Mobile Data StudioObject Model › Mailer

The Mailer class is a built-in helper that you can use to conveniently send email from Data Script.

An instance of the class can be instantited by calling the Project.NewMailer method:

Set mailer = Project.NewMailer

You will need an email account on an email server that supports the SMTP standard. Configure the server by setting the SMTPServer and related properties. Most email servers will require authentication before they will allow you to send email: configure this using the Username and Password properties.

The Mailer always sends a plain-text email body, set via the Body property. It can also send attachments of any type, either files from disk using AttachFileFromDisk, or files embedded in Session data using AttachFileFromValue.

If you wish to send en email with a HTML body in addition to the plain-text body, attach an HTML file as the first attachment, and set its attachmentName to the special value "inline".

Examples are available on the Sending an Email page.

Properties

Body

A String specifying the plain-text body of the email. Can include vbCrLf for newlines. Long lines will be wrapped to meet email standards.

This property must be set before calling the Send method.

See the AttachFileFromDisk method for how to attach an HTML file as a message body.

Password

A String specifying the password to be used when authenticating to the server.

Mailer supports PLAIN, LOGIN and CRAM-MD5 authentication standards. By default it will refuse to use PLAIN or LOGIN if the connection to the mail server is unencrypted, which would be bad security practice. You can override this behaviour by setting the SMTPProtocol property to "SMTP", indicating that you wish to use an unencrypted connection.

SMTPPort

An Integer with the port number of the SMTP server. Defaults to 587, the standard port number for submission with SMTP.

SMTPProtocol

A String specifying the encryption protocol to be used with the SMTP server:

  • "AUTO" - the default, will select based on the port number (port 465 will use "SMTPS", all other ports will use "STARTTLS" if available)
  • "SMTP" - use plain, unencrypted SMTP, even if the server offers STARTTLS
  • "SMTPS" - use SMTPS, i.e. TLS immediately upon connection
  • "STARTTLS" - use SMTP initially, but require upgrade to TLS with STARTTLS, failing if the server does not support STARTTLS

See also SMTPValidateCertificate.

SMTPServer

A String with the hostname of the SMTP server.

This property must be set before calling the Send method.

SMTPValidateCertificate

A Boolean that indicates whether the Mailer should validate the SMTP server's TLS certificate using the local system's list of approved certificate authorities. Defaults to True.

Many mail servers will use a self-signed TLS certificate if they are not configured with a certificate authority-issued certificate. This allows "opportunistic" encryption, which is arguably better than no encryption. However validation of such a certificate will fail. This property can be set to False to allow the connection.

Subject

A String specifying the subject of the email. This property must be set before calling the Send method.

Token

A String value that has no meaning to the class, but which will be passed to OnMailerFinished() in Data Script when the email has been sent, or failed to send. If no token is set, OnMailerFinished() will not be run.

Username

A String specifying the username to be used when authenticating to the server.

Methods

SetFrom

Sets the from/sender details. Calling this method multiple times will overwrite the previous values.

Takes two parameters:

  • name - a String containing the human-friendly name of the sender.
  • address - a String containing the email address of the sender.

AddTo

Adds a normal recipient. Calling this method multiple times will add additional recipients.

Takes two parameters:

  • name - a String containing the human-friendly name of the recipient.
  • address - a String containing the email address of the recipient.

AddCC

Adds a carbon-copy recipient. Calling this method multiple times will add additional recipients.

Takes two parameters:

  • name - a String containing the human-friendly name of the recipient.
  • address - a String containing the email address of the recipient.

AddBCC

Adds a blind carbon-copy recipient. Calling this method multiple times will add additional recipients. Blind carbon-copy recipients receive the email, but are not mentioned anywhere in its headers.

Takes two parameters:

  • name - a String containing the human-friendly name of the recipient.
  • address - a String containing the email address of the recipient.

AttachFileFromDisk

Attaches a file to the email being composed. The file is read immediately, before this method returns, so it is OK to delete it from disk if it is no longer needed.

Takes three parameters:

  • fileName - a String containing the filename of the file to attach, with directory.
  • attachmentName - the name of the attachment, without directory. If this is an empty string, name will be taken from fileName.
  • mimeType - the MIME type of the attachment, for example "application/pdf". If this is an empty string, it will be guessed based on the file extension.

Note that if this is the first attachment, and attachmentName is "inline", and mimeType is "text/html", this attachment will be the HTML message body, to be displayed to the recipient instead of the plain-text body as set by the Body property.

AttachFileFromValue

When working with Session data, you may have files (such as images) embedded in session values, from points like the Camera point.

You could of course use the Database.SaveToFile method to first save such a file to disk, then call the AttachFileFromDisk method above. However with AttachFileFromValue you can add the embedded file directly from the session.

Takes three parameters:

  • fileValue - the value with an embedded file to attach.
  • attachmentName - the name of the attachment. If this is an empty string, it will be taken from the name of the file embedded in fileValue.
  • mimeType - the MIME type of the attachment, for example "image/jpeg". If this is an empty string, it will be guessed based on the file extension.

ClearAttachments

Takes no parameters, and clears all attachments from the email being composed.

ClearRecipients

Takes no parameters, and clears all normal and carbon-copy recipients from the email being composed. Does not clear the from address / sender.

Send

Takes no parameters, and sends the email that has been composed to the email server.

The following properties must have been set before calling this method:

The following methods must have been called at least once before this method:

Note that the email will be sent asynchronously, i.e. this method will return immediately, before the email has actually been sent. If you wish to be informed as to the success or failure of this method, set the Token property before calling Send, and then handle that token in OnMailerFinished() in Data Script.

As soon as this method returns, the mailer object can be reused to start sending another email. There is no need to wait for the previous email to be sent, nor to create a new mailer. You may wish to call the ClearAttachments and/or ClearRecipients methods.