Skip to main content
Version: v20 R4 BETA

SMTPTransporter

The SMTPTransporter class allows you to configure SMTP connections and send emails through SMTP transporter objects.

SMTP Transporter object

SMTP Transporter objects are instantiated with the SMTP New transporter command. They provide the following properties and functions:

.acceptUnsecureConnection : Boolean    True if 4D is allowed to establish an unencrypted connection
.authenticationMode : Text    the authentication mode used to open the session on the mail server
.bodyCharset : Text     the charset and encoding used for the body part of the email
.checkConnection() : Object     checks the connection using information stored in the transporter object
.connectionTimeOut : Integer    the maximum wait time (in seconds) allowed to establish a connection to the server
.headerCharset : Text     the charset and encoding used for the email header
.host : Text    the name or the IP address of the host server
.keepAlive : Boolean    True if the SMTP connection must be kept alive until the transporter object is destroyed
.logFile : Text    the path of the extended log file defined (if any) for the mail connection
.port : Integer     the port number used for mail transactions
.send( mail : Object ) : Object    sends the mail object to the SMTP server defined in the transporter object and returns a status object
.sendTimeOut : Integer     the maximum wait time (in seconds) of a call to .send( ) before a timeout occurs
.user : Text     the user name used for authentication on the mail server

SMTP New transporter

History
VersionChanges
v18New logFile property
v17 R5New bodyCharset and headerCharset properties
v17 R4Added

SMTP New transporter( server : Object ) : 4D.SMTPTransporter

ParameterTypeDescription
serverObject->Mail server information
Result4D.SMTPTransporter<-SMTP transporter object

Description

The SMTP New transporter command configures a new SMTP connection according to the server parameter and returns a new SMTP transporter object. The returned transporter object will then usually be used to send emails.

This command does not open any connection to the SMTP server. The SMTP connection is actually opened when the .send() function is executed.

The SMTP connection is automatically closed:

  • when the transporter object is destroyed if the keepAlive property is true (default),
  • after each .send( ) function execution if the keepAlive property is set to false.

In the server parameter, pass an object containing the following properties:

serverDefault value (if omitted)
.acceptUnsecureConnection : Boolean    True if 4D is allowed to establish an unencrypted connectionFalse
.accessTokenOAuth2: Text
.accessTokenOAuth2: Object
Text string or token object representing OAuth2 authorization credentials. Used only with OAUTH2 authenticationMode. If accessTokenOAuth2 is used but authenticationMode is omitted, the OAuth 2 protocol is used (if allowed by the server). Not returned in SMTP transporter object.
none
.authenticationMode : Text    the authentication mode used to open the session on the mail serverthe most secure authentication mode supported by the server is used
.bodyCharset : Text     the charset and encoding used for the body part of the emailmail mode UTF8 (US-ASCII_UTF8_QP)
.connectionTimeOut : Integer    the maximum wait time (in seconds) allowed to establish a connection to the server30
.headerCharset : Text     the charset and encoding used for the email headermail mode UTF8 (US-ASCII_UTF8_QP)
.host : Text    the name or the IP address of the host servermandatory
.keepAlive : Boolean    True if the SMTP connection must be kept alive until the transporter object is destroyedTrue
.logFile : Text    the path of the extended log file defined (if any) for the mail connectionnone
password : Text
User password for authentication on the server. Not returned in SMTP transporter object.
none
.port : Integer     the port number used for mail transactions587
.sendTimeOut : Integer     the maximum wait time (in seconds) of a call to .send( ) before a timeout occurs100
.user : Text     the user name used for authentication on the mail servernone

Result

The function returns a SMTP transporter object. All returned properties are read-only.

Example

 $server:=New object
$server.host:="smtp.gmail.com" //Mandatory
$server.port:=465
$server.user:="4D@gmail.com"
$server.password:="XXXX"
$server.logFile:="LogTest.txt" //Extended log to save in the Logs folder

var $transporter : 4D.SMTPTransporter
$transporter:=SMTP New transporter($server)

$email:=New object
$email.subject:="my first mail "
$email.from:="4d@gmail.com"
$email.to:="4d@4d.com;test@4d.com"
$email.textBody:="Hello World"
$email.htmlBody:="<h1>Hello World</h1><h4>'Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit...'</h4>\
<p>There are many variations of passages of Lorem Ipsum available."\
+"The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc.</p>"

$status:=$transporter.send($email)
If(Not($status.success))
ALERT("An error occurred sending the mail: "+$status.message)
End if

4D.SMTPTransporter.new()

4D.SMTPTransporter.new( server : Object ) : 4D.SMTPTransporter

ParameterTypeDescription
serverObject->Mail server information
Result4D.SMTPTransporter<-SMTP transporter object

Description

The 4D.SMTPTransporter.new() function creates and returns a new object of the 4D.SMTPTransporter type. It is identical to the SMTP New transporter command (shortcut).

.acceptUnsecureConnection

History
VersionChanges
v17 R4Added

.acceptUnsecureConnection : Boolean

Description

The .acceptUnsecureConnection property contains True if 4D is allowed to establish an unencrypted connection when encrypted connection is not possible.

It contains False if unencrypted connections are unallowed, in which case an error in returned when encrypted connection is not possible.

Available secured ports are:

  • SMTP

    • 465: SMTPS
    • 587 or 25: SMTP with STARTTLS upgrade if supported by the server.
  • IMAP

    • 143: IMAP non-encrypted port
    • 993: IMAP with STARTTLS upgrade if supported by the server
  • POP3

    • 110: POP3 non-encrypted port
    • 995: POP3 with STARTTLS upgrade if supported by the server.

.authenticationMode

History
VersionChanges
v17 R4Added

.authenticationMode : Text

Description

The .authenticationMode property contains the authentication mode used to open the session on the mail server.

By default, the most secured mode supported by the server is used.

Possible values are:

ValueConstantsComment
CRAM-MD5SMTP authentication CRAM MD5Authentication using CRAM-MD5 protocol
LOGINSMTP authentication loginAuthentication using LOGIN protocol
OAUTH2SMTP authentication OAUTH2Authentication using OAuth2 protocol
PLAINSMTP authentication plainAuthentication using PLAIN protocol

.bodyCharset

History
VersionChanges
v18Support for UTF8 base64
v17 R5Added

.bodyCharset : Text

Description

The .bodyCharset property contains the charset and encoding used for the body part of the email.

Possible values:

ConstantValueComment
mail mode ISO2022JPUS-ASCII_ISO-2022-JP_UTF8_QP
  • headerCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & Quoted-printable if possible, otherwise UTF-8 & Quoted-printable
  • bodyCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & 7-bit if possible, otherwise UTF-8 & Quoted-printable
mail mode ISO88591ISO-8859-1
  • headerCharset: ISO-8859-1 & Quoted-printable
  • bodyCharset: ISO-8859-1 & 8-bit
mail mode UTF8US-ASCII_UTF8_QPheaderCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & Quoted-printable (default value)
mail mode UTF8 in base64US-ASCII_UTF8_B64headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & base64

.checkConnection()

History
VersionChanges
v17 R4Added

.checkConnection() : Object

ParameterTypeDescription
ResultObject<-Status of the transporter object connection

Description

The .checkConnection() function checks the connection using information stored in the transporter object, recreates the connection if necessary, and returns the status. This function allows you to verify that the values provided by the user are valid and consistent.

Returned object

The function sends a request to the mail server and returns an object describing the mail status. This object can contain the following properties:

PropertyTypeDescription
successbooleanTrue if the check is successful, False otherwise
statusnumber(SMTP only) Status code returned by the mail server (0 in case of an issue unrelated to the mail processing)
statusTexttextStatus message returned by the mail server, or last error returned in the 4D error stack
errorscollection4D error stack (not returned if a mail server response is received)
[ ].errCodenumber4D error code
[ ].messagetextDescription of the 4D error
[ ].componentSignaturetextSignature of the internal component which returned the error

For information about SMTP status codes, please refer to this page.

Example

 var $pw : Text
var $options : Object
var $transporter : 4D.SMTPTransporter
$options:=New object

$pw:=Request("Please enter your password:")
$options.host:="smtp.gmail.com"

$options.user:="test@gmail.com"
$options.password:=$pw

$transporter:=SMTP New transporter($options)

$status:=$transporter.checkConnection()
If($status.success=True)
ALERT("SMTP connection check successful!")
Else
ALERT("Error # "+String($status.status)+", "+$status.statusText)
End if

.connectionTimeOut

History
VersionChanges
v17 R5Added

.connectionTimeOut : Integer

Description

The .connectionTimeOut property contains the maximum wait time (in seconds) allowed to establish a connection to the server. By default, if the property has not been set in the server object (used to create the transporter object with SMTP New transporter, POP3 New transporter, or IMAP New transporter), the value is 30.

.headerCharset

History
VersionChanges
v17 R5Added

.headerCharset : Text

Description

The .headerCharset property contains the charset and encoding used for the email header. The header includes the following parts of the email:

  • subject,
  • attachment filename(s),
  • email name.

Possible values:

ConstantValueComment
mail mode ISO2022JPUS-ASCII_ISO-2022-JP_UTF8_QP
  • headerCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & Quoted-printable if possible, otherwise UTF-8 & Quoted-printable
  • bodyCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & 7-bit if possible, otherwise UTF-8 & Quoted-printable
mail mode ISO88591ISO-8859-1
  • headerCharset: ISO-8859-1 & Quoted-printable
  • bodyCharset: ISO-8859-1 & 8-bit
mail mode UTF8US-ASCII_UTF8_QPheaderCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & Quoted-printable (default value)
mail mode UTF8 in base64US-ASCII_UTF8_B64headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & base64

.host

History
VersionChanges
v17 R5Added

.host : Text

Description

The .host property contains the name or the IP address of the host server. Used for mail transactions (SMTP, POP3, IMAP).

.keepAlive

History
VersionChanges
v17 R4Added

.keepAlive : Boolean

Description

The .keepAlive property contains True if the SMTP connection must be kept alive until the transporter object is destroyed, and False otherwise. By default, if the keepAlive property has not been set in the server object (used to create the transporter object with SMTP New transporter), it is True.

The SMTP connection is automatically closed:

  • when the transporter object is destroyed if the .keepAlive property is true,
  • after each .send( ) function execution if the .keepAlive property is set to false.

.logFile

History
VersionChanges
v17 R5Added

.logFile : Text

Description

The .logFile property contains the path of the extended log file defined (if any) for the mail connection. It can be relative (to the current Logs folder) or absolute.

Unlike regular log files (enabled via the SET DATABASE PARAMETER command), extended log files store MIME contents of all sent mails and do not have any size limit. For more information about extended log files, refer to:

.port

History
VersionChanges
v17 R4Added

.port : Integer

Description

The .port property contains the port number used for mail transactions. By default, if the port property has not been set in the server object (used to create the transporter object with SMTP New transporter, POP3 New transporter, IMAP New transporter), the port used is:

  • SMTP - 587
  • POP3 - 995
  • IMAP - 993

.send()

History
VersionChanges
v17 R5Support of mime contents
v17 R4Added

.send( mail : Object ) : Object

ParameterTypeDescription
mailObject->Email to send
ResultObject<-SMTP status

Description

The .send() function sends the mail object to the SMTP server defined in the transporter object and returns a status object.

The transporter object must have already been created using the SMTP New transporter command.

The method creates the SMTP connection if it is not already alive. If the .keepAlive property of the transporter object is false, the SMTP connection is automatically closed after the execution of .send(), otherwise it stays alive until the transporter object is destroyed. For more information, please refer to the SMTP New transporter command description.

In mail, pass a valid Email object to send. The origination (where the email is coming from) and destination (one or more recipients) properties must be included, the remaining properties are optional.

Returned object

The function returns an object describing the SMTP status of the operation. This object can contain the following properties:

PropertyTypeDescription
successbooleanTrue if the send is successful, False otherwise
statusnumberStatus code returned by the SMTP server (0 in case of an issue unrelated to the mail processing)
statusTexttextStatus message returned by the SMTP server

In case of an issue unrelated to the SMTP processing (e.g. a mandatory property is missing in mail), 4D generates an error that you can intercept using a method installed by the ON ERR CALL command. Use the GET LAST ERROR STACK command for information about the error.

In this case, the resulting status object contains the following values:

PropertyValue
successFalse
status0
statusText"Failed to send email"

.sendTimeOut

History
VersionChanges
v17 R4Added

.sendTimeOut : Integer

Description

The .sendTimeOut property contains the maximum wait time (in seconds) of a call to .send( ) before a timeout occurs. By default, if the .sendTimeOut property has not been set in the server object, the value 100 is used.

.user

History
VersionChanges
v17 R4Added

.user : Text

Description

The .user property contains the user name used for authentication on the mail server.