Emails
Creating, sending or receiving emails in 4D is done by handling an Email
object. This object is used by the following commands and methods:
- SMTP -
.send()
function to send an email through SMTP - POP3 -
.getMail()
function to get an email from a POP3 server - IMAP -
.getMail()
and.getMails()
functions to get emails from an IMAP server. MAIL Convert from MIME
andMAIL Convert to MIME
commands to convert emails
Email Object
Email objects provide the following properties:
4D follows the JMAP specification to format the Email object.
.attachments : Collection collection of attachment object(s) |
.bcc : Text .bcc : Object .bcc : Collection Blind Carbon Copy (BCC) hidden email recipient addresse(s) of the email |
.bodyStructure : Object EmailBodyPart object, i.e. the full MIME structure of the message body (optional) |
.bodyValues : Object EmailBodyValue object, containing an object for each <partID> of |
.cc : Text .cc : Object .cc : Collection Carbon Copy (CC) additional email recipient addresse(s) of the email |
.comments : Text additional comments header |
.from : Text .from : Object .from : Collection Originating address(es) of the email |
.headers : Collection collection of |
.htmlBody : Text HTML representation of the email message (default charset is UTF-8) (optional, SMTP only) |
.id : Text unique ID from the IMAP server |
.inReplyTo : Text message identifier(s) of the original message(s) to which the current message is a reply |
.keywords : Object set of keywords as an object, where each property name is a keyword and each value is true |
.messageId : Texte en-tête d'identificateur de message ("message-id") |
.receivedAt : Texte l'horodatage de l'arrivée de l'e-mail 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 addresse(s) for responses |
.sendAt : Texte Email timestamp in ISO 8601 UTC format |
.sender : Texte .sender : Objet .sender : Collection email source addresse(s) of the email |
.size : Integer size (expressed in bytes) of the Email object returned by the IMAP server |
.subject : Texte description of topic |
.textBody : Texte
|
.to : Texte .to : Objet .to : Collection le ou les destinataires principaux de l'e-mail |
Email Addresses
All properties that contain email addresses (from
, cc
, bcc
, to
, sender
, replyTo
) accept a value of text, object, or collection type.
Texte
- single email: "somebody@domain.com"
- single display name+email: "Somebody somebody@domain.com"
- several emails: "Somebody somebody@domain.com,me@home.org"
Objet
An object with two properties:
Propriété | Type | Description |
---|---|---|
name | Texte | Display name (can be null) |
Texte | Email address |
Collection
A collection of address objects.
Handling body part
The textBody
and htmlBody
properties are only used with the SMTP.send() function to allow sending simple mails. When both property are filled, the MIME content-type multipart/alternative is used. The email client should then recognize the multipart/alternative part and display the text part or html part as necessary.
bodyStructure
and bodyValues
are used for SMTP when the Email object is built from a MIME document, e.g. when generated by the MAIL Convert from MIME
command. In this case, both bodyStructure
and bodyValues
properties must be passed together, and it is not recommended to use textBody
and htmlBody
.
Example of bodyStructure and bodyValues objects
"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
The .attachments
property contains a collection of attachment object(s).
Attachment objects are defined through the MAIL New attachment
command.
.bcc
.bcc : Text
.bcc : Object
.bcc : Collection
Description
The .bcc
property contains the Blind Carbon Copy (BCC) hidden email recipient addresse(s) of the email.
.bodyStructure
.bodyStructure : Object
Description
The .bodyStructure
property contains the EmailBodyPart object, i.e. the full MIME structure of the message body (optional). See Handling body part section.
The .bodyStructure
object contains the following properties:
Propriété | Type | Valeur |
---|---|---|
partID | Texte | Identifies the part uniquely within the email |
type | Texte | (mandatory) Value of the Content-Type header field of the part |
charset | Texte | Value of the charset parameter of the Content-Type header field |
encoding | Texte | If isEncodingProblem=true , the Content-Transfer-Encoding value is added (by default undefined) |
disposition | Texte | Value of the Content-Disposition header field of the part |
language | Collection of texts | List of language tags, as defined in RFC3282, in the Content-Language header field of the part, if present. |
location | Texte | URI, as defined in RFC2557, in the Content-Location header field of the part, if present. |
subParts | Collection of objects | Body parts of each child (collection of EmailBodyPart objects) |
headers | Collection of objects | List of all header fields in the part, in the order they appear in the message (collection of EmailHeader objects, see headers property) |
.bodyValues
.bodyValues : Object
Description
The .bodyValues
property contains the EmailBodyValue object, containing an object for each <partID> of bodyStructure
(optional). See Handling body part section.
The .bodyValues
object contains the following properties:
Propriété | Type | Valeur |
---|---|---|
partID.value | Texte | Value of the body part |
partID.isEncodingProblem | boolean | True if malformed sections are found while decoding the charset, or unknown charset, or unknown content transfer-encoding. False by default |
.cc
.cc : Text
.cc : Object
.cc : Collection
Description
The .cc
property contains the Carbon Copy (CC) additional email recipient addresse(s) of the email.
.comments
.comments : Text
Description
The .comments
property contains an additional comments header.
Comments only appear within the header section of the message (keeping the message's body untouched).
For specific formatting requirements, please consult the RFC#5322.
.from
.from : Text
.from : Object
.from : Collection
Description
The .from
property contains the Originating address(es) of the email.
Each email you send out has both the sender and from addresses:
- the sender domain is what the receiving email server gets when opening the session,
- the from address is what the recipient(s) will see.
For better deliverability, it is recommended to use the same from and sender addresses.
.headers
.headers : Collection
Description
The .headers
property contains a collection of EmailHeader
objects, in the order they appear in the message. This property allows users to add extended (registered) headers or user-defined (not registered, starting with "X") headers.
If an
EmailHeader
object property defines a header such as "from" or "cc" which is already set as a property at the mail level, theEmailHeader
property is ignored.
Every object of the headers collection can contain the following properties:
Propriété | Type | Valeur |
---|---|---|
[].name | Texte | (mandatory) Header field name as defined in RFC#5322. If null or undefined, the header field is not added to the MIME header. |
[].value | Texte | Header field values as defined in RFC#5322 |
.htmlBody
.htmlBody : Text
Description
The .htmlBody
property contains the HTML representation of the email message (default charset is UTF-8) (optional, SMTP only). See Handling body part section.
.id
.id : Text
Description
IMAP transporter only.
The .id
property contains the unique ID from the IMAP server.
.inReplyTo
.inReplyTo : Text
Description
The .inReplyTo
property contains the message identifier(s) of the original message(s) to which the current message is a reply.
For specific formatting requirements, please consult the RFC#5322.
.keywords
.keywords : Object
Description
The .keywords
property contains a set of keywords as an object, where each property name is a keyword and each value is true.
This property is the "keywords" header (see RFC#4021).
Propriété |
---|
. \ |
Reserved keywords:
- $draft - Indicates a message is a draft
- $seen - Indicates a message has been read
- $flagged - Indicates a message needs special attention (e.g., Urgent)
- $answered - Indicates a message has been replied to
- $deleted - Indicates a message to delete
Exemple
var $mail : Object
$mail.keywords["$flagged"]:=True
$mail.keywords["4d"]:=True
.messageId
.messageId : Texte
Description
La propriété .messageId
contient un en-tête d'identificateur de 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 only.
La propriété .receivedAt
contient l'horodatage de l'arrivée de l'e-mail 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.
For specific formatting requirements, please consult the RFC#5322.
.replyTo
.replyTo : Texte
.replyTo : Objet
.replyTo : Collection
Description
The .replyTo
property contains the addresse(s) for responses.
.sendAt
.sendAt : Texte
Description
The .sendAt
property contains the Email timestamp in ISO 8601 UTC format.
.sender
.sender : Texte
.sender : Objet
.sender : Collection
Description
The .sender
property contains the email source addresse(s) of the email.
Each email you send out has both the sender and from addresses:
- the sender domain is what the receiving email server gets when opening the session,
- the from address is what the recipient(s) will see.
For better deliverability, it is recommended to use the same from and sender addresses.
.size
.size : Integer
Description
IMAP transporter only.
The .size
property contains the size (expressed in bytes) of the Email object returned by the IMAP server.
.subject
.subject : Texte
Description
The .subject
property contains the description of topic.
.textBody
.textBody : Texte
Description
The .htmlBody
property contains theHTML representation of the email message (default charset is UTF-8) (optional, SMTP only). See Handling body part section.
.to
.to : Texte
.to : Objet
.to : Collection
Description
La propriété .to
contient le ou les destinataires principaux de l'e-mail.