Version: 20 R5 BETA

SMTPTransporter

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

Objet SMTP Transporter

SMTP Transporter objects are instantiated with the SMTP New transporter command. Leurs propriétés et fonctions sont les suivantes :


.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

Historique

Release	Modifications
18	Nouvelle propriété logFile
17 R5	Nouvelles propriétés bodyCharset et headerCharset
17 R4	Ajout

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

Paramètres	Type		Description
server	Object	->	Informations sur le serveur IMAP
Résultat	4D.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. L'objet transporteur retourné sera alors utilisé pour l'envoi d'emails.

Cette commande n'ouvre pas de connexion au serveur SMTP. The SMTP connection is actually opened when the .send() function is executed.
La connexion SMTP est automatiquement fermée :
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:

server	Valeur par défaut (si omise)
.acceptUnsecureConnection : Boolean    True if 4D is allowed to establish an unencrypted connection	False
.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.	aucun
.authenticationMode : Text    the authentication mode used to open the session on the mail server	le mode d'authentification le plus sûr pris en charge par le serveur est utilisé
.bodyCharset : Text     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 : Text     the charset and encoding used for the email header	`mail mode UTF8` (US-ASCII_UTF8_QP)
.host : Text    the name or the IP address of the host server	obligatoire
.keepAlive : Boolean    True if the SMTP connection must be kept alive until the `transporter` object is destroyed	True
.logFile : Text    the path of the extended log file defined (if any) for the mail connection	aucun
password : Text User password for authentication on the server. Not returned in SMTP transporter object.	aucun
.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 : Text     the user name used for authentication on the mail server	aucun

Résultat

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

Exemple

 $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

Paramètres	Type		Description
server	Object	->	Informations sur le serveur IMAP
Résultat	4D.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

Historique

Release	Modifications
17 R4	Ajout

.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.

Ports sécurisés disponibles :

SMTP
- 465: SMTPS
- 587 ou 25 : SMTP avec mise à niveau STARTTLS si le serveur le prend en charge.
IMAP
- 143 : Port IMAP non chiffré
- 993 : IMAP avec mise à niveau STARTTLS si le serveur le prend en charge
POP3
- 110 : Port POP3 non chiffré
- 995 : POP3 avec mise à niveau STARTTLS si le serveur le prend en charge.

.authenticationMode

Historique

Release	Modifications
17 R4	Ajout

.authenticationMode : Text

Description

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

Par défaut, le mode le plus sécurisé pris en charge par le serveur est utilisé.

Valeurs possibles :

Valeur	Constantes	Commentaire
CRAM-MD5	`SMTP authentication CRAM MD5`	Authentification à l'aide du protocole CRAM-MD5
LOGIN	`SMTP authentication login`	Authentification à l'aide du protocole LOGIN
OAUTH2	`SMTP authentication OAUTH2`	Authentification à l'aide du protocole OAuth2
PLAIN	`SMTP authentication plain`	Authentification à l'aide du protocole PLAIN

.bodyCharset

Historique

Release	Modifications
18	Prise en charge de UTF8 base64
17 R5	Ajout

.bodyCharset : Text

Description

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

Possible values:

Constante	Valeur	Commentaire
mail mode ISO2022JP	US-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 ISO88591	ISO-8859-1	headerCharset: ISO-8859-1 & Quoted-printable bodyCharset: ISO-8859-1 & 8-bit
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()

Historique

Release	Modifications
17 R4	Ajout

.checkConnection() : Object

Paramètres	Type		Description
Résultat	Object	<-	Statut de la connexion de l'objet transporteur

Description

The .checkConnection() function checks the connection using information stored in the transporter object, recreates the connection if necessary, and returns the status. Cette fonction vous permet de vérifier que les valeurs fournies par l'utilisateur sont valides et cohérentes.

Objet retourné

La fonction envoie une requête au serveur de mail et retourne un objet décrivant le statut. Cet objet peut avoir les propriétés suivantes :

Propriété		Type	Description
success		boolean	Vrai si la vérification a été effectuée avec succès, sinon Faux
status		number	(SMTP uniquement) Code du statut retourné par le serveur de messagerie (0 en cas de problème non lié au traitement du mail)
statusText		text	Message du statut retourné par le serveur de messagerie, ou dernière erreur retournée dans la pile d'erreurs 4D
errors		collection	Pile d'erreurs 4D (non retournée si une réponse du serveur de messagerie est reçue)
	[ ].errCode	number	Code d'erreur 4D
	[ ].message	text	Description de l'erreur 4D
	[ ].componentSignature	text	Signature du composant interne qui a retourné l'erreur

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

Exemple

 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

Historique

Release	Modifications
17 R5	Ajout

.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

Historique

Release	Modifications
17 R5	Ajout

.headerCharset : Text

Description

The .headerCharset property contains the charset and encoding used for the email header. L'en-tête comprend les éléments suivants de l'e-mail :

subject,
attachment filename(s),
email name.

Possible values:

Constante	Valeur	Commentaire
mail mode ISO2022JP	US-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 ISO88591	ISO-8859-1	headerCharset: ISO-8859-1 & Quoted-printable bodyCharset: ISO-8859-1 & 8-bit
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

Historique

Release	Modifications
17 R5	Ajout

.host : Text

Description

The .host property contains the name or the IP address of the host server. Utilisée pour les échanges de courrier (SMTP, POP3, IMAP).

.keepAlive

Historique

Release	Modifications
17 R4	Ajout

.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.

La connexion SMTP est automatiquement fermée :

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

Historique

Release	Modifications
17 R5	Ajout

.logFile : Text

Description

The .logFile property contains the path of the extended log file defined (if any) for the mail connection. Le chemin peut être relatif (au dossier Logs courant) ou absolu.

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. Pour plus d'informations sur les fichiers log étendus, reportez-vous à :

SMTP connections - 4DSMTPLog.txt
POP3 connections - 4DPOP3Log.txt
IMAP connections - 4DIMAPLog.txt

.port

Historique

Release	Modifications
17 R4	Ajout

.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()

Historique

Release	Modifications
17 R5	Prise en charge des contenus Mime
17 R4	Ajout

.send( mail : Object ) : Object

Paramètres	Type		Description
mail	Object	->	Email to send
Résultat	Object	<-	Statut SMTP

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.

La fonction établit la connexion SMTP si cette dernière n'est pas déjà active. 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. Les propriétés origine (la provenance de l'Email) et destination (un ou plusieurs destinataires) de l'Email doivent être incluses, les autres propriétés sont optionnelles.

Objet retourné

La fonction retourne un objet décrivant le statut SMTP de l"opération. Cet objet peut avoir les propriétés suivantes :

Propriété	Type	Description
success	boolean	Vrai si l'envoi a été effectué avec succès, sinon Faux
status	number	Code du statut retourné par le serveur SMTP (0 si problème non lié au traitement de l'email)
statusText	text	Message de statut retourné par le serveur SMTP

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.

Dans ce cas, l'objet erreur qui en résulte contient les valeurs suivantes :

Propriété	Valeur
success	False
status	0
statusText	"Failed to send email"

.sendTimeOut

Historique

Release	Modifications
17 R4	Ajout

.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

Historique

Release	Modifications
17 R4	Ajout

.user : Text

Description

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

Objet SMTP Transporter​

SMTP New transporter​

Description​

Résultat​

Exemple​

4D.SMTPTransporter.new()​

Description​

.acceptUnsecureConnection​

Description​

.authenticationMode​

Description​

.bodyCharset​

Description​

.checkConnection()​

Description​

Objet retourné​

Exemple​

.connectionTimeOut​

Description​

.headerCharset​

Description​

.host​

Description​

.keepAlive​

Description​

.logFile​

Description​

.port​

Description​

.send()​

Description​

Objet retourné​

.sendTimeOut​

Description​

.user​

Description​

Objet SMTP Transporter

SMTP New transporter

Description

Résultat

Exemple

4D.SMTPTransporter.new()

Description

.acceptUnsecureConnection

Description

.authenticationMode

Description

.bodyCharset

Description

.checkConnection()

Description

Objet retourné

Exemple

.connectionTimeOut

Description

.headerCharset

Description

.host

Description

.keepAlive

Description

.logFile

Description

.port

Description

.send()

Description

Objet retourné

.sendTimeOut

Description

.user

Description