Skip to main content

Email

Creating, sending or receiving emails in Qodly 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 by calling the New object command, and then fill it with Email object properties.

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

mailConvertFromMIME and mailConvertToMIME commands can be used to convert Email objects to and from MIME contents.

Properties​

Email objects provide the following properties:

QodlyScript follows the JMAP specification to format the Email object.

.attachments : collection    collection of 4D.MailAttachment object(s)
.bcc : string
.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 : string
.cc : object
.cc : collection    Carbon Copy (CC) additional email recipient addresse(s) of the email
.comments : string    additional comments header
.from : string
.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 : string    HTML representation of the email message (default charset is UTF-8) (optional, SMTP only)
.id : string    unique ID from the IMAP server
.inReplyTo : string    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 : string    message identifier header ("message-id")
.receivedAt : string    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 : string
.replyTo : object
.replyTo : collection    addresse(s) for responses
.sendAt : string    Email timestamp in ISO 8601 UTC format
.sender : string
.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 : string    description of topic
.stringBody : string    Plain string representation of the email message (default charset is UTF-8) (optional, SMTP only)
.to : string
.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 string, object, or collection type.

String​

object​

An object with two properties:

PropertyTypeDescription
namestringDisplay name (can be null)
emailstringEmail address

collection​

A collection of address objects.

Handling body part​

The stringBody 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 string 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 stringBody and htmlBody.

Example of bodyStructure and bodyValues objects​

"bodyStructure": {
  "type": "multipart/mixed",
  "subParts": [
    {
      "partId": "p0001",
      "type": "string/plain"
    },
    {
      "partId": "p0002",
      "type": "string/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 = \"string/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 mailNewAttachment command. Attachment objects have specific properties and functions.

.bcc​

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

PropertyTypeValue
partIDstringIdentifies the part uniquely within the email
typestring(mandatory) Value of the Content-Type header field of the part
charsetstringValue of the charset parameter of the Content-Type header field
encodingstringIf isEncodingProblem == true, the Content-Transfer-Encoding value is added (by default undefined)
dispositionstringValue of the Content-Disposition header field of the part
languagecollection of stringsList of language tags, as defined in RFC3282, in the Content-Language header field of the part, if present.
locationstringURI, as defined in RFC2557, in the Content-Location header field of the part, if present.
subPartscollection of objectsBody parts of each child (collection of EmailBodyPart objects)
headerscollection of objectsList 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:

PropertyTypeValue
partID.valuestringValue of the body part
partID.isEncodingProblembooleanTrue if malformed sections are found while decoding the charset, or unknown charset, or unknown content transfer-encoding. False by default

.cc​

.cc : string
.cc : object
.cc : collection

Description​

The .cc property contains the Carbon Copy (CC) additional email recipient addresse(s) of the email.

.comments​

.comments : string

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

PropertyTypeValue
[].namestring(mandatory) Header field name as defined in RFC#5322. If null or undefined, the header field is not added to the MIME header.
[].valuestringHeader field values as defined in RFC#5322

.htmlBody​

.htmlBody : string

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

Description​

IMAP transporter only.

The .id property contains the unique ID from the IMAP server.

.inReplyTo​

.inReplyTo : string

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

PropertyTypeValue
.keywordbooleanKeyword 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["qodly"] = True

.messageId​

.messageId : string

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

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 : string
.replyTo : object
.replyTo : collection

Description​

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

.sendAt​

.sendAt : string

Description​

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

.sender​

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

Description​

The .subject property contains the description of topic.

.stringBody​

.stringBody : string

Description​

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

.to​

.to : string
.to : object
.to : collection

Description​

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