Version: 19

Email

La création, l'envoi et la réception d'emails dans 4D s'effectuent par l'intermédiaire des objets Email.

Des objets Email sont créés lorsque vous recevez des emails via une fonction de classe transporter :

IMAP - fonctions .getMail() et .getMails() pour récupérer des emails depuis un serveur IMAP
POP3 - fonction .getMail() pour récupérer un email depuis un serveur POP3.

Vous pouvez également créer un nouvel objet vide Email et le remplir avec les propriétés de l'objet Email.

Vous envoyez des objets Email à l'aide de la fonction SMTP .send().

Les commandes MAIL Convert from MIME et MAIL Convert to MIME peuvent être utilisées pour convertir des objets Email depuis et vers des contenus MIME.

Objet Email

Les objets Email exposent les propriétés suivantes :

Le format des objets Email de 4D suit la spécification JMAP.


.attachments : Collection collection d'objets `4D.MailAttachment`
.bcc : Text .bcc : Object .bcc : Collection adresse(s) des destinataires cachés en copie carbone invisible (cci) de l'email
.bodyStructure : Object objet EmailBodyPart, c'est-à-dire la structure MIME complète du corps du message (optionnel)
.bodyValues : Object objet EmailBodyValue, contenant lui-même un objet pour chaque <partID> de `bodyStructure` (optionnel)
.cc : Text .cc : Object .cc : Collection adresse(s) supplémentaire(s) des destinataires en Copie Carbone (CC) de l'email
.comments : Text en-tête de commentaires supplémentaire
.from : Text .from : Object .from : Collection adresse(s) d'origine de l'e-mail
.headers : Collection collection d'objets `EmailHeader`, dans l'ordre où ils apparaissent dans le message
.htmlBody : Text représentation HTML de l'email (le jeu de caractères par défaut est UTF-8) (facultatif, SMTP uniquement)
.id : Text ID unique du serveur IMAP
.inReplyTo : Text identifiant(s) du ou des message(s) d'origine auquel/auxquels le message courant est une réponse
.keywords : Object ensemble de mots-clés sous forme d'objet, où chaque nom de propriété est un mot-clé et chaque valeur est mise à Vrai
.messageId : Text en-tête d'identification du message ("message-id")
.receivedAt : Texte horodatage de l'arrivée de l'email sur le serveur IMAP au format ISO 8601 UTC (ex : 2020-09-13T16:11:53Z)
.references : Collection collection de tous les identifiants de messages de la chaîne de réponses précédente
.replyTo : Texte .replyTo : Objet .replyTo : Collection adresse(s) des destinataires de réponse à l'email
.sendAt : Texte horodatage de l'email au format ISO 8601 UTC
.sender : Texte .sender : Objet .sender : Collection adresse(s) source(s) de l'email
.size : Integer taille (exprimée en octets) de l'objet Email retourné par le serveur IMAP
.subject : Texte description du sujet
.textBody : Texte représentation en texte brut de l'email (le jeu de caractères par défaut est UTF-8) (optionnel, SMTP uniquement)
.to : Texte .to : Objet .to : Collection adresse(s) des destinataires principaux de l'email

Adresses Email

Toutes les propriétés qui contiennent des adresses email (from, cc, bcc, to, sender, replyTo) acceptent des valeurs de type texte, objet ou collection.

Text

une adresse uniquement : "somebody@domain.com"
un nom+adresse : "Somebody somebody@domain.com"
combinaison de plusieurs adresses : "Somebody somebody@domain.com,me@home.org"

Object

Un objet avec deux propriétés :

Propriété	Type	Description
name	Text	Nom à afficher (peut être null)
email	Text	Adresse email

Collection

Une collection d'objets adresse.

Traitement du body

Les propriétés textBody et htmlBody sont utilisées uniquement par la fonction SMTP.send() pour permettre d'envoyer des emails simples. Lorsque les deux propriétés sont remplies, le type MIME content-type multipart/alternative est utilisé. Le client email doit alors reconnaître la partie multipart/alternative et afficher la partie texte ou html nécessaire.

bodyStructure et bodyValues sont utilisés par le SMTP lorsque l'objet Email est construit depuis un document MIME, e.g. généré par la commande MAIL Convert from MIME. Dans ce cas, les deux propriétés bodyStructure et bodyValues doivent être passées ensemble, et il est déconseillé d'utiliser textBody et htmlBody.

Exemple d'objets bodyStructure et bodyValues

"bodyStructure": {
  "type": "multipart/mixed",
  "subParts": [
    {
      "partId": "p0001",
      "type": "text/plain"
    },
    {
      "partId": "p0002",
      "type": "text/html"
    }
  ]
},
"bodyValues": {
  "p0001": {
    "value": "I have the most brilliant plan. Let me tell you all about it."
  },
  "p0002": {
    "value": "<!DOCTYPE html><html><head><title></title><style type=\"text/css\">div{font-size:16px}</style></head><body><div>I have the most brilliant plan. Let me tell you all about it.</div></body></html>"
  }
}

.attachments

.attachments : Collection

Description

La propriété .attachments contient une collection d'objets 4D.MailAttachment.

Les objets Attachment (pièce jointe) sont créés à l'aide de la commande MAIL New attachment. Les objets Attachment ont des propriétés et fonctions spécifiques.

.bcc

.bcc : Text
.bcc : Object
.bcc : Collection

Description

La propriété .bcc contient les adresse(s) des destinataires cachés en copie carbone invisible (cci) de l'email.

.bodyStructure

.bodyStructure : Object

Description

La propriété .bodyStructure contient l' objet EmailBodyPart, c'est-à-dire la structure MIME complète du corps du message (optionnel). Voir section Traitement du body.

L'objet .bodyStructure contient les propriété suivantes :

Propriété	Type	Valeur
partID	Text	Identifie la partie de manière unique dans l'email
type	Text	(obligatoire) Valeur du champ d'en-tête Content-Type de la partie
charset	Text	Valeur du paramètre charset du champ d'en-tête Content-Type
encoding	Text	Si `isEncodingProblem=true`, la valeur de Content-Transfer-Encoding est ajoutée (par défaut indéfini)
disposition	Text	Valeur du champ d'en-tête Content-Disposition de la partie
language	Collection de textes	Liste de balises de langage, telles que définies dans la RFC3282, dans le champ d'en-tête Content-Language de la partie, le cas échéant.
location	Text	URI, tel que défini dans la RFC2557, dans le champ d'en-tête Content-Location de la partie, le cas échéant.
subParts	Collection d'objets	Parties du corps de chaque enfant (collection d'objets EmailBodyPart)
headers	Collection d'objets	Liste de tous les champs d'en-tête de la partie, dans leur ordre d'apparition de l'email (collection d'objets EmailHeader voir propriété headers)

.bodyValues

.bodyValues : Object

Description

La propriété .bodyValues contient l' objet EmailBodyValue, contenant lui-même un objet pour chaque <partID> de bodyStructure (optionnel). Voir section Traitement du body.

L'objet .bodyValues contient les propriété suivantes :

Propriété	Type	Valeur
partID.value	text	Valeur de la partie body
partID.isEncodingProblem	boolean	Vrai si des sections malformées sont identifiées durant le décodage du charset, si le charset est inconnu, ou si le content transfer-encoding est inconnu. Faux par défaut

.cc

.cc : Text
.cc : Object
.cc : Collection

Description

La propriété .cc contient la ou les adresse(s) supplémentaire(s) des destinataires en Copie Carbone (CC) de l'email.

.comments

.comments : Text

Description

La propriété .comments contient un en-tête de commentaires supplémentaire.

Les commentaires n'apparaissent que dans la zone d'en-tête du message (le body du message reste inchangé).

Pour les exigences propres au formatage, veuillez consulter la RFC#5322.

.from

.from : Text
.from : Object
.from : Collection

Description

La propriété .from contient la ou les adresse(s) d'origine de l'e-mail.

Chaque email envoyé comporte à la fois les adresses du sender et du from :

le domaine sender correspond à ce que le serveur de réception d'email obtient à l'ouverture de la session,
l'adresse from correspond à ce que le(s) destinataire(s) visualise(nt).

Pour mieux livrer l'email, il est recommandé d'utiliser les mêmes adresses pour from et sender.

.headers

.headers : Collection

Description

La propriété .headers contient une collection d'objets EmailHeader, dans l'ordre où ils apparaissent dans le message. Cette propriété permet aux utilisateurs d'ajouter des en-têtes extended (enregistrés) ou des en-têtes user-defined (non enregistrés, commençant par "X").

Si une propriété d'objet EmailHeader définit un en-tête tel que "from" ou "cc" qui est déjà défini comme propriété au niveau du mail, la propriété EmailHeader est ignorée.

Chaque objet de la collection de headers peut contenir les propriétés suivantes :

Propriété	Type	Valeur
[].name	text	(obligatoire) Nom du champ en-tête, tel que défini dans la RFC#5322. S'il est null ou indéfini, le champ en-tête n'est pas ajouté à l'en-tête MIME.
[].value	text	Valeur du champ d'en-tête telle que définie dans la RFC#5322

.htmlBody

.htmlBody : Text

Description

La propriété .htmlBody contient la représentation HTML de l'email (le jeu de caractères par défaut est UTF-8) (facultatif, SMTP uniquement). Voir section Traitement du body.

.id

.id : Text

Description

IMAP transporter uniquement.

La propriété .id contient l' ID unique du serveur IMAP.

.inReplyTo

.inReplyTo : Text

Description

La propriété .inReplyTo contient le ou les identifiant(s) du ou des message(s) d'origine auquel/auxquels le message courant est une réponse.

Pour les exigences propres au formatage, veuillez consulter la RFC#5322.

.keywords

.keywords : Object

Description

La propriété .keywords contient un ensemble de mots-clés sous forme d'objet, où chaque nom de propriété est un mot-clé et chaque valeur est mise à Vrai.

Cette propriété est l'en-tête "keywords" (voir la RFC#4021).

Propriété	Type	Valeur
.<keyword>	boolean	Mot-clé à définir à définir (la valeur doit être mise à vrai)

Mots-clés réservés :

$draft - Indique qu'un message est un brouillon
$seen - Indique qu'un message a été lu
$flagged - Indique qu'un message nécessite une attention particulière (ex : Urgent)
$answered - Indique qu'un message a reçu une réponse
$deleted - Indique un message à supprimer

Exemple

 $mail.keywords["$flagged"]:=True
 $mail.keywords["4d"]:=True

.messageId

.messageId : Text

Description

La propriété .messageId contient un en-tête d'identification du message ("message-id").

Cet en-tête est généralement "desChiffresOuDesLettres@nomdededomaine", par exemple "abcdef.123456@4d.com". Cet identifiant unique est notamment utilisé sur les forums ou les listes de diffusion publiques. En général, les serveurs de messagerie ajoutent automatiquement cet en-tête aux messages qu'ils envoient.

.receivedAt

.receivedAt : Texte

Description

IMAP transporter uniquement.

La propriété .receivedAt contient l' horodatage de l'arrivée de l'email sur le serveur IMAP au format ISO 8601 UTC (ex : 2020-09-13T16:11:53Z).

.references

.references : Collection

Description

La propriété .references contient la collection de tous les identifiants de messages de la chaîne de réponses précédente.

Pour les exigences propres au formatage, veuillez consulter la RFC#5322.

.replyTo

.replyTo : Texte
.replyTo : Objet
.replyTo : Collection

Description

La propriété .replyTo contient les adresse(s) des destinataires de réponse à l'email.

.sendAt

.sendAt : Texte

Description

La propriété .sendAt contient l' horodatage de l'email au format ISO 8601 UTC.

.sender

.sender : Texte
.sender : Objet
.sender : Collection

Description

La propriété .sender contient la ou les adresse(s) source(s) de l'email.

Chaque email envoyé comporte à la fois les adresses du sender et du from :

le domaine sender correspond à ce que le serveur de réception d'email obtient à l'ouverture de la session,
l'adresse from correspond à ce que le(s) destinataire(s) visualise(nt).

Pour mieux livrer l'email, il est recommandé d'utiliser les mêmes adresses pour from et sender.

.size

.size : Integer

Description

IMAP transporter uniquement.

La propriété .size contient la taille (exprimée en octets) de l'objet Email retourné par le serveur IMAP.

.subject

.subject : Texte

Description

La propriété .subject contient la description du sujet.

.textBody

.textBody : Texte

Description

La propriété .textBody contient la représentation en texte brut de l'email (le jeu de caractères par défaut est UTF-8) (optionnel, SMTP uniquement). Voir section Traitement du body.

.to

.to : Texte
.to : Objet
.to : Collection

Description

La propriété .to contient la ou les adresse(s) des destinataires principaux de l'email.

MAIL Convert from MIME

Historique

Release	Modifications
18	Ajout

MAIL Convert from MIME( mime : Blob ) : Object
MAIL Convert from MIME( mime : Text ) : Object

Paramètres	Type		Description
mime	Blob, Text	->	Email en MIME
Résultat	Object	<-	Objet email

Description

La commande MAIL Convert from MIME convertit un document MIME en un objet email valide.

Le format des objets Email de 4D suit la spécification JMAP.

Passez dans mime un document MIME valide à convertir. Il peut être fourni par tout type de serveur ou d'application de messagerie. Vous pouvez passer un BLOB ou un texte dans le paramètre mime. Si le MIME provient d'un fichier, il est recommandé d'utiliser un paramètre BLOB pour éviter les problèmes liés aux conversions de charset et de retours à la ligne.

Objet retourné

Objet email.

Exemple 1

Vous souhaitez charger un template mail enregistré au format MIME dans un document texte et l'envoyer par email :

var $mime: Blob
var $mail;$server;$transporter;$status: Object

$mime:=File("/PACKAGE/Mails/templateMail.txt").getContent())

$mail:=MAIL Convert from MIME($mime)
$mail.to:="smith@mail.com"
$mail.subject:="Hello world"

$server:=New object
$server.host:="smtp.gmail.com"
$server.port:=465
$server.user:="test@gmail.com"
$server.password:="XXXX"

$transporter:=SMTP New transporter($server)
$status:=$transporter.send($mail)

Exemple 2

Dans cet exemple, vous envoyez directement un document 4D Write Pro contenant des images :

var $mime: Blob
var $email;$server;$transporter;$status: Object

// Export Mime du document 4D Write Pro
WP EXPORT VARIABLE(WParea;$mime;wk mime html)

// convertir la variable Mime de 4D Write Pro en objet email
$email:=MAIL Convert from MIME($mime)

// Remplir les en-têtes de l'objet email
$email.subject:="4D Write Pro HTML body"
$email.from:="YourEmail@gmail.com"
$email.to:="RecipientEmail@mail.com"

$server:=New object
$server.host:="smtp.gmail.com"
$server.port:=465
$server.user:="YourEmail@gmail.com"
$server.password:="XXXX"

$transporter:=SMTP New transporter($server)
$status:=$transporter.send($email)

MAIL Convert to MIME

Historique

Release	Modifications
17 R4	Ajout
17 R5	Modifié

MAIL Convert to MIME( mail : Object { ; options : Object } ) : Text

Paramètres	Type		Description
mail	Object	->	Objet email
options	Object	->	Options d'encodage et de charset du mail
Résultat	Text	<-	Objet email converti en MIME

Description

La commande MAIL Convert to MIME convertit un objet email en texte MIME. Cette commande est appelée en interne par SMTP_transporter.send( ) pour formater l'objet email avant de l'envoyer. Elle peut être utilisée pour analyser le format MIME de l'objet.

Dans mail, passez les éléments du contenu et de la structure de l'email à convertir. Cela inclut des informations telles que les adresses e-mail (expéditeur et destinataire(s)), le contenu de l'e-mail lui-même et son type d'affichage.

Le format des objets Email de 4D suit la spécification JMAP.

Dans options, vous pouvez configurer l'encodage et le charset du mail. Les propriétés suivantes sont disponibles :

Propriété

Type

Description

headerCharset

Text

Charset et encodage utilisés pour les parties de mail suivantes : le sujet, les noms de fichiers joints et le nom du mail. 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 & 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

bodyCharset

Text

Charset et encodage utilisés pour le contenu html et le texte du body du mail. Valeurs possibles : Identiques à celles de headerCharset (voir ci-dessus)

Si le paramètre options est omis, la configuration mail mode UTF8 est utilisée pour les parties en-tête et corps.

Exemple

var $mail: Object
var $mime: Text
$mail:=New object

// Création d'un mail
$mail.from:="tsales@massmarket.com"
$mail.subject:="Terrific Sale! This week only!"
$mail.textBody:="Text format email"
$mail.htmlBody:="<html><body>HTML format email</body></html>"
$mail.to:=New collection
$mail.to.push(New object ("email";"noreply@4d.com"))
$mail.to.push(New object ("email";"test@4d.com"))

// transform the mail object in MIME
$mime:=MAIL Convert to MIME($mail)

// Contents of $mime:
// MIME-Version: 1.0
// Date: Thu, 11 Oct 2018 15:42:25 GMT
// Message-ID: <7CA5D25B2B5E0047A36F2E8CB30362E2>
// Sender: tsales@massmarket.com
// From: tsales@massmarket.com
// To: noreply@4d.com
// To: test@4d.com
// Content-Type: multipart/alternative; boundary="E0AE5773D5E95245BBBD80DD0687E218"
// Subject: Terrific Sale! This week only!
//
// --E0AE5773D5E95245BBBD80DD0687E218
// Content-Type: text/plain; charset="UTF-8"
// Content-Transfer-Encoding: quoted-printable
//
// Text format email
// --E0AE5773D5E95245BBBD80DD0687E218
// Content-Type: text/html; charset="UTF-8"
// Content-Transfer-Encoding: quoted-printable
//
// <html><body>HTML format email</body></html>
// --E0AE5773D5E95245BBBD80DD0687E218--

Objet Email​

Adresses Email​

Text​

Object​

Collection​

Traitement du body​

Exemple d'objets bodyStructure et bodyValues​

.attachments​

Description​

.bcc​

Description​

.bodyStructure​

Description​

.bodyValues​

Description​

.cc​

Description​

.comments​

Description​

.from​

Description​

.headers​

Description​

.htmlBody​

Description​

.id​

Description​

.inReplyTo​

Description​

.keywords​

Description​

Exemple​

.messageId​

Description​

.receivedAt​

Description​

.references​

Description​

.replyTo​

Description​

.sendAt​

Description​

.sender​

Description​

.size​

Description​

.subject​

Description​

.textBody​

Description​

.to​

Description​

MAIL Convert from MIME​

Description​

Objet retourné​

Exemple 1​

Exemple 2​

MAIL Convert to MIME​

Description​

Exemple​

Objet Email

Adresses Email

Text

Object

Collection

Traitement du body

Exemple d'objets bodyStructure et bodyValues

.attachments

Description

.bcc

Description

.bodyStructure

Description

.bodyValues

Description

.cc

Description

.comments

Description

.from

Description

.headers

Description

.htmlBody

Description

.id

Description

.inReplyTo

Description

.keywords

Description

Exemple

.messageId

Description

.receivedAt

Description

.references

Description

.replyTo

Description

.sendAt

Description

.sender

Description

.size

Description

.subject

Description

.textBody

Description

.to

Description

MAIL Convert from MIME

Description

Objet retourné

Exemple 1

Exemple 2

MAIL Convert to MIME

Description

Exemple