SMTP_transporter.send( )

Home

4D v18.4

Mail


SMTP_transporter.send ( mail ) -> Result

Parameter	Type	Description
mail	Object	Email to send
Result	Object	SMTP status

Description

The SMTP_transporter.send( ) method sends the mail object to the SMTP server defined in the transporter object and returns a status object.

Note: The transporter object must have already been created using the SMTP New transporter command.

The method creates the SMTP connection if it is not already alive. If the keepAlive property of the transporter object is false, the SMTP connection is automatically closed after the execution of SMTP_transporter.send( ), otherwise it stays alive until the transporter object is destroyed. For more information, please refer to the SMTP New transporter command description.

In mail, pass a valid mail object to send. The origination (where the email is coming from) and destination (one or more recipients) properties must be included, the remaining properties are optional. The properties supported are:

Property		Type	Description
from		Text \| Object \| Collection(*)	Originating address(es)(**)
cc		Text \| Object \| Collection(*)	Carbon Copy (CC). Additional email recipient(s)
bcc		Text \| Object \| Collection(*)	Blind Carbon Copy (BCC). Hidden email recipient(s)
to		Text \| Object \| Collection(*)	Primary recipient(s)
sender		Text \| Object \| Collection(*)	Email source address(es)(**)
replyTo		Text \| Object \| Collection(*)	Address(es) for responses
subject		Text	Description of topic
textBody		Text	Plain text representation of the email message (default charset is UTF-8)(***)
htmlBody		Text	HTML representation of the email message (default charset is UTF-8)(***)
sendAt		Text	Email timestamp (UTCDate)
attachments		Collection of objects	Collection of attachment object(s), see MAIL New attachment
messageId		Text	Message identifier header ("message-id"). 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.
inReplyTo		Text	Message identifier(s) of the original message(s) to which the current message is a reply (****).
references		Collection of text	Collection of all message-ids of messages in the preceding reply chain (****).
keywords		Object	"keywords" header. Contains a set of keywords as an object, where each property name is a keyword and each value is true. See RFC#4021.
	.<keyword>	Boolean	Keyword to set (value must be true). Ex: `$mail.keywords["$flagged"]:=True $mail.keywords["4d"]:=True`
comments		Text	Additional comments header. Comments only appear within the header section of the message (keeping the message's body untouched) (****).
headers		Collection of objects	Collection of EmailHeader objects, in the order they appear in the message. Allows users to add extended (registered) headers or user-defined (not registered, starting with "X") headers. Note: 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.
	[ ].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 name as defined in RFC#5322

Note: Header fields starting with "Content-" must NOT be specified in the mail object.

The following additional properties are used when the mail 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 htmlBody and textBody.

bodyStructure		Object	(optional) Full MIME structure of the message body (EmailBodyPart object)
	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 header property)
bodyValues		Object	(optional) EmailBodyValue object, containing an object for each partID of bodyStructure
	<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

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>"
  }
}

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

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

(***) If textBody and htmlBody are both 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.
It is recommended that these properties be omitted if bodyStructure and bodyValues are used.

(****) For specific formatting requirements, please consult RFC#5322.

Note: 4D follows the JMAP specification to format the mail object.

Returned object

SMTP_transporter.send( ) returns an object describing the SMTP status of the operation. This object can contain the following properties:

Property	Type	Description
success	Boolean	True if the send operation is successful, False otherwise
status	Number	Status code returned by the SMTP server
statusText	Text	Message returned by the SMTP server

Note: For information about SMTP status codes, please go to this page.

Error handling

In case of an issue unrelated to the SMTP processing (e.g. a mandatory property is missing in mail), 4D generates an error that you can intercept using a method installed by the ON ERR CALL command. Use the GET LAST ERROR STACK command for information about the error.

In this case, the resulting status object contains the following values:

success: false
status: 0
statusText: "Failed to send email"

Example

This code builds and sends an email:

 C_OBJECT($server)

 $server:=New object

 $server.host:="mail.smtp.host" // Mandatory

 $server.port:=25 // Optional, default value: 587

 

 $transporter:=SMTP New transporter($server)

 

 C_COLLECTION($headers) //add user-defined headers

 $headers:=New collection

 $headers.push(New object("name";"X-MAILER";"value";"MySoftware"))

 $headers.push(New object("name";"X-4D-VERSION";"value";"17Rx"))

 

 C_OBJECT($email)

 $email:=New object

 $email.subject:="my first mail"

 $email.to:="test.mail@4d.com"

 $email.from:="test.noreply@4d.com"

 $email.textBody:="this is a test"

 $email.attachments:=New collection(MAIL New attachment("schedule.xlsx"))

 $email.headers:=$headers

 $email.keywords:=New object("technical";True;"advanced";True;"useless";False)

 

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

 If(Not($status.success))

    ALERT("An error occurred sending the mail: "+$status.statusText)

 End if