Data Types for Email handling

Unofficial Content

The purpose of these data types is to unify the functions of interaction with the sending and receiving of messages for the different generate languages.

A very important advantage of this implementation, compared to the previous ones, is that it allows using more than one instance of connection to the email server.

Scope

Objects: Transactions, Work Panels, Web Panels, Procedures, Reports

Languages: C/SQL (only SMTPSession and POP3Session), Java, Visual Basic , Visual FoxPro, C# (only OutlookSession, SMTPSession, and POP3Session)

Interface: Win, Web

Description

To use this new functionality the following data types have been created:

Data type

Description

Requirements

OutlookSession

Allows you to use an email session to send and receive messages with Microsoft Outlook.

Microsoft Outlook 97 or higher.

MAPISession

 

Allows you to send/receive emails with MAPI (Mail Application Program Interface) by Microsoft.

Note: We don’t recommend using this mode unless you wish to use the Microsoft Exchange Server services and don’t have Microsoft Outlook.

Microsoft Outlook 97 or higher or Microsoft Exchange Client, and Collaboration Data Objects (CDO) 1.2 or higher.

Note: The CDOs 1.2 come with the following products:
- MS Outlook 98 and MS Outlook 2000 (Version 1.21).
- MS Exchange 5.5 Server (Version 1.2 or Version 1.21 in SP1 or higher).

SMTPSession

Allows you to use an email session to send messages through a server using the SMTP (Simple Mail Transfer Protocol).

TCP/IP protocol. Doesn’t require Office.

POP3Session

Allows you to use an email session to receive messages from a server using POP3 (Post Office Protocol Version 3).

TCP/IP protocol. Doesn’t require Office.

MailMessage

Allows you to configure the message that will be sent/received, through different properties and methods.

 

MailRecipient

Allows you to configure the name and address of the recipient of a message.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The OutlookSessionMAPISessionSMTPSession, and POP3Session data types indicate the mode in which the sending and receiving of emails will be carried out.

Furthermore, internally you can work with the following data types:

MailRecipientCollection

 Collection MailRecipient objects.

StringCollection

 Collection of  Character objects.

 

 

 

OutlookSession

The properties and methods available for this data type are the following:

Property

Type

Access

AttachDir

Character

Reading/Writing

Count

Numeric

Reading

EditWindow

Numeric (0 | 1)

Reading/Writing

ErrCode

Numeric

Reading

ErrDescription

Character

Reading

ErrDisplay

Numeric (0 | 1)

Reading/Writing

NewMessages

Numeric (0 | 1)

Reading/Writing

 

 

 

 

 

 

 

 

 

 

Method

Parameters

Type

ChangeFolder

FolderName

Character

Delete

(none)

 

MarkAsRead

(none)

 

Receive

Message

MailMessage

Send

Message

MailMessage

 

 

 

 

 

 

 

 

PROPERTIES

AttachDir

Attachment directory.

Syntax:    &OutlookSession.AttachDir

Specifies in which directory the attached files must be saved when the Receive method is executed. If this property contains an empty chain (“”), the attached files won’t be saved.

In the case of the Send method, it will be taken as the base directory for searching files attached to the message (Attachments property).

The default value is an empty chain ( “”).

 

Count

Number of messages to be received.

Syntax:   &OutlookSession.Count

Returns the quantity of messages which comply with the conditions of the folder opening. That is to say, if the folder or session was opened specifying that only the unread messages should be received (through the use of the NewMessages property), it will return the number of unread messages; while if the folder was opened specifying that all messages should be received, then it will return the total number of messages.  

 

EditWindow

Indicates whether or not the message editing window will be shown before sending it.  

Syntax:   &OutlookSession.EditWindow

If EditWindow = 1, then the message editing window will be shown each time the Send property is invoked. If it’s 0, the message will be sent without user interaction.

The default value is 0.

 

ErrCode

Error code of the last operation.

Syntax: &OutlookSession.ErrCode

See the section “Error Codes and Messages” of this document. 

 

ErrDescription

Error message of the last operation. The message list details can be found in the ErrorNumber property.

Syntax: &OutlookSession.ErrDescription

See the section “Error Codes and Messages” of this document. 

 

ErrDisplay

Indicates whether or not error messages will be displayed.

Syntax:   &OutlookSession.ErrDisplay

Specifies whether or not, when an error occurs, an error message will be displayed, warning the user with the error text. If ErrDisplay=1 then the message will be displayed, while if it’s 0 then it won’t.  

The default value is 0.

 

NewMessages

Indicates if only new messages or all messages will be received.

Syntax:            &OutlookSession.NewMessages

If NewMessages=1 then Receive method will return only the unread messages of the current folder. If it’s 0, then it will return all the messages of said folder.

The default value is 0.

This property’s value will be effective from the next call to the ChangeFolder method.

If the server doesn’t support the property NewMessages=1 the error 29 will occur.

 

METHODS

ChangeFolder

Changes the folder from which messages will be received.

Syntax:            &Error = &OutlookSession.ChangeFolder(FolderName)

FolderName is the name of the folder from which the emails will be read. Look at Notes to know the rules when defining folder names.

This parameter is optional; if it’s omitted or left blank, the Inbox folder will be referenced.

Notes:

-          Rules for the correct definition of folder names. The notation is similar to the one used in DOS and UNIX to navigate directories, with some exceptions.

In general, the rules are as follows:

-          You can use the “.” character to indicate the current folder.

-          You can use the “..” chain to indicate the folder of a higher level.  

-          You can use the “\” character to indicate a subfolder.  

-          You can use the “\” character at the beginning of the folder name to indicate the root.

-         If a simple name is specified, without “\” or “..”, an Inbox sister folder will be referenced.

-          The values “*Inbox”, “*Outbox”, “*Sent Items”, “*Deleted Items” y “*Drafts” are used to reference the folders commonly called those names, even if their names are not exactly the same. This is useful when you use a client in another language. For example, if you have Outlook in Spanish, “Inbox” will reference the “Bandeja de entrada” folder.

For example, if you have the following structure:

Mailbox

Drafts

                          Inbox

                        Urgent       

Outbox

                              Pending

Waitlisted

Sent Items

Public Folders

Favorites

                    All Public Folders

General

The following FolderName values are valid:

“Pending”

“Pending\Waitlisted”

“\Mailbox\Pending”

 “\Public Folders\All Public Folders\General”

“*Inbox\Urgent”

If the Inbox\Urgent folder is currently selected:

-         “..” (Selects Inbox)

-         “..\..\Pending\Waitlisted”

If the Inbox folder is currently selected:

“.\Urgent”

 

Delete

Deletes from the server the last message that was received with the Receive method.

Syntax:            &OutlookSession.Delete()

The deleted message will be moved to the “Deleted Items” folder.

If the Receive method hasn’t been called, or if the last call did not return a message (because of an error, for example), calling the Delete method will return error 26.

 

MarkAsRead

Marks as read the last message that was received with the Receive method.

Syntax:   &OutlookSession.MarkAsRead()

If the Receive method hasn’t been called, or if the last call did not return a message (because of an error, for example), calling the MarkAsRead method will return error 26.

This property must be configured after performing the Receive.

 

Receive

Returns the data of the next email in the current session.

If the email has attachments, and a directory was specified in the AttachDir property, they will be saved to disk; otherwise they won’t be saved.

Syntax:            &OutlookSession.Receive(Message)

 

Note:

-          The Message parameter is of the MailMessage data type.

 

Send

Sends a message.

Syntax:            &OutlookSession.Send(Message)

 

Notes:

-          The Message parameter is of the MailMessage data type.

-          If one destination address cannot be resolved, the editing window will be displayed, as if the EditWindow property was set to 1.

 

MAPISession

The available properties and methods for this data type are the following:

Property

Type

Access

AttachDir

Character

Reading/Writing

Count

Numeric

Reading

EditWindow

Numeric (0 | 1)

Reading/Writing

ErrCode

Numeric

Reading

ErrDescription

Character

Reading

ErrDisplay

Numeric (0 | 1)

Reading/Writing

NewMessages

Numeric (0 | 1)

Reading/Writing

Profile

Character

Reading/Writing

 

 

 

 

 

 

 

 

 

 

Method

Parameters

Type

ChangeFolder

FolderName

Character

Delete

(none)

 

Login

(none)

 

Logout

(none)

 

MarkAsRead

(none)

 

Receive

Message

MailMessage

Send

Message

MailMessage

 

 

 

 

 

 

 

 

 

PROPERTIES

AttachDir

Attachment directory.

Syntax:            &MAPISession.AttachDir

Specifies in which directory the attached files must be saved when the Receive method is executed. If this property contains an empty chain (“”), the attached files won’t be saved.

In the case of the Send method, it will be taken as the base directory for searching files attached to the message (Attachments property).

The default value is an empty chain ( “”).

 

Count

Number of messages to be received.

Syntax:   &MAPISession.Count

Returns the quantity of messages which comply with the conditions of the folder opening. That is to say, if the folder or session was opened specifying that only the unread messages should be received (through the use of the NewMessages property), it will return the number of unread messages; while if the folder was opened specifying that all messages should be received, then it will return the total number of messages.  

 

EditWindow

Indicates whether or not the message editing window will be shown before sending it. 

Syntax:   &MAPISession.EditWindow

If EditWindow = 1, then the message editing window will be shown each time the Send property is invoked. If it’s 0, the message will be sent without user interaction.

The default value is 0.

 

ErrCode

Error code of the last operation.

Syntax:   &MAPISession.ErrCode

See the section “Error Codes and Messages” of this document. 

 

ErrDescription

Error message of the last operation. The message list details can be found in the ErrCode property.

Syntax:  &MAPISession.ErrDescription

See the section “Error Codes and Messages” of this document. 

 

ErrDisplay

Indicates whether or not error messages will be displayed.

Syntax:    &MAPISession.ErrDisplay

Specifies whether or not, when an error occurs, an error message will be displayed, warning the user with the error text. If ErrDisplay=1 then the message will be displayed, while if it’s 0 then it won’t. 

The default value is 0.

 

NewMessages

Indicates if only new messages or all messages will be received.

Syntax:     &MAPISession.NewMessages

If NewMessages=1 then Receive method will return only the unread messages of the current folder. If it’s 0, then it will return all the messages of said folder.

The default value is 0.

This property’s value will be effective from the next call to the ChangeFolder method.

If the server doesn’t support the property NewMessages=1 the error 29 will occur.

 

Profile

Profile used to begin a session.

Syntax:  &MAPISession.Profile

This prpoerty’s value will be effective from the next call to the Login method. If this property is not specified, then the Login method will show a profile selection window.

 

METHODS

ChangeFolder

Changes the folder from which messages will be received.

Syntax:    &MAPISession.ChangeFolder(FolderName)

FolderName is the name of the folder from which the emails will be read. Look at Notes to know the rules when defining folder names.

This parameter is optional; if it’s omitted or left blank, the Inbox folder will be referenced

 

Delete

Deletes from the server the last message that was received with the Receive method.

Syntax:    &MAPISession.Delete()

The deleted message will be moved to the “Deleted Items” folder.

If the Receive method hasn’t been called, or if the last call did not return a message (because of an error, for example), calling the Delete method will return error 26.

 

Login

Logs-in (starts) a session.

Syntax:     &MAPISession.Login

The MAPI session will begin with the profile indicated in the Profile property. If said property hasn’t been assigned then a window will open asking what profile to use.  

After logging in a session with the specified profile, the “Inbox” folder (or equivalent) opens.  

 

Logout

Logs out of (ends) a session.

Syntax:     &MAPISession.Logout

 

MarkAsRead

Marks as read the last message that was received with the Receive method.

Syntax:            &MAPISession.MarkAsRead

If the Receive method hasn’t been called, or if the last call did not return a message (because of an error, for example), calling the MarkAsRead method will return error 26.

Note:

-        To be able to use this method you must configure the preference “Functions = Allow non standard functions” in design and prototype.

 

Receive

Returns the data of the next email in the current session.

If the email has attachments, and a directory was specified in the AttachDir property, they will be saved to disk; otherwise they won’t be saved.

Syntax:  &MAPISession.Receive(Message)

Note:

-          The Message parameter is of the MailMessage data type.

 

Send

Sends a message.

Syntax: &MAPISession.Send(Message)

Notes:

-          The Message parameter is of the MailMessage data type.

-          If the address of one of the recipients cannot be solved, a window will open, letting the user choose the recipient from a list of possible recipients for the specified address.  

-          Emails are forcefully sent after performing a Send. As a consequence, if you are using a phone connection to Internet, the dialing will be carried out when you call this method.

 

SMTPSession

The available properties and methods for this data type are the following:

Property

Type

Access

AttachDir

Character

Reading/Writing

Authentication

Numeric (0 | 1)

Reading/Writing

ErrCode

Numeric

Reading

ErrDescription

Character

Reading

ErrDisplay

Numeric (0 | 1)

Reading/Writing

Host

Character

Reading/Writing

Password

Character

Writing

Port

Numeric

Reading/Writing

Sender

MailRecipient

Reading/Writing

Timeout

Numeric

Reading/Writing

UserName

Character

Reading/Writing

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Method

Parameters

Type

Login

(none)

 

Logout

(none)

 

Send

Message

MailMessage

 

 

 

 

 

PROPERTIES

AttachDir

Attachment directory.

Syntax:  &SMTPSession.AttachDir

Specifies which directory will be used for searching attachments to messages (Attachments property).

The default value is an empty chain (“”).

 

Authentication

Indicates whether or not to try authentication with the server.

Syntax:  &SMTPSession. Authentication

Some SMTP servers require authentication. In these cases you can set the Authentication property to 1 and specigy in the UserName and Password properties thw username and password to be used. These values will be taken into account in the next call to the Login method.

The only authentication mechanism is Clear Text. If you specify the paramaters UserName and Password and the server does not support Clear Text authentication, then the method will return the error 23

The default value is 0.

 

ErrCode

Error code of the last operation.

Syntax: &SMTPSession.ErrCode

See the section “Error Codes and Messages” of this document. 

 

ErrDescription

Error message of the last operation. The message list details can be found in the ErrCode property.

Syntax:  &SMTPSession.ErrDescription

See the section “Error Codes and Messages” of this document. 

 

ErrDisplay

Indicates whether or not error messages will be displayed.

Syntax:   &SMTPSession.ErrDisplay

Specifies whether or not, when an error occurs, an error message will be displayed, warning the user with the error text. If ErrDisplay=1 then the message will be displayed, while if it’s 0 then it won’t. 

The default value is 0.

Note:

-          This property is not available in the C/SQL generator.

 

Host

Address of the SMTP server.

Syntax:   &SMTPSession.Host

You can specify the server name and its address.

 

Password

Password used for authentication in the server

Syntax:    &SMTPSession.Password

This property will be ignored if the Authentication property is set to 0. 

 

Port

Port of the SMTP server in the Host.

Syntax:   &SMTPSession.Port

The default value is 25, the port normally used by STMP servers.

 

Sender

Data from the sender, to be included in the sent messages.

Syntax:  &SMTPSession.Sender

When you create a variable of the SMTPSession type, the Sender property contains a MailRecipient object with the Name and Address properties empty. For this reason, the sender’s data can be directly assigned to the Name and Address properties of the already-created object, or another object of the MailRecipient type can be assigned, from which these properties will be copied.

For the Login method to work, it’s necessary to have valid values in the Sender property.

 

Timeout

Maximum time, in seconds, to wait for an answer from the server after each request.

Syntax:  &SMTPSession.Timeout

This value must adapt to the speed of the communications network and the server’s load. For local networks you must use small values, and bigger values if you’re using Internet, especially if you are connecting to very remote servers.

The default value is 30.

 

UserName

Username used for authentication in the server.                  

Syntax:   &SMTPSession.UserName

This property will be ignored if the Authentication property is set to 0. 

 

METHODS

Login

Begins a session with an SMTP server.

Syntax:    &SMTPSession.Login

The SMTP session will begin with the server specified in the Host property in the port specified in the Port property. The values in the UserName and Password properties will be used for authentication with the server.

 

Logout

Ends the session with an SMTP server.

Syntax:   &SMTPSession.Logout

 

Send

Sends a message.

Syntax:      &SMTPSession.Send(Message)

Notes:

-          The Message parameter is of the MailMessage type.

 

POP3Session

The available properties and methods for this data type are the following:

Property

Type

Access

AttachDir

Character

Reading/Writing

Count

Numeric

Reading

ErrCode

Numeric

Reading

ErrDescription

Character

Reading

ErrDisplay

Numeric (0 | 1)

Reading/Writing

Host

Character

Reading/Writing

NewMessages

Numeric (0 | 1)

Reading/Writing

Password

Character

Writing

Port

Numeric

Reading/Writing

Timeout

Numeric

Reading/Writing

UserName

Character

Reading/Writing

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Method

Parameters

Type

Delete

(none)

 

Login

( none )

 

Logout

( none )

 

Receive

Message

MailMessage

 

 

 

 

 

 

 

PROPERTIES

AttachDir

Attachment directory.

Syntax:    &POP3Session.AttachDir

Specifies the directory in which to save attachments when the Receive method is executed. If this property contains an empty chain (“”), attachments won’t be saved.   

The default value is an empty chain (“”).

 

Count

Cantidad de mensajes a recibir.

Syntax:  &POP3Session.Count

Returns the quantity of messages which comply with the conditions of the folder opening. That is to say, if the folder or session was opened specifying that only the unread messages should be received (through the use of the NewMessages property), it will return the number of unread messages; while if the folder was opened specifying that all messages should be received, then it will return the total number of messages. 

 

ErrCode

Error code of the last operation.

Syntax: &POP3Session.ErrCode

See the section “Error Codes and Messages” of this document. 

 

ErrDescription

Error message of the last operation. The message list details can be found in the ErrCode property.

Syntax:    &Error = &POP3Session.ErrDescription

See the section “Error Codes and Messages” of this document. 

 

ErrDisplay

Indicates whether or not error messages will be displayed.

Syntax:   &POP3Session.ErrDisplay

Specifies whether or not, when an error occurs, an error message will be displayed, warning the user with the error text. If ErrDisplay=1 then the message will be displayed, while if it’s 0 then it won’t. 

The default value is 0.

Note:

-          This property is not available in the C/SQL generator.

 

Host

Address of the POP3 server.

Syntax:    &POP3Session.Host

You can specify both the server’s name and its IP address.

 

NewMessages

Indicates whether all messages or only new messages will be received.

Syntax:    &POP3Session.NewMessages

If NewMessages= 1 the calls to the Receive method will return only the unread messages of the current folder. If it’s 0, it will return all the messages of the folder.  

The default value is 0.

This property will be effective as of the next call to the Login method.

The most recent implementations of POP3 servers do not have the necessary mechanism for the correct functioning of this property when it has value 1. In the case that the Login method is called specifying in the Host property a server that does not have said mechanism and this property has value 1, it will return error 29.

 

Password

Password used for authentication in the server

Syntax:   &POP3Session.Password

 

Port

Port of the POP3 server in the Host.

Syntax:   &POP3Session.Port

The default value is 110, the port normally used by POP3 servers.

 

Timeout

Maximum time, in seconds, to wait for an answer from the server after each request.

Syntax:    &POP3Session.Timeout

This value must adapt to the speed of the communications network and the server’s load. For local networks you must use small values, and bigger values if you’re using Internet, especially if you are connecting to very remote servers.

The default value is 30.

 

UserName

Username used for authentication in the server.

Syntax:     &SMTPSession.UserName

 

METHODS

Delete

Deletes the last message that was received with the Receive method from the server.

Syntax:   &POP3Session.Delete()

The message is permantently deleted, and this is performed when the Logout method is executed.

If the Receive method has not been called, or if the last call didn’t return a message (for example, because of an error), calling the Delete method will return error 26.  

 

Login

Begins a session with POP3 serve.

Syntax:     &POP3Session.Login

The POP3 session will begin with the server specified in the Host property in the port specified in the Port property. The values in the UserName and Password properties will be used for authentication with the server.

 

Logout

Ends the session with a POP3 server.

Syntax:    &POP3Session.Logout

 

Receive

Receives a message.

Syntax: &POP3Session.Receive(Message)

Returns the data of the next email in the current session or folder.

If the email has attachments, and a directory was specified in the AttachDir property, they will be saved to disk

Note:

-         The Message parameter is of the MailMessage data type.

 

MailMessage                                                

The available properties for this data type are the following:

Property

Type

Access

Attachments

StringCollection

Reading

BCC

MailRecipientCollection

Reading

CC

MailRecipientCollection

Reading

DateReceived

DateTime

Reading

DateSent

DateTime

Reading

From

MailRecipient

Reading/Writing

HTMLText

Character

Reading/Writing

Subject

Character

Reading/Writing

Text

Character

Reading/Writing

To

MailRecipientCollection

Reading

 

 

 

 

 

 

 

 

 

 

 

 

 

PROPERTIES

Attachments

List of the message’s attachments’ names.

If a complete path is not specified, when sending a message, it will look for the attachments in the directory specified in the AttachDir property.

Syntax:   &Message.Attachments

Note:

-          If the SMTP mode is used: In the attachments’ path you can use both the slash (/) and the backslash (\) as a directory separator. In this way, we offer compatibility between the UNIX and Windows environments.

BCC

List of hidden recipients (Blind Carbon Copy) of a message.

Syntax:    &Message.BCC

 

CC

List of secondary recipients (Carbon Copy) of a message.

Syntax:  &Message.CC

 

DateReceived

Date and time when the server received the message.

Syntax:    &Message.DateReceived

 

DateSent

Date and time when the message was sent.

Syntax:  &Message.DateSent

 

From

The message’s sender.

Syntax:  &Message.From

 

HTMLText

Body of the message in HTML (HyperText Markup Language) format.

Syntax:   &Message.HTMLText

Notes:

-          MAPI: This property is not supported if it’s used in MAPI mode.  

-          Outlook: Even though this property is supported in Outlook, it is not possible to handle a message with content in simple text and HTML at the same time. The final content will be the last one assigned. When you receive a message with HTML content the Text property will contain the same text as the HTMLText property but with no format (omitting the HTML tags).

-          SMTP/POP3:  It is possible to handle messages with content in simple text and HTML at the same time. If you send a message of this type, the client who receives it will, whenever possible, show the HTML content. If the client is not capable of handling HTML content, the content will be shown in simple text.

 

Subject

The message’s subject.

Syntax:     &Message.Subject

 

Text

The message’s body in simple text format.

Syntax:   &Message.Text


To

Collection of primary recipients of the message.

Syntax:   &Message.To

 

MailRecipient

The available properties for this data type are the following:

Property

Type

Access

Name

Character

Reading/Writing

Adress

Character

Reading/Writing

 

 

 

 

PROPERTIES

Name

Name of the recipient.

Syntax:            &Recipient.Name

If a value is not specified for the Name property, the content of the Address property is copied for this property.

 

Address

Email address of the recipient

Syntax:            &Recipient.Address

Note:

-          Outlook: This property is not supported in Outlook, when receiving an email, for the properties To, CC, BCC, and From, In these cases the Address property comes with the same value as the Name property.
 

MailRecipientCollection

The available properties and methods for this data type are the following:

Property

Type

Access

Count

Numeric

Reading

 

 

 

Method

Parameters

Type

Add

Recipient

MailRecipient

Clear

(none)

 

Item

Index

Numeric

New

Name

Address

Character

Character

 

 

 

 

 

 

 

PROPERTIES

Count

Number of elements in the collection.

Syntax:            &Message(...).Count

 

METHODS

Add

Adds a MailRecipient object to the collection.

Syntax:    &Message(...).Add(Recipient)

If the object is copied, and if hence the properties of the MailRecipient object are modified after calling the Add method, the element in the collection will continue to have the properties it had when the Add method was called.

If the object passed by parameter has an empty chain in the Address property, the call to the Add method is ignored.  

If the object passed by paraemter has an empty chain in the Name property, then the Name property of the copy that will be created in the collection will be the same as its Address property.  

 

Clear

Empties the collection. All elements in the collection are deleted.

Syntax:  &Message(...).Clear()

 

Item

Returns a MailRecipient object stored in the collection.

Syntax:  &Message(...).Item(Index)

Index must be between 1 and the value of the Count property.  

 

New

Returns a MailRecipient object stored in the collection.

Syntax:   &Message(...).New(Name, Address)

Creates a new MailRecipient object inside a collection, with the name and address specified in the Name and Address parameters respectively.

If the Address parameter is an empty chain, the call to the New method is ignored.

If the Name parameter is an empty chain, the new object created in the collection will have the Name property equal to the Address property.

 

 

StringCollection

Property

Type

Access

Count

Numeric

Reading

 

 

 

Method

Parameters

Type

Add

String

Character

Clear

(none)

 

Item

Index

Numeric

 

 

 

 

 

PROPERTIES

Count

Number of elements in the collection.

Syntax: &Message(...).Count

 

METHODS

Add

Adds a MailRecipient object to the collection.

Syntax:   &Message(...).Add(String)

The object is copied, and hence if the properties of the MailRecipient object are modified after calling the Add method, the element in the collection will continue to have the properties it had when the Add method was called.

If the String parameter is an empty chain, the call to the Add method is ignored.

 

Clear

Empties the collection. All elements in the collection are deleted.

Syntax:    &Message(...).Clear()

 

Item

Returns a MailRecipient object stored in the collection.

Syntax: &Message(...).Item(Index)

Index must be between 1 and the value of the Count property.

 

Error Codes and Messages

The possible values are: (O=OutlookSession, I=SMTPSession/POP3Session, M=MAPISession):

Code

Message

Modes

0

Ok

O/I/M

1

Already logged in

I/M

2

Not logged in

I/M

3

Could not complete login

I/M

4

Could not start Outlook.

O

5

Could not open folder

O/M

6

Invalid sender name

I

7

Invalid sender address

I

8

Invalid user name

I

9

Invalid password

I

10

Could not send message

O/I/M

11

No messages to receive

O/I/M

12

Could not delete message

I

13

No main recipient specified

O/I/M

14

Invalid recipient

O/I/M

15

Invalid attachment

O/I/M

16

Could not save attachment

O/I/M

17

Invalid Authentication value

I

18

Not enough memory

I

19

Connection lost

I

20

Timeout exceeded

I

21

Memory allocation error

I

22

Error receiving message

O/M

23

The server does not recognize any of the supported authentication methods

I

24

Authentication error

I

25

User or password refused

I

26

No current message

O/I/M

27

Invalid NewMessages value

O/I/M

28

Invalid EditWindow value

O/M

29

POP3 server does not support NewMessages = 1

I

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

General considerations

-          The methods previously described were implemented so that they return error codes (as if they were functions), so it is possible to call them as functions.

For Example:

&Err = &OutlookSession.Send(Message)

 

Examples

Shown below are examples of events in GeneXus which allow the sending and receiving of emails with the different data types (OutlookSession, MAPISession, and SMTPSession/POP3Session)

 

OutlookSession

The &Send and &Receive variables must be defined as MailMessage type, and &Message must be of the OutlookSession type; the &AddressTo and &AddressCC must be of the MailRecipient type.

s &Send y &Receivedeben estar definidas de tipo MailMessage, &Message debe ser de tipo OutlookSession y las variables &AddressTo y &AddressCC deben ser de tipoMailRecipient.

 

Event 'Send'

    &AddressTo.Address = ‘isidoro@cañones.com

    &AddressTo.Name = ‘Isidoro Cañones’

    &Send.To.Clear()

    &Send.To.Add(&AddressTo)


    &AddressCC.Address = ‘cachorra@bazuka.com

    &AddressCC.Name = ‘Cachorra Bazuka’

    &Send.Cc.Clear()

    &Send.Cc.Add(&AddressCC)


    &Send.Subject = ‘You’re invited to my party’

    &Send.HTMLText = ‘Next Saturday I celebrate my birthday, do not miss it!’


    &Message.Editwindow = 1

    // If Outlook is used, it is not necessary to use the Login method, you can use the Send method directly.

 

    &Message.Send(&Send)

    if &Message.ErrCode <> 0

        msg(&Message.ErrDescription)

    endif

EndEvent


Event 'Receive'

    &Message.NewMessages = 1 

    &Message.ChangeFolder("Inbox")

    &Message.Attachdir = ‘d:\archivos’


    // Receive the message

    &Message.Receive(&Receive)

    &Message.MarkAsRead()

    &From = &Receive.From.Address()

    &Sub = &Receive.Subject()

    &Texthtml = &Receive.HTMLText()

EndEvent

 

MAPISession

The  &Send and &Receive variable must be defined as MailMessage type, &Message must be a MAPISession type, and the &AddressTo and &AddressCC variables musy ne of the MailRecipient type.

 

Event 'Send'

    &AddressTo.Address = ‘isidoro@cañones.com

    &AddressTo.Name = ‘Isidoro Cañones’

    &Send.To.Clear()

    &Send.To.Add(&AddressTo)


    &AddressCC.Address = ‘cachorra@bazuka.com

    &AddressCC.Name = ‘Cachorra Bazuka’

    &Send.Cc.Clear()

    &Send.Cc.Add(&AddressCC)


    &Send.Subject = ‘You’re invited to my party’

    &Send.HTMLText = ‘Next Saturday I celebrate my birthday, do not miss it!’


    // In the 'M' mode, you must perform the login, send the message, and perform the logout.  

    &Message.Profile = ‘My profile’

    &Message.Editwindow = 1

    

    &Message.Login()

    &Message.Send(&Send) 

    if &Message.ErrCode <> 0

        msg(&Message.ErrDescription)

    endif   

       

    &Message.Logout()

EndEvent


Event ‘Receive’

    &Message.Attachdir = ‘d:\archivos’

    &Message.NewMessages = 1

    &Message.Profile = ‘My profile’


    &Message.Login()

    &Message.Receive(&Receive)

    &Message.MarkAsRead()

    &Sub = &Receive.Subject()

    &Texthtml = &Receive.HTMLText()

    &From = &Receive.From.Address()

    &Datesen = &Receive.DateSent()

    &Daterec = &Receive.DateReceived()

    &Message.Logout()

EndEvent

 

SMTPSession/POP3Session

The  &Send and &Receive variable must be defined as MailMessage type, &MessageSMTP must be a SMTPSession type, &MessagePOP3 of the POP3Session type,  and the &AddressTo and &AddressCC variables musy ne of the MailRecipient type.

 

Event 'Send'

    &AddressTo.Address = ‘isidoro@cañones.com

    &AddressTo.Name = ‘Isidoro Cañones’

    &Send.To.Clear()

    &Send.To.Add(&AddressTo)


    &AddressCC.Address = ‘cachorra@bazuka.com

    &AddressCC.Name = ‘Cachorra Bazuka’

    &Send.Cc.Clear()

    &Send.Cc.Add(&AddressCC)


    &Send.Subject = ‘You’re invited to my party’

    &Send.HTMLText = ‘Next Saturday I celebrate my birthday, do not miss it!’


    // The SMTP server used in this case does not need authentication.

    &MessageSMTP.Host = ‘SMTP Server’

    &MessageSMTP.Sender.Name = ‘Patoruzu’

    &MessageSMTP.Sender.Address = ‘patoruzu@hotmail.com’

    &MessageSMTP.Authentication = 1

    &MessageSMTP.UserName = ‘My user’

    &MessageSMTP.Password = ‘My password’

      

    &MessageSMTP.Login()

    &MessageSMTP.Send(&Send) 

    if &MessageSMTP.ErrCode <> 0

        msg(&MessageSMTP.ErrDescription)

    endif   

       

    &MessageSMTP.Logout()


EndEvent


Event 'Receive’

    &MessagePOP3.Host = ‘POP3 Server’

    &MessagePOP3.UserName = ‘My user’

    &MessagePOP3.Password = &pass

    &MessagePOP3.NewMessages = 1


    &MessagePOP3.Login()

    &MessagePOP3.Receive(&Receive)

    &From = &Receive.From.Address()

    &Datesen = &Receive.DateSent()

    &Daterec = &Receive.DateReceived()

    &Sub = &Receive.Subject()

    &Texthtml = &Receive.HTMLText()

EndEvent