A common task is to send an email, often using data received from a Session.

The easiest way to do this is to use Mobile Data Studio's built-in Mailer class. An instance of this class can be instantiated with:

Set mailer = Project.NewMailer

Configuring the Mail Server

You must first configure the Mailer object to use your SMTP mail server:

mailer.SMTPServer = "smtp.example.com"
mailer.Username = "myusername"
mailer.Password = "mypassword"

This assumes the mail server uses the default submission port, 587, and STARTTLS security. If this is not the case for your mail server, you may need to modify the SMTPPort and/or SMTPProtocol properties.

If your mail server uses a proper TLS certificate, it should validate correctly. If it uses a self-signed certificate for "opportunistic" encryption, you may need to disable SMTPValidateCertificate.

See the Mailer class reference for other properties that can be set.

Adding Addresses

You must specify the From address:

mailer.SetFrom "My Name", "myusername@example.com"

And at least one normal recipient address:

mailer.AddTo "Someone Else", "anotheruser@example.com"

You can call AddTo multiple times to add multiple recipients. See also AddCC and AddBCC.

Adding Subject and Body

You must specify the email subject, and body text:

mailer.Subject = "The email subject"
mailer.Body = "The email body," & vbCrLf & "Note the lewline."

It may be more convenient to build up the body string over several script statements, then finally assign it to the Body property.

Attaching Files

You can add attachments using the AttachFileFromDisk and AttachFileFromValue functions.

The former is well suited to emailing an output file that was generated by the Data Pathway, in which case your email code should be run in OnIncomingSessionDeferred(), so that the file exists and is ready to be attached.

The latter is well suited to attaching files that are embedded in the session, such as photographs from the Camera point. As these values with embedded files already exist in the session, it does not matter at which stage of Data Pathway processing they are accessed.

Let's attach a JPEG image file:

mailer.AttachFileFromDisk "C:\Path\Image.jpg", "", ""

Note that the 2nd parameter is an empty string, indicating that the attachment name should be guessed from the filename: in this case it will be "Image.jpg".

The 3rd parameter is also an empty string, indicating that the MIME type should be guessed from the filename as well: in this case it will be "image/jpeg".

Sending the Email

Simply call:

mailer.Send

Note that the Send method will return immediately, without waiting for the email to actually be sent. If you need to know that, see the documentation for the Mailer class, specifically Maler.Token.

You can now re-use the mailer object to send another email, but be sure to clear any values you don't want to carry forward, such as addresses.

Adding a HTML Body

All emails need to have a plain-text body, which can be set by using the Mailer.Body property.

However plain-text does not allow rich formatting, links or embedded images. To support these, you can provide an HTML body. Most email applications support this, and will display it instead of the plain-text body.

To add an HTML body, create an HTML file on disk, and then attach it as your first attachment, using the special attachmentName of "inline":

' Create an HTML file on disk here, save it to C:\Path\MyEmailBody.htm
' Then:
mailer.AttachFileFromDisk "C:\Path\MyEmailBody.htm", "inline", "text/html"