Version: 19

Email

Creating, sending or receiving emails in 4D is done by handling an Email object.

Email objects are created when receiving mails through a transporter class function:

IMAP - .getMail() and .getMails() functions to get emails from an IMAP server
POP3 - .getMail() function to get an email from a POP3 server.

You can also create a new, blank Email object and then fill it with Email object properties.

You send Email objects using the SMTP .send() function.

MAIL Convert from MIME and MAIL Convert to MIME commands can be used to convert Email objects to and from MIME contents.

Email Object

Email objects provide the following properties:

4D follows the JMAP specification to format the Email object.


.attachments : Collection collection of `4D.MailAttachment` 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 `bodyStructure` (optional)
.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 `EmailHeader` objects, in the order they appear in the message
.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 : Text message identifier header ("message-id")
.receivedAt : Text timestamp of the email's arrival on the IMAP server in ISO 8601 UTC format (ex: 2020-09-13T16:11:53Z)
.references : Collection Collection of all message-ids of messages in the preceding reply chain
.replyTo : Text .replyTo : Object .replyTo : Collection addresse(s) for responses
.sendAt : Text Email timestamp in ISO 8601 UTC format
.sender : Text .sender : Object .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 : Text description of topic
.textBody : Text Plain text representation of the email message (default charset is UTF-8) (optional, SMTP only)
.to : Text .to : Object .to : Collection primary recipient addresse(s) of the email

Email Addresses

All properties that contain email addresses (from, cc, bcc, to, sender, replyTo) accept a value of text, object, or collection type.

Text

single email: "somebody@domain.com"
single display name+email: "Somebody somebody@domain.com"
several emails: "Somebody somebody@domain.com,me@home.org"

Object

An object with two properties:

Property	Type	Description
name	Text	Display name (can be null)
email	Text	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 4D.MailAttachment object(s).

Attachment objects are defined through the MAIL New attachment command. Attachment objects have specific properties and functions.

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

Property	Type	Value
partID	Text	Identifies the part uniquely within the email
type	Text	(mandatory) Value of the Content-Type header field of the part
charset	Text	Value of the charset parameter of the Content-Type header field
encoding	Text	If `isEncodingProblem=true`, the Content-Transfer-Encoding value is added (by default undefined)
disposition	Text	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	Text	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:

Property	Type	Value
partID.value	text	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, the EmailHeader property is ignored.

Every object of the headers collection can contain the following properties:

Property	Type	Value
[].name	text	(mandatory) Header field name as defined in RFC#5322. If null or undefined, the header field is not added to the MIME header.
[].value	text	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).

Property	Type	Value
.<keyword>	boolean	Keyword to set (value must be true)

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

Example

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

.messageId

.messageId : Text

Description

The .messageId property contains a message identifier header ("message-id").

This header is usually "lettersOrNumbers@domainname", e.g. "abcdef.123456@4d.com". This unique ID is used in particular on forums or public mailing lists. In general, mail servers automatically add this header to the messages they send.

.receivedAt

.receivedAt : Text

Description

IMAP transporter only.

The .receivedAt property contains the timestamp of the email's arrival on the IMAP server in ISO 8601 UTC format (ex: 2020-09-13T16:11:53Z).

.references

.references : Collection

Description

The .references property contains the Collection of all message-ids of messages in the preceding reply chain.

For specific formatting requirements, please consult the RFC#5322.

.replyTo

.replyTo : Text
.replyTo : Object
.replyTo : Collection

Description

The .replyTo property contains the addresse(s) for responses.

.sendAt

.sendAt : Text

Description

The .sendAt property contains the Email timestamp in ISO 8601 UTC format.

.sender

.sender : Text
.sender : Object
.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 : Text

Description

The .subject property contains the description of topic.

.textBody

.textBody : Text

Description

The .textBody property contains the Plain text representation of the email message (default charset is UTF-8) (optional, SMTP only). See Handling body part section.

.to

.to : Text
.to : Object
.to : Collection

Description

The .to property contains the primary recipient addresse(s) of the email.

MAIL Convert from MIME

History

Release	Changes
18	Added

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

Parameter	Type		Description
mime	Blob, Text	->	Email in MIME
Result	Object	<-	Email object

Description

The MAIL Convert from MIME command converts a MIME document into a valid email object.

4D follows the JMAP specification to format the returned email object.

Pass in mime a valid MIME document to convert. It can be provided by any mail server or application. You can pass a BLOB or a text mime parameter. If the MIME comes from a file, it is recommended to use a BLOB parameter to avoid issues related to charset and line break conversions.

Returned object

Email object.

Example 1

You want to load a mail template saved as MIME in a text document and send an 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)

Example 2

In this example, you send directly a 4D Write Pro document containing pictures:

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

// Mime export of the 4D Write Pro document
WP EXPORT VARIABLE(WParea;$mime;wk mime html)

// convert 4D Write Pro Mime variable in mail object
$email:=MAIL Convert from MIME($mime)

// Fill your mail object headers
$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

History

Release	Changes
17 R4	Added
17 R5	Modified

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

Parameter	Type		Description
mail	Object	->	Email object
options	Object	->	Charset and encoding mail options
Result	Text	<-	Email object converted to MIME

Description

The MAIL Convert to MIME command converts an email object into MIME text. This command is called internally by SMTP_transporter.send( ) to format the email object before sending it. It can be used to analyze the MIME format of the object.

In mail, pass the content and the structure details of the email to convert. This includes information such as the email addresses (sender and recipient(s)), the message itself, and the type of display for the message.

4D follows the JMAP specification to format the email object.

In options, you can set a specific charset and encoding configuration for the mail. The following properties are available:

Property

Type

Description

headerCharset

Text

Charset and encoding used for the following parts of the email: subject, attachment filenames, and email name attribute(s). Possible values:

Constant	Value	Comment
mail mode ISO2022JP	US-ASCII_ISO-2022-JP_UTF8_QP	headerCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & Quoted-printable if possible, otherwise UTF-8 & Quoted-printable bodyCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & 7-bit if possible, otherwise 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 if possible, otherwise UTF-8 & Quoted-printable (default value)
mail mode UTF8 in base64	US-ASCII_UTF8_B64	headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & base64

bodyCharset

Text

Charset and encoding used for the html and text body contents of the email. Possible values: Same as for headerCharset (see above)

If the options parameter is omitted, the mail mode UTF8 configuration is used for header and body parts.

Example

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

// Creation of a 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--

Email Object​

Email Addresses​

Text​

Object​

Collection​

Handling body part​

Example of bodyStructure and bodyValues objects​

.attachments​

Description​

.bcc​

Description​

.bodyStructure​

Description​

.bodyValues​

Description​

.cc​

Description​

.comments​

Description​

.from​

Description​

.headers​

Description​

.htmlBody​

Description​

.id​

Description​

.inReplyTo​

Description​

.keywords​

Description​

Example​

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

Returned object​

Example 1​

Example 2​

MAIL Convert to MIME​

Description​

Example​

Email Object

Email Addresses

Text

Object

Collection

Handling body part

Example of bodyStructure and bodyValues objects

.attachments

Description

.bcc

Description

.bodyStructure

Description

.bodyValues

Description

.cc

Description

.comments

Description

.from

Description

.headers

Description

.htmlBody

Description

.id

Description

.inReplyTo

Description

.keywords

Description

Example

.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

Returned object

Example 1

Example 2

MAIL Convert to MIME

Description

Example