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 charset et l'encodage utilisés pour la partie body de l'email
.certificate : 4D.File .certificate : Blob le certificat utilisé pour signer les e-mails via S/MIME (Secure/MIME), fourni sous la forme d'un objet 4D.File ou d'un Blob
.certificateName : Text le nom du certificat utilisé pour signer les e-mails via S/MIME (Secure/MIME), tel qu'il est enregistré dans le magasin de certificats du système (keychain)
.certificatePassword : Text le mot de passe du certificat utilisé pour signer les e-mails, s'il est requis
.checkConnection() : Object vérifie la connexion en utilisant les informations stockées dans l'objet transporteur
.connectionTimeOut : Integer le temps d'attente maximum (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'e-mail
.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 du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie
.port : Integer le numéro de port utilisé pour les transactions de courrier
.send( mail : Object ) : Object envoie l'objet mail vers le 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
.user : Text le nom d'utilisateur utilisé pour l'authentification sur le serveur de messagerie

4D.SMTPTransporter.new()

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

Paramètres	Type		Description
server	Object	->	Informations sur le serveur de messagerie
Résultat	4D.SMTPTransporter	<-	Objet SMTP Transporter

Description

La fonction 4D.SMTPTransporter.new() crée et retourne un nouvel objet de 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 charset et l'encodage utilisés pour la partie body de l'email.

Valeurs possibles :

Constante	Valeur	Commentaire
mail mode ISO2022JP	US-ASCII_ISO-2022-JP_UTF8_QP	headerCharset: US-ASCII si possible, Japanese (ISO-2022-JP) & Quoted-printable si possible, sinon UTF-8 & Quoted-printable bodyCharset: US-ASCII si possible, Japanese (ISO-2022-JP) & 7-bit si possible, sinon 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 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

.certificate

Historique

Release	Modifications
21 R5	Ajout

.certificate : 4D.File
.certificate : Blob

Description

La propriété .certificate contient le certificat utilisé pour signer les e-mails via S/MIME (Secure/MIME), fourni sous la forme d'un objet 4D.File ou d'un Blob. Ce certificat contient la clé privée.

Si votre certificat est déjà enregistré dans votre magasin de certificats (keychain), vous pouvez utiliser .certificateName à la place de cette propriété. Notez que vous ne pouvez pas utiliser les deux propriétés simultanément, sinon une erreur est retournée.

Article(s) de blog sur le sujet

Signer des e-mails avec S/MIME et SMTPTransporter

Exemple

var $transporter : 4D.SMTPTransporter
var $options ; $result : Object

$options:=New object
//Saisir les informations pour le serveur SMTP

//Activer la signature S/MIME
//Fournir le fichier de certificat
$options.certificate:=File("myCertificateFile.p12")
$options.certificatePassword:="myGreatPW123"

$transporter:=4D.SMTPTransporter.new($options)

$email:=New object
//Remplir le contenu du mail

$result:=$transporter.send($email)

Voir également

.certificateName
.certificatePassword

.certificateName

Historique

Release	Modifications
21 R5	Ajout

.certificateName : Text

Description

La propriété .certificateName contient le nom du certificat utilisé pour signer les e-mails via S/MIME (Secure/MIME), tel qu'il est enregistré dans le magasin de certificats du système (keychain). Ce certificat contient la clé privée.

Le certificat peut également être fourni directement sous forme de fichier ou de blob à l'aide de la propriété .certificate. Notez que vous ne pouvez pas utiliser les deux propriétés simultanément, sinon une erreur est retournée.

Article(s) de blog sur le sujet

Signer des e-mails avec S/MIME et SMTPTransporter

Voir également

.certificate
.certificatePassword

.certificatePassword

Historique

Release	Modifications
21 R5	Ajout

.certificatePassword : Text

Description

La propriété .certificatePassword contient le mot de passe du certificat utilisé pour signer les e-mails, s'il est requis. Une chaîne vide est utilisée si aucun mot de passe n'est requis.

Voir également

.certificate
.certificateName

.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 en utilisant les informations stockées dans l'objet transporteur, recrée la connexion si nécessaire et renvoie le 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 maximum (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'e-mail. 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, Japanese (ISO-2022-JP) & Quoted-printable si possible, sinon UTF-8 & Quoted-printable bodyCharset: US-ASCII si possible, Japanese (ISO-2022-JP) & 7-bit si possible, sinon 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 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 du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie. 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 de courrier. 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 vers le 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, veuillez vous référer à 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 Last errors 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. 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 utilisé pour l'authentification sur le serveur de messagerie.