Aller au contenu principal
Version: v19

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
VersionModifications
v18Nouvelle propriété logFile
v17 R5Nouvelles propriétés bodyCharset et headerCharset
v17 R4Ajout

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

ParamètresTypeDescription
serverObject->Informations sur le serveur IMAP
Résultat4D.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 :

serverValeur par défaut (si omise)
.acceptUnsecureConnection : Boolean    True si 4D est autorisé à établir une connexion non chiffréeFalse
.accessTokenOAuth2: TextText string representing OAuth 2 authorization credentials. 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 messageriele 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'emailmail mode UTF8 (US-ASCII_UTF8_QP)
.connectionTimeOut : Integer    le temps d'attente maximal (en secondes) autorisé pour établir une connexion avec le serveur30
.headerCharset : Text     le jeu de caractères et l'encodage utilisés pour l'en-tête de l'emailmail mode UTF8 (US-ASCII_UTF8_QP)
.host : Text    le nom ou l'adresse IP du serveur hôteobligatoire
.keepAlive : Boolean    True si la connexion SMTP doit rester active jusqu'à la destruction de l'objet transporterTrue
.logFile : Text    le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexionaucun
password : TextUser password for authentication on the server. Non retourné dans l'objet SMTP transporter.aucun
.port : Integer     le numéro de port utilisé pour les transactions d'emails587
.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 messagerieaucun

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" //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>\
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ètresTypeDescription
serverObject->Informations sur le serveur IMAP
Résultat4D.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
VersionModifications
v17 R4Ajout

.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
VersionModifications
v17 R4Ajout

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

ValeurConstantesCommentaire
CRAM-MD5SMTP authentication CRAM MD5Authentification à l'aide du protocole CRAM-MD5
LOGINSMTP authentication loginAuthentification à l'aide du protocole LOGIN
OAUTH2SMTP authentication OAUTH2Authentification à l'aide du protocole OAuth2
PLAINSMTP authentication plainAuthentification à l'aide du protocole PLAIN

.bodyCharset

Historique
VersionModifications
v18Prise en charge de UTF8 base64
v17 R5Ajout

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

ConstanteValeurCommentaire
mail mode ISO2022JPUS-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 ISO88591ISO-8859-1
  • headerCharset : ISO-8859-1 & Quoted-printable
  • bodyCharset : ISO-8859-1 et 8 bits
mail mode UTF8US-ASCII_UTF8_QPheaderCharset & bodyCharset : US-ASCII si possible, sinon UTF-8 & Quoted-printable (valeur par défaut)
mail mode UTF8 in base64US-ASCII_UTF8_B64headerCharset &bodyCharset : US-ASCII si possible, sinon UTF-8 & base64

.checkConnection()

Historique
VersionModifications
v17 R4Ajout

.checkConnection() : Object

ParamètresTypeDescription
RésultatObject<-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éTypeDescription
successbooleanVrai si la vérification a été effectuée avec succès, sinon Faux
statusnumber(SMTP uniquement) Code du statut retourné par le serveur de messagerie (0 en cas de problème non lié au traitement du mail)
statusTexttextMessage du statut retourné par le serveur de messagerie, ou dernière erreur retournée dans la pile d'erreurs 4D
errorscollectionPile d'erreurs 4D (non retournée si une réponse du serveur de messagerie est reçue)
[ ].errCodenumberCode d'erreur 4D
[ ].messagetextDescription de l'erreur 4D
[ ].componentSignaturetextSignature 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
VersionModifications
v17 R5Ajout

.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
VersionModifications
v17 R5Ajout

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

ConstanteValeurCommentaire
mail mode ISO2022JPUS-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 ISO88591ISO-8859-1
  • headerCharset : ISO-8859-1 & Quoted-printable
  • bodyCharset : ISO-8859-1 et 8 bits
mail mode UTF8US-ASCII_UTF8_QPheaderCharset & bodyCharset : US-ASCII si possible, sinon UTF-8 & Quoted-printable (valeur par défaut)
mail mode UTF8 in base64US-ASCII_UTF8_B64headerCharset &bodyCharset : US-ASCII si possible, sinon UTF-8 & base64

.host

Historique
VersionModifications
v17 R5Ajout

.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
VersionModifications
v17 R4Ajout

.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
VersionModifications
v17 R5Ajout

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

.port

Historique
VersionModifications
v17 R4Ajout

.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
VersionModifications
v17 R5Prise en charge des contenus Mime
v17 R4Ajout

.send( mail : Object ) : Object

ParamètresTypeDescription
mailObject->Email à envoyer
RésultatObject<-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éTypeDescription
successbooleanVrai si l'envoi a été effectué avec succès, sinon Faux
statusnumberCode du statut retourné par le serveur SMTP (0 si problème non lié au traitement de l'email)
statusTexttextMessage 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
successFalse
status0
statusText"Failed to send email"

.sendTimeOut

Historique
VersionModifications
v17 R4Ajout

.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
VersionModifications
v17 R4Ajout

.user : Text

Description

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