Sending Email¶

SMTP Email Basics¶

Email messages are queued using the email_send method. All outgoing messages are stored in tables of the Site database. The queue can be examined and messages removed in the Email Queue section of Lasso Server Admin.

Lasso’s email system checks the queue periodically and sends any waiting messages. If the email system encounters an error when sending an email then it stores the error in the database and requeues the message. If too many errors are encountered then the message send will be cancelled.

By default, Lasso sends queued messages directly to the SMTP server that corresponds to each recipient address. This means that a single message may end up being sent to multiple SMTP servers in order to deliver it to each recipient. It is also possible to specify SMTP hosts directly within the email_send method.

By default Lasso will send up to 100 messages to each SMTP server with every connection. Lasso will open up to five outgoing SMTP connections at a time. Lasso selects messages to send in order of priority, but once it connects to an SMTP server it delivers as many messages as possible. This means that a batch send to an SMTP server will contain high-priority messages as well as medium- and low-priority messages.

Composing and Sending Email¶

The email_send method is used to send email from Lasso. This method supports the most common types of email including plain text, HTML, HTML with a plain text alternative, embedded HTML images, and attachments.

email_send(-subject, -from, ...)¶

Adds a message to the email queue. The method requires a -subject parameter, a -from parameter, and one of either -to, -cc, or -bcc parameters. Also required is one of either -body or -html parameters. Below is a description of each of the parameters.

Parameters:

-subject – The subject of the message. Required. -from – The sender of the message. Required. -to – The recipient of the message. Multiple recipients can be specified by separating their email addresses with commas. -cc – Carbon copy recipients of the message. -bcc – Blind carbon copy recipients of the message. -body – The body of the message. Either a -body or -html part (or both) is required. See the section Send HTML Messages for details about how to create HTML and mixed messages. -html – The HTML part of the message. Either a -body or -html part (or both) is required. -htmlImages – Specifies a list of files that will be used as images for the HTML part of an outgoing message. Accepts either an array of file paths or an array of pairs containing a file name as the first part and the data for the file as the second part. -attachments – Specifies a list of files that will be attached to the outgoing message. Accepts either an array of file paths or an array of pairs containing a file name as the first part and the data for the file as the second part. -tokens – Specifies a map of token names and values that will be merged into the email message. The same tokens will be used on every message. -merge – Specifies a map of email addresses. Each email address should have as its value a map of token names and values. The values in this merge map will override those in the tokens map if both are specified. -priority – Specifies the priority of the message. Valid values include “High” or “Low”. Default is “Medium”. -replyTo – The email address that should be used for replies to this message. -sender – The email address that should be reported as the sender of this message. -transferEncoding – The value for the Transfer-Encoding header of the message. -contentType – The value for the Content-Type header of the message. -characterSet – The character set in which the message should be encoded. -extraMIMEHeaders – A pair array defining extra MIME headers that should be added to the email message. -immediate – If specified then the email is sent immediately without using the outgoing message queue. This option can be used for messages that have very large attachments. -host – SMTP host through which to send messages. -port – SMTP port. Defaults to “25”. -username – Specifies the username for SMTP AUTH if required by the SMTP server. If specified a -password is also required. -password – Specifies the password for SMTP AUTH if required by the SMTP server. If specified a -username is also required. -timeout – Specifies the timeout for the SMTP server in seconds. -ssl – If specified then SSL is used when connecting to the SMTP server. -simpleform – If specified then the message is sent without a body. -date – A date object specifying a time in the future to send the message.

email_send(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -subject = 'An Email',
   -body    = 'This is the body of the email.'
)

local(email_body) = 'This is the body of the email'
#email_body += '\nSent on: ' + server_date + ' at ' + server_time
#email_body += '\nCurrent visitor: ' + client_username + ' at ' + client_ip

email_send(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -subject = 'An Email',
   -body    = #email_body
)

email_send(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -subject = 'An Email',
   -body    = include('format.lasso')
)

email_send(
   -to      = 'example@example.com, someone@example.com',
   -from    = 'example@example.com',
   -subject = 'An Email',
   -body    = include('format.lasso')
)

local(president) = 'president@example.com'
local(someone)   = 'someone@example.com'

email_send(
   -to      = 'example@example.com',
   -cc      = #president + ',' + #someone,
   -from    = 'example@example.com',
   -subject = 'An Email',
   -body    = include('format.lasso')
)

email_send(
   -to      = 'announce@example.com',
   -bcc     = 'example@example.com, someone@example.com',
   -from    = 'example@example.com',
   -subject = 'An Email',
   -body    = include('format.lasso')
)

<h2>Money Saving Coupon</h2>
<p>Print out the money saving coupon below or click on it to order directly from our website.<br />
   <a href="http://www.example.com/couponoffer.html">
      <img src="http://www.example.com/couponoffer.gif" border="0" width="288" height="288" />
   </a>
</p>

email_send(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -subject = 'An HTML Email',
   -html    = include('email_body.html')
)

email_send(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -subject = 'A Multi-Part Email',
   -body    = include('format.lasso'),
   -html    = include('email_body.html')
)

email_send(
   -to         = 'example@example.com',
   -from       = 'example@example.com',
   -subject    = 'An HTML Email With Embedded Image',
   -html       = '<h2>Embedded Image</h2><br /><img src="myimage.jpg" />',
   -htmlImages = array('myimage.jpg'=include_raw('/apache_pb.jpg'))
)

email_send(
   -to          = 'example@example.com',
   -from        = 'example@example.com',
   -subject     = 'An Email with Two Attachments',
   -body        = 'This is the body of the Email.',
   -attachments = array('MyAttachment.txt', 'MyAttachment2.txt')
)

local(my_file) = pdf_doc(-size='A4', -margin=(: 144.0, 144.0, 72.0, 72.0))
#my_file->add(
   pdf_text("I'm a PDF document", -font=pdf_font(-face='Helvetica', -size=36))
)

email_send(
   -to          = 'example@example.com',
   -from        = 'example@example.com',
   -subject     = 'An Email with a PDF',
   -body        = 'This is the body of the Email.',
   -attachments = array('MyPDF.pdf'=string(#my_file))
)

email_send(
   -to       = 'example@example.com',
   -from     = 'example@example.com',
   -subject  = 'Password Reset Instructions',
   -body     = include('password_reset.lasso'),
   -priority = 'High'
)

email_send(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -replyTo = 'repsonses@example.com',
   -sender  = 'otheruser@example.com',
   -subject = 'An Email',
   -body    = include('format.lasso')
)

email_send(
   -to               = 'example@example.com',
   -from             = 'example@example.com',
   -subject          = 'An Email',
   -body             = include('format.lasso'),
   -extraMIMEHeaders = array('Header'='Value', 'Header'='Value')
)

email_send(
   -host     = 'mail.example.com',
   -username = 'SMTP_USER',
   -password = 'USER_PASS',
   -timeout  = 120,
   -to       = 'example@example.com',
   -from     = 'example@example.com',
   -subject  = 'An Email',
   -body     = include('format.lasso')
)

Email Merge¶

Lasso can merge values into email messages just before sending them. This allows a single email message to be composed and then customized for several recipients. The -tokens and -merge parameters make this possible.

In order to use the -tokens and -merge parameters the email message must contain one or more email tokens. The preferred method for specifying tokens is to use the email_token method. In plain text messages or messages that can’t be processed through Lasso the #TOKEN# marker can be used instead. For example, the method call email_token('FirstName') corresponds to the marker #FirstName#.

email_token(name::string)¶

Email tokens are created using this method. It requires a single value containing the name of the email token.

For example, an email message can be marked up with email tokens for the first name and last name of the recipient. The start of the message, stored in a file called “body.lasso” could be:

<p>Dear [email_token('FirstName')] [email_token('LastName')],</p>

The email message is going to be sent to two recipients: “John Doe” at “john@example.com” and “Jane Doe” at “jane@example.com”. Each element of the merge map includes an email address as the key and a map of token values as its value, constructed as follows:

local(myMergeTokens) = map(
   'john@example.com' = map('FirstName'="John", 'LastName'="Doe"),
   'jane@example.com' = map('FirstName'="Jane", 'LastName'="Doe"),
)

A default token map can also be constructed. The values from this map would be used if any tokens are missing from the specified email address maps shown above.

local(myDefaultTokens) = map('FirstName'="Lasso User", 'LastName'="")

The email_send method call would be written as follows. The email message is being sent to two recipients. The method references “body.lasso” as the -body of the email message that has the included email_token methods, -merge specifies #myMergeTokens, and -tokens specifies #myDefaultTokens.

email_send(
   -to      = 'john@example.com, jane@example.com',
   -from    = 'example@example.com',
   -subject = 'Mail Merge',
   -body    = include('body.lasso'),
   -merge   = #myMergeTokens,
   -tokens  = #myDefaultTokens

The message to John Doe would contain this text:

Dear John Doe,

email_merge(data, tokens, charset=?, transferEncoding=?)¶

Allows the email merge operation to be performed on any text. Requires two parameters: the text that is to be modified and a map of tokens to be replaced in the text. The optional charset and transferEncoding parameters can specify what type of encoding should be applied to the merged tokens.

Email Sending Status¶

Email messages that are sent using the email_send method are stored in an outgoing email queue temporarily and then sent by a background process. Any errors encountered when sending a message can be viewed in the Email Queue section of Lasso Server Admin.

However, it is often desirable to get information about a message that was sent programatically without examining the queue table. The following documented methods allow examining the status of a recently sent message.

email_result()¶

Can be called immediately after calling email_send to get a unique ID string for the queued message.

email_status(id)¶

Requires an ID from the email_result method and returns the status of the queued message: “sent”, “queued”, or “error”.

The following example shows an email_send method call that sends a message. The email_result method is called immediately after to store the unique ID of the sent message. After a delay of 30 seconds the email_status method is called to see if the message was successfully sent.

email_send(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -subject = 'An Email',
   -body    = 'This is the body of the email.'
)
local(my_email) = email_result
sleep(30000)
email_status(#my_email)

In a practical solution the unique ID returned by email_result would be stored in a session variable or in a database table and then would be checked sometime later using email_status to see if the email message was sent or if the address it was sent to was invalid.

Composing and Queueing Email¶

The email_send method handles all of the most common types of email that can be sent through Lasso including plain text messages, HTML messages, HTML messages with a plain text alternative messages, and messages with attachments.

For more complex messages structures the email_compose type can be used directly to create the MIME text of the message. The message can then be sent with the email_queue method. Both of these methods are used internally by email_send.

The email_compose type accepts the same parameters as email_send except those which specify the SMTP server and priority of the outgoing message. After creating an object with email_compose, member methods can add additional text parts, HTML parts, attachments, or generic MIME parts. This allows very complex email structures to be created with much more control than email_send provides.

The email_compose type can also create email parts. When the creator method is called without a -to, -from, or -subject parameter, a MIME part is created rather than a complete email message. This part can then be fed into the email_compose->addPart method or into the -attachments or -htmlImages parameters to place the part within a complex email message.

The email_queue method is designed to be fed an email_compose object. It requires three parameters: the -data, -from, and -recipients parameters as attributes of an email_compose object. Additionally, SMTP server parameters and the sending priority can be specified just like in email_send. Queued emails must be less than 8 MB in size including all encoded attachments.

The email_immediate method takes the same parameters as the email_queue method, but sends the message immediately rather than adding it to the email queue. This method can send messages larger than 8 MB if required. Use of the email_immediate method is not recommended since it bypasses the priority, error-handling, and connection-handling features of the email sending system.

type email_compose¶

email_compose(-to=?, -from=?, -cc=?, -bcc=?, -subject=?, -sender=?, -replyTo=?, -body=?, -html=?, -date=?, -contentType=?, -characterSet=?, -transferEncoding=?, -contentDisposition=?, -headerType=?, -extraMIMEHeaders=?, -attachments=?, -attachment=?, -htmlImages=?, -parts=?)

Creates an email_compose object, accepting similar parameters as email_send. If the -to, -from, and -subject parameters are not specified then a MIME part is created, otherwise a full MIME email is created.

email_compose->addAttachment(-data=?, -name=?, -path=?, -type=?)¶

Adds an attachment to an email_compose object. The data of the attachment can be specified directly in the -data parameter or the path to a file can be specified in the -path parameter. The name of the attachment can be specified in the -name parameter. The MIME type can be specified with the -type parameter.

email_compose->addHTMLPart(-data=?, -path=?, -images=?)¶

Adds an HTML part to an email_compose object. The text of the HTML part can be specified directly in the -data parameter or the path to a file can be specified in the -path parameter. Additionally, the -images parameter can take the same values as the -htmlImages parameter of the email_send method.

email_compose->addTextPart(-data=?, -path=?)¶

Adds a text part to an email_compose object. The text of the part can be specified directly in the -data parameter or the path to a file can be specified in the -path parameter.

email_compose->addPart(-data=?)¶

Adds a generic part to an email_compose object. Requires a parameter -data specifying the data for the part. The part must be properly formatted as a MIME part. No formatting or encoding will be performed by Lasso.

email_compose->data(-prefix::boolean=?, -force::boolean=?)¶

Returns the MIME text of the composed email.

email_compose->from()¶

Returns the from address of the composed email.

email_compose->recipients()¶

Returns a list of recipients of the composed email.

email_batch()¶

When passed a capture block of code, it temporarily suspends some back-end operations of the email queue so that a batch of email messages can be queued quickly. Any messages that are already queued will continue to send while the code in the specified block is running.

email_queue(-data=?, -recipients=?, -from=?, -host=?, -username=?, -password=?, -port=?, -timeout=?, -priority=?, -tokens=?, -merge=?, -date=?, -ssl=?)¶

Queues a message for sending. Requires a -data parameter with the MIME text of the email to send, -from specifying the from address for the email, and -recipients an array of recipients for the email. Can also accept -priority and SMTP server -host, -port, -timeout, ``-username, and -password parameters. A different -tokens parameter can be specified for each queued message to perform an email merge.

email_immediate(-data, -recipients=?, -from=?, -host=?, -username=?, -password=?, -port=?, -timeout=?, -ssl=?)¶

The same as email_queue, but sends the message immediately without storing it in the database.

local(message) = email_compose(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -subject = 'Example Message',
   -body    = 'Example Message'
)

<pre>[#message->asString->encodeHtml]</pre>

#message->addAttachment(-path='ExampleFile.txt')

email_queue(
   -data       = #message->data,
   -from       = #message->from,
   -recipients = #message->recipients
)

email_batch => {
   inline(-search, ...) => {
      records => {
         email_send(-from='sender@example.com', -to=field('email_address'), ...)
      }
   }
}

Sending SMTP Commands¶

All communication with remote SMTP servers is handled by a type called email_smtp. These connections are normally handled automatically by the email_send, email_queue, email_immediate, and background email sending processes.

The email_smtp type can be used directly for low-level access to remote SMTP servers, but this is not generally necessary.

type email_smtp¶

email_smtp(-host::string=?, -port::integer=?, -timeout::integer=?, -username=?, -password=?, -ssl::boolean=?, -clientIp=?)

Creates a new SMTP connection object. Can optionally pass in the SMTP server parameters.

email_smtp->open(-host=?, -port=?, -timeout=?, -username=?, -password=?, -ssl=?, -clientIp=?)¶

Requires a -host specifying the SMTP host to connect to. Also accepts optional -port, -username, -password, and -timeout parameters.

email_smtp->command(-send=?, -expect=?, -multi=?, -read=?, -timeout=?)¶

Sends a raw command to the SMTP server. The -send parameter specifies the command to send. The -expect parameter specifies the numeric result code that is expected as a result. Returns “true” or “false” depending on whether the expected result code was found. The -read parameter can be specified to have it return the result from the SMTP server.

email_smtp->send(-from::string, -recipients::array, -message::string)¶

Sends a single message to the SMTP server. Requires a -message parameter with the MIME data for the message, -recipients with an array of recipient email address, and -from with the email address of the sender.

email_smtp->close()¶

Closes the connection to the remote server.

email_mxlookup(domain, -refresh=?, -hostname=?)¶

Requires a domain as a string parameter and returns a map that describes the MX server for the domain. The map includes the ‘domain’, ‘host’, ‘username’, ‘password’, ‘timeout’, and ‘SSL’ preference for the MX server.

email_mxlookup('gmail.com')
// => map(domain = gmail.com, host = gmail-smtp-in.l.google.com, priority = 5)

local(message) = email_compose(
   -to      = 'example@example.com',
   -from    = 'example@example.com',
   -subject = 'Example Message',
   -body    = 'Example Message'
)
local(smtp) = email_smtp

#smtp->open(
   -host     = 'smtp.example.com',
   -port     = 25,
   -username = 'SMTPUSER',
   -password = 'mysecretpassword',
   -timeout  = 60
)
#smtp->send(
   -from       = #message->from,
   -recipients = #message->recipients,
   -message    = #message->data + '\r\n'
)
#smtp->close