Version: 20

SMTPTransporter

La classe SMTPTransporter vous permet de configurer des connexions SMTP et d'envoyer des emails par le biais d'objets SMTP transporter.

Objet SMTP Transporter

Les objets SMTP Transporter sont instanciés avec la commande SMTP New transporter. Leurs propriétés et fonctions sont les suivantes :


.acceptUnsecureConnection : Boolean True si 4D est autorisé à établir une connexion non chiffrée
.authenticationMode : Text le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie
.bodyCharset : Text le jeu de caractères et l'encodage utilisés pour le corps de l'email
.checkConnection() : Object vérifie la connexion à l'aide des informations stockées dans l'objet transporteur
.connectionTimeOut : Integer le temps d'attente maximal (en secondes) autorisé pour établir une connexion avec le serveur
.headerCharset : Text le jeu de caractères et l'encodage utilisés pour l'en-tête de l'email
.host : Text le nom ou l'adresse IP du serveur hôte
.keepAlive : Boolean True si la connexion SMTP doit rester active jusqu'à la destruction de l'objet `transporter`
.logFile : Text le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexion
.port : Integer le numéro de port utilisé pour les transactions d'emails
.send( mail : Object ) : Object envoie l'objet mail au serveur SMTP défini dans l'objet `transporter` et retourne un objet statut
.sendTimeOut : Integer le temps d'attente maximum (en secondes) d'un appel à `.send()` avant le timeout (l'expiration du délai)
.user : Text le nom d'utilisateur employé pour l'authentification sur le serveur de messagerie

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	<-	objet SMTP transporter

Description

La commande SMTP New transporter configure une nouvelle connexion SMTP en fonction du paramètre server et renvoie un nouvel objet SMTP transporter. L'objet transporteur retourné sera alors utilisé pour l'envoi d'emails.

Cette commande n'ouvre pas de connexion au serveur SMTP. La connexion SMTP est réellement ouverte lorsque la fonction .send() est exécutée.

La connexion SMTP est automatiquement fermée :

lorsque l'objet transporteur est détruit si la propriété keepAlive est vraie (par défaut),

après chaque exécution de la fonction .send() si la propriété keepAlive a la valeur faux.

Dans le paramètre server, passez un objet contenant les propriétés suivantes :

server	Valeur par défaut (si omise)
.acceptUnsecureConnection : Boolean True si 4D est autorisé à établir une connexion non chiffrée	False
.accessTokenOAuth2 : Text .accessTokenOAuth2 : Object Chaîne ou objet token représentant les informations d'autorisation OAuth2. Utilisé uniquement avec OAUTH2 `authenticationMode`. Si `accessTokenOAuth2` est utilisé mais que `authenticationMode` est omis, le protocole OAuth 2 est utilisé (si le serveur l'autorise). Non retourné dans l'objet SMTP transporter.	aucun
.authenticationMode : Text le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie	le mode d'authentification le plus sûr pris en charge par le serveur est utilisé
.bodyCharset : Text le jeu de caractères et l'encodage utilisés pour le corps de l'email	`mail mode UTF8` (US-ASCII_UTF8_QP)
.connectionTimeOut : Integer le temps d'attente maximal (en secondes) autorisé pour établir une connexion avec le serveur	30
.headerCharset : Text le jeu de caractères et l'encodage utilisés pour l'en-tête de l'email	`mail mode UTF8` (US-ASCII_UTF8_QP)
.host : Text le nom ou l'adresse IP du serveur hôte	obligatoire
.keepAlive : Boolean True si la connexion SMTP doit rester active jusqu'à la destruction de l'objet `transporter`	True
.logFile : Text le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexion	aucun
password : Text Mot de passe utilisateur pour l'authentification sur le serveur. Non retourné dans l'objet SMTP transporter.	aucun
.port : Integer le numéro de port utilisé pour les transactions d'emails	587
.sendTimeOut : Integer le temps d'attente maximum (en secondes) d'un appel à `.send()` avant le timeout (l'expiration du délai)	100
.user : Text le nom d'utilisateur employé pour l'authentification sur le serveur de messagerie	aucun

Résultat

La fonction retourne un objet SMTP transporter. Toutes les propriétés retournées sont en lecture seule.

Exemple

 $server:=New object
 $server.host:="smtp.gmail.com" //Obligatoire
 $server.port:=465
 $server.user:="4D@gmail.com"
 $server.password:="XXXX"
 $server.logFile:="LogTest.txt" //Log étendu à sauvegarder dans le dossier Logs

 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	<-	objet SMTP transporter

Description

La fonction 4D.SMTPTransporter.new() crée et renvoie un nouvel objet du type 4D.SMTPTransporter. Elle est identique à la commande SMTP New transporter (raccourci).

.acceptUnsecureConnection

Historique

Release	Modifications
17 R4	Ajout

.acceptUnsecureConnection : Boolean

Description

La propriété .acceptUnsecureConnection contient True si 4D est autorisé à établir une connexion non chiffrée lorsqu'une connexion chiffrée n'est pas possible.

Elle contient False si les connexions non chiffrées ne sont pas autorisées, auquel cas une erreur est retournée lorsque la connexion chiffrée n'est pas 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

La propriété .authenticationMode contient le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie.

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

La propriété .bodyCharset contient le jeu de caractères et l'encodage utilisés pour le corps de l'email.

Valeurs possibles :

Constante	Valeur	Commentaire
mail mode ISO2022JP	US-ASCII_ISO-2022-JP_UTF8_QP	headerCharset : US-ASCII si possible, japonais (ISO-2022-JP) & Quoted-printable si possible, sinon UTF-8 & Quoted-printable bodyCharset : US-ASCII si possible, japonais (ISO-2022-JP) et 7 bits si possible, sinon UTF-8 et Quoted-printable
mail mode ISO88591	ISO-8859-1	headerCharset : ISO-8859-1 & Quoted-printable bodyCharset : ISO-8859-1 et 8 bits
mail mode UTF8	US-ASCII_UTF8_QP	headerCharset & bodyCharset : US-ASCII si possible, sinon UTF-8 & Quoted-printable (valeur par défaut)
mail mode UTF8 in base64	US-ASCII_UTF8_B64	headerCharset &bodyCharset : US-ASCII si possible, sinon 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

La fonction .checkConnection() vérifie la connexion à l'aide des informations stockées dans l'objet transporteurrecrée la connexion si nécessaire, et renvoie son statut. 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

Pour une description des codes de statut SMTP, veuillez vous reporter à cette 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

La propriété .connectionTimeOut contient le temps d'attente maximal (en secondes) autorisé pour établir une connexion avec le serveur. Par défaut, si la propriété n'a pas été définie dans l'objet server (utilisé pour créer l'objet transporteur avec SMTP New transporter, POP3 New transporter, IMAP New transporter), la valeur utilisée est 30.

.headerCharset

Historique

Release	Modifications
17 R5	Ajout

.headerCharset : Text

Description

La propriété .headerCharset contient le jeu de caractères et l'encodage utilisés pour l'en-tête de l'email. L'en-tête comprend les éléments suivants de l'e-mail :

subject,
attachment filename(s),
email name.

Valeurs possibles :

Constante	Valeur	Commentaire
mail mode ISO2022JP	US-ASCII_ISO-2022-JP_UTF8_QP	headerCharset : US-ASCII si possible, japonais (ISO-2022-JP) & Quoted-printable si possible, sinon UTF-8 & Quoted-printable bodyCharset : US-ASCII si possible, japonais (ISO-2022-JP) et 7 bits si possible, sinon UTF-8 et Quoted-printable
mail mode ISO88591	ISO-8859-1	headerCharset : ISO-8859-1 & Quoted-printable bodyCharset : ISO-8859-1 et 8 bits
mail mode UTF8	US-ASCII_UTF8_QP	headerCharset & bodyCharset : US-ASCII si possible, sinon UTF-8 & Quoted-printable (valeur par défaut)
mail mode UTF8 in base64	US-ASCII_UTF8_B64	headerCharset &bodyCharset : US-ASCII si possible, sinon UTF-8 & base64

.host

Historique

Release	Modifications
17 R5	Ajout

.host : Text

Description

La propriété .host contient le nom ou l'adresse IP du serveur hôte. Utilisée pour les échanges de courrier (SMTP, POP3, IMAP).

.keepAlive

Historique

Release	Modifications
17 R4	Ajout

.keepAlive : Boolean

Description

La propriété .keepAlive contient True si la connexion SMTP doit rester active jusqu'à la destruction de l'objet transporter, et False sinon. Par défaut, si la propriété keepAlive n'a pas été définie dans l'objet server qui permet de créer l'objet transporter via la commande SMTP New transporter), elle est mise à True.

La connexion SMTP est automatiquement fermée :

lorsque l'objet transporter est détruit si la propriété .keepAlive est mise à vrai,
après chaque fonction .send( ) exécutée si la propriété .keepAlive est mise à faux.

.logFile

Historique

Release	Modifications
17 R5	Ajout

.logFile : Text

Description

La propriété .logFile contient le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexion. Le chemin peut être relatif (au dossier Logs courant) ou absolu.

Contrairement aux fichiers log habituels (activés via la commande SET DATABASE PARAMETER), les fichiers log étendus stockent le contenu MIME de tous les emails envoyés et n'ont pas de limite de taille. Pour plus d'informations sur les fichiers log étendus, reportez-vous à :

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

.port

Historique

Release	Modifications
17 R4	Ajout

.port : Integer

Description

La propriété .port contient le numéro de port utilisé pour les transactions d'emails. Par défaut, si la propriété port n'a pas été définie dans l'objet server (utilisé pour créer l'objet transporteur avec SMTP New transporter, POP3 New transporter, IMAP New transporter), le port utilisé est :

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 à envoyer
Résultat	Object	<-	Statut SMTP

Description

La fonction .send() envoie l'objet mail au serveur SMTP défini dans l'objet transporter et retourne un objet statut.

L'objet transporter doit avoir déjà été créé à l'aide de la commande SMTP New transporter.

La fonction établit la connexion SMTP si cette dernière n'est pas déjà active. Si la propriété .keepAlive de l'objet transporter est à false, la connexion SMTP est automatiquement fermée après l'exécution de la commande .send(). Pour plus d'informations, voir la description de la commande SMTP New transporter.

Dans mail, passez un objet Email valide à envoyer. 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

En cas de problème non lié au traitement SMTP (par exemple une propriété obligatoire qui est manquante dans l'objet mail), 4D génère une erreur que vous pouvez intercepter à l'aide d'une méthode installée via la commande ON ERR CALL. Utilisez la commande GET LAST ERROR STACK pour obtenir des informations sur l'erreur.

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

La propriété .sendTimeOut contient le temps d'attente maximum (en secondes) d'un appel à .send() avant le timeout (l'expiration du délai). Par défaut, si la propriété .sendTimeOut n'a pas été définie dans l'objet server, la valeur 100 est utilisée.

.user

Historique

Release	Modifications
17 R4	Ajout

.user : Text

Description

La propriété .user contient le nom d'utilisateur employé pour l'authentification sur le serveur de messagerie.

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