SMTPTransporter
The SMTPTransporter
class allows you to configure SMTP connections and send emails.
Functions and properties
SMTP Transporter objects provide the following properties and functions:
4D.SMTPTransporter.new( server : object ) : 4D.SMTPTransporter configures a new IMAP connection |
.acceptUnsecureConnection : boolean true if Qodly is allowed to establish an unencrypted connection |
.authenticationMode : string the authentication mode used to open the session on the mail server |
.bodyCharset : string 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 : string the charset and encoding used for the email header |
.host : string 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 : string 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 : string the user name used for authentication on the mail server |
4D.SMTPTransporter.new()
4D.SMTPTransporter.new( server : object ) : 4D.SMTPTransporter
Parameter | Type | Description | |
---|---|---|---|
server | object | → | Mail server information |
Result | 4D.SMTPTransporter | ← | SMTP transporter object |
Description
The 4D.SMTPTransporter.new()
function configures a new SMTP connection according to the server parameter and returns a new transporter object. The returned transporter object will then usually be used to send emails.
This function 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:
In the server parameter, pass an object containing the following properties:
server | Default value (if omitted) |
---|---|
.acceptUnsecureConnection : boolean true if Qodly is allowed to establish an unencrypted connection | False |
.accessTokenOAuth2: string .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 the SMTP transporter object. | none |
.authenticationMode : string the authentication mode used to open the session on the mail server | the most secure authentication mode supported by the server is used |
.bodyCharset : string the charset and encoding used for the body part of the email | mail mode UTF8 (US-ASCII_UTF8_QP) |
.connectionTimeOut : integer the maximum wait time (in seconds) allowed to establish a connection to the server | 30 |
.headerCharset : string the charset and encoding used for the email header | mail mode UTF8 (US-ASCII_UTF8_QP) |
.host : string the name or the IP address of the host server | mandatory |
.keepAlive : boolean true if the SMTP connection must be kept alive until the transporter object is destroyed | True |
.logFile : string the path of the extended log file defined (if any) for the mail connection | none |
password : string User password for authentication on the server. Not returned in the SMTP transporter object. | none |
.port : integer the port number used for mail transactions | 587 |
.sendTimeOut : integer the maximum wait time (in seconds) of a call to .send() before a timeout occurs | 100 |
.user : string the user name used for authentication on the mail server | none |
Result
The function returns a SMTP transporter object. All returned properties are read-only.
Example
var server : object
var transporter : 4D.SMTPTransporter
var status : object
var info : string
server = newObject()
server.host = "smtp.gmail.com" //Mandatory
server.port = 465
server.user = "qodly@gmail.com"
server.password = "XXXX"
server.logFile = "LogTest.txt" //Log to save in the Logs folder
transporter = 4D.SMTPTransporter.new (server)
email = newObject()
email.subject = "my first mail"
email.from = "qodly@gmail.com"
email.to = "qodly@qodly.com , test@qodly.com"
email.stringBody = "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))
info = "An error occurred: "+status.message
end
.acceptUnsecureConnection
.acceptUnsecureConnection : boolean
Description
The .acceptUnsecureConnection
property contains true if Qodly 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
.authenticationMode : string
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:
Value | Constants | Comment |
---|---|---|
CRAM-MD5 | kSMTPAuthenticationCRAMMD | Authentication using CRAM-MD5 protocol |
LOGIN | kSMTPAuthenticationLogin | Authentication using LOGIN protocol |
OAUTH2 | kSMTPAuthenticationOAUTH2 | Authentication using OAuth2 protocol |
PLAIN | kSMTPAuthenticationPlain | Authentication using PLAIN protocol |
.bodyCharset
.bodyCharset : string
Description
The .bodyCharset
property contains the charset and encoding used for the body part of the email.
Possible values:
Constant | Value | Comment |
---|---|---|
mail mode ISO2022JP | US-ASCII_ISO-2022-JP_UTF8_QP | |
mail mode ISO88591 | ISO-8859-1 | |
mail mode UTF8 | US-ASCII_UTF8_QP | headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & Quoted-printable (default value) |
mail mode UTF8 in base64 | US-ASCII_UTF8_B64 | headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & base64 |
.checkConnection()
.checkConnection() : object
Parameter | Type | Description | |
---|---|---|---|
Result | object | ← | 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:
Property | Type | Description | |
---|---|---|---|
success | boolean | true if the check is successful, false otherwise | |
status | number | (SMTP only) Status code returned by the mail server (0 in case of an issue unrelated to the mail processing) | |
statusText | text | Status message returned by the mail server, or last error returned in the Qodly error stack | |
errors | collection | Qodly error stack (not returned if a mail server response is received) | |
[ ].errCode | number | Qodly error code | |
[ ].message | text | Description of the Qodly error | |
[ ].componentSignature | text | Signature of the internal component which returned the error |
For information about SMTP status codes, please refer to this page.
Example
var options : object
var transporter : 4D.SMTPTransporter
var info : string
options = newObject()
options.host = "smtp.gmail.com"
options.user = "test@gmail.com"
options.password = "XXXXXX"
transporter = 4D.SMTPTransporter.new (options)
status = transporter.checkConnection()
if(status.success == true)
info = "SMTP connection check successful!"
else
info = "Error # "+string(status.status) + ", " + status.statusText)
end
.connectionTimeOut
.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
.headerCharset : string
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:
Constant | Value | Comment |
---|---|---|
mail mode ISO2022JP | US-ASCII_ISO-2022-JP_UTF8_QP | |
mail mode ISO88591 | ISO-8859-1 | |
mail mode UTF8 | US-ASCII_UTF8_QP | headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & Quoted-printable (default value) |
mail mode UTF8 in base64 | US-ASCII_UTF8_B64 | headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & base64 |
.host
.host : string
Description
The .host
property contains the name or the IP address of the host server. Used for mail transactions (SMTP, POP3, IMAP).
.keepAlive
.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), 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
.logFile : string
Description
The .logFile
property contains the path of the extended log file defined (if any) for the mail connection.
.port
.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), the port used is:
- SMTP - 587
- POP3 - 995
- IMAP - 993
.send()
.send( mail : object ) : object
Parameter | Type | Description | |
---|---|---|---|
object | → | Email to send | |
Result | object | ← | 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 the4D.SMTPTransporter.new()
constructor.
The function 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 4D.SMTPTransporter.new()
constructor 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:
Property | Type | Description |
---|---|---|
success | boolean | True if the send is successful, false otherwise |
status | number | Status code returned by the SMTP server (0 in case of an issue unrelated to the mail processing) |
statusText | string | Status 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), Qodly generates an error that you can intercept.
In this case, the resulting status object contains the following values:
Property | Value |
---|---|
success | false |
status | 0 |
statusText | "Failed to send email" |
.sendTimeOut
.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
.user : string
Description
The .user
property contains the user name used for authentication on the mail server.