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: TransactionsWeb Panels, Procedures

Generators: C/SQL (only SMTPSession and POP3Session), Java, .NET, .NET Framework (only SMTPSession, and POP3Session)

Description

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

Data type

Description

Requirements

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.

The SMTPSession, 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.

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 property

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.

 

Error Codes and Messages

The possible values are:  (I=SMTPSession/POP3Session):

Code

Message

Modes

0

Ok

I

1

Already logged in

I

2

Not logged in

I

3

Could not complete login

I

6

Invalid sender name

I

7

Invalid sender address

I

8

Invalid user name

I

9

Invalid password

I

10

Could not send message

I

11

No messages to receive

I

12

Could not delete message

I

13

No main recipient specified

I

14

Invalid recipient

I

15

Invalid attachment

I

16

Could not save attachment

I

17

Invalid Authentication value

I

18

Not enough memory

I

19

Connection lost

I

20

Timeout exceeded

I

21

Memory allocation error

I

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

I

27

Invalid NewMessages value

I

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.

Examples

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

 

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



  

Last update: February 2024 | © GeneXus. All rights reserved. GeneXus Powered by Globant