Chapter 47
Sending Email

[p]This chapter describes how to send email using Lasso. [/p]

• Overview introduces the SMTP email sending system.
• Sending Email describes the [code][Email_Send][/code] tag.
• Email Status describes how to get information about messages sent using the [code][Email_Send][/code] tag.
• Composing Email describes the [code][Email_Compose][/code] tag which can be used to create more complex emails with multiple attachments and parts.
• SMTP Type describes the SMTP type that is used to actually send messages to remote servers.

[note][b]Note: [/b]The following Chapter 43: POP documents how to download email from a POP server using Lasso. [/note]

Overview

[p]Lasso includes a built-in system for queuing and sending email messages to SMTP servers. Email messages can be sent to site visitors to notify them when they create a new account or to remind them of their login information. Email messages can be sent to administrators when various errors or other conditions occur. Email messages can even be sent in bulk to many email addresses to notify site visitors of updates to the Web site or other news. [/p]

[p]Email messages are queued using the [code][Email_Send][/code] tag. All outgoing messages are stored in tables of the [code]Site[/code] database. The queue can be examined and started or stopped in the Utility > Email section of Site Administration. [/p]

[p]Lasso’s email system checks the queue periodically and sends any messages which are waiting. 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. [/p]

[p]By default, Lasso sends queued messages directly to the SMTP server which 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. Lasso can also be configured to route all messages through a local SMTP server in the Utility > Email > Setup section for Site Administration. An optional SMTP AUTH username and password allows Lasso to authenticate with the SMTP server in order to send messages. Lasso will use DIGEST or CRAM-MD5 authentication if the local SMTP server supports it. [/p]

[p]It is also possible to specify SMTP hosts directly within the [code][Email_Send][/code] tag. This can be useful if different SMTP servers need to be used for different purposes. For example, if one SMTP server needs to be used for internal company email and another for general Internet users. [/p]

[note][b]Note: [/b]If a local SMTP server is being used then Lasso must either have valid SMTP AUTH credentials or be otherwise allowed to send unrestricted messages through the SMTP server. Consult the SMTP server documentation for details about how to setup SMTP AUTH security or how to allow specific IP addresses to relay messages. [/note]

[p]By default Lasso will send up to 100 messages to each SMTP server every connection. Lasso will open up to 5 outgoing SMTP connections at a time. Lasso selects messages to send in priority order, 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. [/p]

[note][b]Important: [/b]The maximum size of an email message including all attachments should be less than 8MB using the [code][Email_Send][/code] tag. If necessary, larger messages can be sent using the [code][Email_Immediate][/code] tag described in the [def]Email Composing[/def] section. [/note]

[p]The email system is administered using the Utility > Email section of Site Administration. The Email Queue can be inspected and any errors which have occurred can be reviewed. Email messages can be queued manually using the Send Email page. The preferences for the email system, such as how often the queue is checked for messages or how many times messages are requeued if an error is detected, can be modified using the Setup page. [/p]

[note][b]Note: [/b]Lasso’s email system is written in LassoScript using the network tags. All of the source code for the email system is included open source within the code for [code]Startup.LassoApp[/code]. [/note]

[note][b]Upgrading [/b][b]Note[/b]: The [code]-Email.…[/code] command tags from Lasso 3 will not operate in Lasso 8. [/note]

Email Structure

[p]The structure of a composed email message will depend on what type of message is being sent. Lasso supports the following structure variations depending on what parameters are specified in the [code][Email_Send][/code] or [code][Email_Compose][/code] tags. [/p]

• Plain Text – Simple messages specified with a [code]-Body[/code] parameter are sent as a single [code]text/plain[/code] part with no boundaries.
• HTML – Simple HTML messages with an [code]-HTML[/code] parameter are sent as a single [code]text/html[/code] part with no boundaries.
• HTML with Plain Text – Messages which have both an [code]-HTML[/code] parameter and a [code]-Body[/code] parameter are sent as [code]multipart/alternative[/code] messages with both [code]text/plain[/code] and [code]text/html[/code] parts.
• HTML with Embedded Images – Messages which use [code]-HTMLImages[/code] replace the [code]text/html[/code] part with a [code]multipart/related[/code] part with enclosed [code]text/html[/code] and inline attachment parts.
• Attachments – Messages with attachments are sent [code]multipart/mixed[/code] and include the [code]text/plain[/code], [code]text/html[/code], [code]multipart/alternative[/code], or [code]multipart/related[/code] part which is appropriate based on the type of message and the attachment parts.

[p]See each of the following sections for details about how other [code][Email_Send][/code] and [code][Email_Compose][/code] parameters affect the composition of each part. [/p]

Sending Email

[p]The [code][Email_Send][/code] tag is used to send email messages from Lasso. This tag supports the most common types of email including plain text, HTML, HTML with a plain text alternative, embedded HTML images, and attachments. [/p]

Table 1: Email Tag

[table][tr][th]Tag[/th][th]Description[/th][th] [/th][/tr]

[tr][td][Email_Send][/td][td]Queues an email message. [/td][/tr]

[/table]

Plain Text Messages

[p]The [code][Email_Send][/code] tag accepts many parameters. The basic parameters for sending plain text messages are shown in the table below. Additional parameters for sending HTML email, adding attachments, controlling character set, etc. are included in a subsequent tables. [/p]

Table 2: [Email_Send] Parameters

[table][tr][th]Keyword[/th][th]Description[/th][th] [/th][/tr]

[tr][td]-To[/td][td]The recipient of the message. Multiple recipients can be specified by separating their email addresses with commas. Required. [/td][/tr]

[tr][td]-From[/td][td]The sender of the message. Required. [/td][/tr]

[tr][td]-Subject[/td][td]The subject of the message. Required. [/td][/tr]

[tr][td]-Body[/td][td]The body of the message. Either a -Body or -HTML part (or both) is required. See the following section on HTML Messages for details about how to create HTML and mixed message. [/td][/tr]

[tr][td]-CC[/td][td]Carbon copy recipients of the message. At least one of -To, -CC, or -BCC is required. [/td][/tr]

[tr][td]-BCC[/td][td]Blind carbon copy recipients of the message. At least one of -To, -CC, or -BCC is required. [/td][/tr]

[/table]

To send an email message:

[p]Use the [code][Email_Send][/code] tag with the desired parameters. The [code]-From[/code] parameter must be set to a valid email address. The [code]-Subject[/code] parameter must be set to the desired subject for the email message. One or more recipients must be specified using the [code]-To[/code], [code]-CC[/code], and [code]-BCC[/code] parameters. The body of the message can be specified using any of the three methods described here. [/p]

• An email can be sent with a hard-coded body by specifying the message directly within the [code][Email_Send][/code] tag. The following example shows an email sent to [code]example@example.com [/code]with a hard-coded message body.

[pre][Email_Send:
-To='example@example.com',
-From='example@example.com',
-Subject='An Email',
-Body='This is the body of the email.'] [/pre]

• The body of an email message can be assembled in a variable in the current Lasso page and then sent using the [code][Email_Send][/code] tag. The following example shows a variable [code]Email_Body [/code]which has several items added to it before the message is finally sent.

<?LassoScript
Variable: '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);

[pre]	Email_Send:
-To='example@example.com',
-From='example@example.com',
-Subject='An Email',
-Body=$Email_Body;
?>

[/pre]

• A Lasso page on the Web server can be used as the message body for an email message using the [code][Include] [/code]tag. A Lasso page created to be a message body should contain no extra white space. The following example shows a Lasso page [code]format.lasso [/code]which is contained in the same folder as the current Lasso page being used as the message body for an email. Any Lasso tags within [code]format.lasso [/code]will be executed before the email is sent.

[pre][Email_Send:
-To='example@example.com',
-From='example@example.com',
-Subject='An Email',
-Body=(Include: 'format.lasso')] [/pre]

To send an email message to multiple recipients:

[p]Email can be sent to multiple recipients by including their addresses as a comma delimited list in the [code]-To[/code] parameter, the [code]-CC[/code] parameter, or the [code]-BCC[/code] parameter. Multiple [code]-To[/code], [code]-CC[/code], or [code]-BCC[/code] parameters are not allowed. [/p]

• The following example shows an [code][Email_Send][/code] tag with two recipients in the [code]-To[/code] parameter. The recipients email addresses are specified with a comma between them [code]example@example.com, somone@example.com[/code]. No extraneous information such as the recipients real names should be included.

[pre][Email_Send:
-To='example@example.com, someone@example.com',
-From='example@example.com',
-Subject='An Email',
-Body=(Include: 'format.lasso')] [/pre]

• The following example shows an [code][Email_Send][/code] tag with one recipient in the [code]-To[/code] parameter and two recipients in the [code]-CC[/code] parameter. The carbon copy parameter is generally used to include recipients who are not the primary recipient of the email, but need to be informed of the correspondence. The addresses for the carbon copied recipients are stored in variables and concatenated together with a comma between them using a [code]+[/code] symbol.

[pre][Variable: 'President'='president@example.com']
[Variable: 'Someone'='someone@example.com']
[Email_Send:
-To='example@example.com',
-CC=($President + ',' + $Someone),
-From='example@example.com',
-Subject='An Email',
-Body=(Include: 'format.lasso')] [/pre]

• The following example shows an [code][Email_Send][/code] tag with one recipient in the [code]-To[/code] parameter and two recipients in the [code]-BCC[/code] parameter. The Blind Carbon Copy parameter can be used to send email to many recipients without disclosing the full list of recipients to everyone who receives the email. Each recipient will receive an email that contains only the address in the [code]-To[/code] parameter [code]announce@example.com[/code].

[pre][Email_Send:
-To='announce@example.com',
-BCC='example@example.com, someone@example.com',
-From='example@example.com',
-Subject='An Email',
-Body=(Include: 'format.lasso')] [/pre]

HTML Messages

[p]HTML messages can be sent from Lasso by specifying the HTML body for the message using the [code]-HTML[/code] parameter. Images can be embedded in the email message using the [code]-HTMLImages[/code] parameter. If a message includes both an [code]-HTML[/code] parameter and a [code]-Body[/code] parameter then it will be sent as a [code]multipart/alternative[/code] message so mail clients which do not recognize HTML messages will see only the plain text part. [/p]

Table 3: HTML Message [Email_Send] Parameters

[table][tr][th]Keyword[/th][th]Description[/th][th] [/th][/tr]

[tr][td]-HTML[/td][td]The HTML part of the message. Either a -Body or -HTML part (or both) is required. [/td][/tr]

[tr][td]-HTMLImages[/td][td]Specifies a list of files which 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 which include a file name as the first part and the data for the file as the second part. Optional. [/td][/tr]

[/table]

To send HTML email:

[p]HTML email can be easily sent using the [code][Email_Send][/code] tag using any of the following methods. [/p]

• An HTML Lasso page can be sent as the body of the message by using [code][Include][/code] as the parameter to the [code]-HTML[/code] parameter of [code][Email_Send][/code]. Image references or URLs in the HTML Lasso page should be specified fully qualified including the [code]http://[/code] prefix and server name. Alternately, images can be embedded within the email using the [code]-HTMLImages[/code] parameter shown below.

[pre][Email_Send:
-To='example@example.com',
-From='example@example.com',
-Subject='A HTML Email',
-HTML=(Include: 'email_body.html')] [/pre]

• For example, the following HTML would reference an example Web page and an image which shows a coupon graphic. Both addresses are fully specified since they will need to be loaded from within the email client without any other information about the Web server. Note that any Lasso tags inside the Lasso page will be processed by Lasso before it is served.

[pre]<h2>Money Saving Coupon</h2>
<p>
Print out the money saving coupon below or click on it to order directly from our Web site.<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> [/pre]

• A plaintext/HTML alternative email can be sent by specifying both a [code]-Body[/code] parameter and an [code]-HTML[/code] parameter. The text of both parts should be equivalent. Recipients with text-based email clients will see the text part while recipients with HTML-based email clients will see the HTML part.

[pre][Email_Send:
-To='example@example.com',
-From='example@example.com',
-Subject='A Multi-Part Email',
-Body=(Include: 'format.lasso'),
-HTML=(include: 'email_body.html')] [/pre]

• If equivalent text and HTML parts can’t be generated then it is preferable to send just an HTML part. Email clients which don’t render HTML will display the raw HTML to the user, but this is preferable to seeing a message which simply says that the message was sent as HTML. The text part for the email message shown above might read as follows.

[pre]Money Saving Coupon
Click on the following link to display a money saving coupon which can be printed and used in our store or to order directly from our Web site.
<http://www.example.com/couponoffer.html> [/pre]

• HTML messages can include embedded images using the [code]-HTMLImages[/code] parameter. This parameter can be specified with either a single file name or an array of file names. Within the email message the images can be referenced in two ways.
• If the [code][Email_Send][/code] contains the parameter [code]-HTMLImages=(Array: '/apache_pb.gif')[/code] then Lasso will automatically fix any HTML [code]<img>[/code] tags that have that same image referenced in their [code]src[/code] parameter. Note that the path must be exactly the same for Lasso to be able to make this replacement.

[pre]<img src="/apache_pb.gif" /> [/pre]

[pre][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="/apache_pb.gif" />',
-HTMLImages=(Array: '/apache_pb.gif'); [/pre]

• Alternately, the [code]Content-ID[/code] of the embedded image should be referenced in the [code]<img>[/code] tag following a [code]cid:[/code] prefix. Lasso automatically uses the image file name as the [code]Content-ID[/code] without any path information so the same image referenced above can also be referenced like this.

[pre]<img src="cid:apache_pb.gif" /> [/pre]

[pre][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="cid:apache_pb.gif" />',
-HTMLImages=(Array: '/apache_pb.gif'); [/pre]

• Images which are generated programatically can be embedded in an HTML message by specifying a pair including the name of the image and the data of the image. In the example below the image data comes from the [code][Include_Raw][/code] tag, but it could also be generated using the [code][Image][/code] tags or retrieved from a database field. Note that the name of the image does not have to match, but the name which is specified in the first part of the pair should be used within the HTML body.

[pre] [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.gif" />',
-HTMLImages=(Array: ‘myimage.gif' = (Include_Raw: ‘apache_pb.gif’)); [/pre]

Attachments

[p]Lasso allows files to be sent as attachments with outgoing email messages. Any file that Lasso can read can be sent as an attachment. Images which are to be displayed inline within an HTML message should be specified using the [code]-HTMLImages[/code] parameter described above. [/p]

Table 4: Attachment [Email_Send] Parameters

[table][tr][th]Keyword[/th][th]Description[/th][th] [/th][/tr]

[tr][td]-Attachments[/td][td]Specifies a list of files which will be attached to the outgoing message. Accepts either an array of file paths or an array of pairs which include a file name as the first part and the data for the file as the second part. Optional. [/td][/tr]

[/table]

To send attachments with an email message:

[p]Files can be included as attachments to email messages using the [code]-Attachments[/code] parameter. This parameter takes an array of file paths as a value. When the email is sent, each file is read from disk and encoded using Base-64 encoding. The recipient’s email client will automatically decode the attached files and make them available. [/p]

[note][b]Important: [/b]The maximum size of an email message including all attachments must be less than 8MB using the [code][Email_Send][/code] tag. If necessary, larger messages can be sent using the [code][Email_Immediate][/code] tag described in the [def]Email Composing[/def] section. [/note]

[p]The following example shows a pair of files being sent with an email message. The attachments are named [code]MyAttachment.txt [/code]and [code]MyAttachment2.text[/code]. They are located in the same folder as the Lasso page which is sending the email. These text files will not be processed by Lasso before they are sent. [/p]

[pre][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')] [/pre]

[p]Files can be generated programmatically and attached to an email message by specifying a pair including the name of the file and the contents of the file. For example, the following [code][Email_Send][/code] tag uses the [code][PDF_Doc][/code] tag to to create a PDF file. The generated PDF file is sent as an attachment without it ever being written to disk. [/p]

[pre][Var:'MyFile'=(PDF_Doc: -Size='A4', -Margin=(Array: 144.0, 144.0, 72.0, 72.0))]
[$MyFile->(Add: (PDF_Text:'I am a PDF document', -Font=(PDF_Font: -Face='Helvetica', -Size=36)))] [/pre]

[pre][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' = $MyFile->Data)] [/pre]

[p]The [code][Image][/code] tags, [code][Include_Raw][/code] tag, [code][Include][/code] tag, or the [code][Field][/code] tag can also be used to programmatically generate attachments [/p]

Email Merge

[p]Lasso can merge values into email messages just before it sends them. This allows a single email message to be composed and then customized for several recipients. The [code][Email_Send][/code] tag accepts two parameters which make email merge possible. The [/p]

Table 5: Email Merge [Email_Send] Parameters

[table][tr][th]Keyword[/th][th]Description[/th][th] [/th][/tr]

[tr][td]-Tokens[/td][td]Specifies a map of token names and values which will be merged into the email message. The same tokens will be used on every message. [/td][/tr]

[tr][td]-Merge[/td][td]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. [/td][/tr]

[/table]

[p]tIn order to use the [code]-Tokens[/code] and [code]-Merge[/code] parameters the email message must contain one or more email tokens. The preferred method of specifying tokens is to use the [code][Email_Token][/code] tag. In plain text messages or messages that can’t be processed through Lasso the [code]#TOKEN#[/code] marker can be used instead. For example, the tag [code][Email_Token: 'FirstName'][/code] corresponds to the marker [code]#FirstName#[/code]. [/p]

Table 6: Email Tokens

[table][tr][th]Keyword[/th][th]Description[/th][th] [/th][/tr]

[tr][td][Email_Token][/td][td]Email tokens can be created using the [Email_Token] tag. This tag requires a single value which is the name of the email token. [/td][/tr]

[tr][td]#TOKEN#[/td][td]Email tokens can also be specified in pound signs. The name of the token should only contain letters, numbers, or underscores. [/td][/tr]

[tr][td] [/td][/tr]

[p]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 [code]body.lasso[/code] might be as follows. [/p]

[pre]Dear [Email_Token: 'FirstName'] [Email_Token: 'LastName'],
… [/pre]

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

[pre][Var: 'myMergeTokens' = (Map:
'john@example.com' = (Map: 'firstname' = 'John', 'lastname' = 'Doe'),
'jane@example.com' = (Map: 'firstname' = 'Jane', 'lastname' = 'Doe'),
)] [/pre]

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

[pre][Var: 'myDefaultTokens' = (Map: 'firstname' = 'Lasso User', 'lastname' = '')] [/pre]

[p]The [code][Email_Send][/code] tag would be written as follows. The email message is being sent to two recipients. The tag references [code]body.lasso[/code] as the [code]-Body[/code] of the email message with the included [code][Email_Token][/code] tags, [code]-Merge[/code] specifies [code]$MyMergeTokens[/code], and [code]-Tokens[/code] specifies [code]$MyDefaultTokens[/code]. [/p]

[pre][Email_Send:
-To='john@example.com, jane@example.com',
-From='example@example.com',
-Subject='Mail Merge,
-Body=(Include: 'body.lasso'),
-Merge=$myMergeTokens,
-Tokens=$myDefaultTokens] [/pre]

[p]The message to [code]John Doe[/code] would contain this text. [/p]

[pre]Dear John Doe,
… [/pre]

Advanced Parameters

[p]This section includes parameters for [code][Email_Send][/code] that are not required for sending basic email messages, but are useful in specific situations. These parameters allow attachments to be included with email messages or for the headers of the outgoing message to be modified. In general, these parameters should only be used if required. [/p]

Table 7: Advanced [Email_Send] Parameters

[table][tr][th]Keyword[/th][th]Description[/th][th] [/th][/tr]

[tr][td]-Priority[/td][td]Specifies the priority of the message. Values include 'High' or 'Low'. Default is 'Medium'. Optional. [/td][/tr]

[tr][td]-ReplyTo[/td][td]The email address that should be used for replies to this message. Optional. [/td][/tr]

[tr][td]-Sender[/td][td]The email address that should be reported as the sender of this message. Optional. [/td][/tr]

[tr][td]-ContentType[/td][td]The value for the Content-Type header of the message. Optional. [/td][/tr]

[tr][td]-TransferEncoding[/td][td]The value for the Transfer-Encoding header of the message. Optional. [/td][/tr]

[tr][td]-CharacterSet[/td][td]The character set in which the message should be encoded. Optional. [/td][/tr]

[tr][td]-ContentDisposition[/td][td]Can be set to 'inline' in order to embed all attachments inline. Defaults to 'attachment'. [/td][/tr]

[tr][td]-ExtraMIMEHeaders[/td][td]A pair array which defines extra MIME headers that should be added to the email message. Optional. [/td][/tr]

[tr][td]-Immediate[/td][td]If specified then the email is sent immediately without using the outgoing message queue. This option can be used for messages which have very large attachments. [/td][/tr]

[tr][td]-Date[/td][td]This optional parameter can be used to set when the email should be sent. The parameter expects a Lasso date object as its value. If a date in the past is specified then the email will be sent immediately. Optional. [/td][/tr]

[/table]

To change the priority of a sent message:

[p]Specify a [code]-Priority[/code] parameter in the [code][Email_Send][/code] tag. [code]High[/code] priority messages will tend to be send faster than lower priority messages. [code]Low[/code] priority messages will tend to be sent after all higher priority messages. [/p]

[p]Most messages should be sent at the default priority. Sending bulk messages like a newsletter at [code]Low[/code] priority will ensure that the normal email from the site is sent as soon as possible rather than waiting for the entire newsletter to be sent first. [code]High[/code] priority should be reserved for time dependent messages such as confirmation emails that a site visitor will be looking for immediately within their email client. [/p]

To send a message with a Reply-To and Sender header:

[p]The [code]-ReplyTo[/code] and [code]-Sender[/code] parameters can be used. The [code]-ReplyTo[/code] parameter specifies a different address from the -From address which should be used for replies. Most email clients will use this address when composing a response to a message. The [code]-Sender[/code] parameter allows an alternate sender from the -From address to be specified. This can be useful if a message is forwarded by Lasso, but the original sender should still be recorded. [/p]

[pre][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')] [/pre]

To send a message with extra headers:

[p]The [code]-ExtraMIMEHeaders[/code] parameter can be used to send any additional parameters that are required. The value should be an array of name/value pairs. Each of the pairs will be inserted into the email as an additional header. [/p]

[pre][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'),
-ExtraMIMEHeaders=(Array: 'Header' = 'Value', 'Header' = 'Value')] [/pre]

Alternate SMTP Servers‘

[p]By default all sent email will be transmitted directly to the SMTP servers of the recipients. However, if email must be sent through multiple specific SMTP servers then the host, port, and SMTP AUTH username and password can be specified directly within each [code][Email_Send][/code] tag. [/p]

Table 8: SMTP Server [Email_Send] Parameters

[table][tr][th]Keyword[/th][th]Description[/th][th] [/th][/tr]

[tr][td]-Host[/td][td]Optional SMTP host through which to send messages. Default is the host defined in Lasso Administration. [/td][/tr]

[tr][td]-Port[/td][td]Optional SMTP port. Defaults to 25. [/td][/tr]

[tr][td]-Username[/td][td]Specifies the username for SMTP AUTH if required by the SMTP server. If specified a -Passwod is also required. Optional. [/td][/tr]

[tr][td]-Password[/td][td]Specifies the password for SMTP AUTH if required by the SMTP server. If specified a -Username is also required. Optional. [/td][/tr]

[tr][td]-Timeout[/td][td]Specifies the timeout for the SMTP server in seconds. Optional [/td][/tr]

[/table]

To use an alternate SMTP server:

[p]Specify the [code]-Host[/code] in the [code][Email_Send][/code] tag directly. If required the port of the SMTP server can be changed with the [code]-Port[/code] parameter. An SMTP AUTH username and password can be provided with the [code]-Username[/code] and [code]-Password[/code] parameters. And, the [code]-Timeout[/code] for the SMTP server can be changed in seconds. [/p]

[pre][Email_Send: -Host='mail.example.com',
-Username='SMTPUSER',
-Password='MySecretPassword',
-To='example@example.com',
-From='example@example.com',
-Subject='An Email',
-Body=(Include: 'format.lasso')] [/pre]

Email Status

[p]Email messages which are sent using the [code][Email_Send][/code] tag 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 [code]Utility > Email > Email Queue [/code]section of Lasso Site Administration. [/p]

[p]However, it is often desirable to get information about a message that was sent programatically without examining the queue table. The tags in the following table allow the status of a recently sent message to be examined. [/p]

Table 9: Email Composing and Queuing Tags

[table][tr][th]Tag[/th][th]Description[/th][th] [/th][/tr]

[tr][td][Email_Result][/td][td]Can be called immediately after an [Email_Send] tag to get a unique ID string for the message that was queued. [/td][/tr]

[tr][td][Email_Status][/td][td]Accepts an ID from the [Email_Result] tag and returns the status of the queued message: sent, queued, or error. [/td][/tr]

[/table]

[note][b]Note: [/b]The email sender may take from a few seconds to longer to send an email message. Calling [code][Email_Status][/code] immediately after calling [code][Email_Send][/code] will always return [code]queued[/code]. The [code][Email_Status][/code] tag must be called after a short delay in order to return the true status of the message as [code]sent[/code] or [code]error[/code]. [/note]

[p]The following example shows an [code][Email_Send][/code] tag that sends a message. The [code][Email_Result][/code] tag is called immediately after [code][Email_Send][/code] to store the unique ID of the message that was sent. After a delay of 30 seconds the [code][Email_Status][/code] tag is called to see if the message was successfully sent. [/p]

[pre][Email_Send:
-To='example@example.com',
-From='example@example.com',
-Subject='An Email',
-Body='This is the body of the email.']
[Var: 'myEmail' = Email_Result]
[Sleep: 30000]
[Email_Status: $myEmail] [/pre]

[p]In a practical solution the unique ID returned by [code][Email_Result][/code] would be stored in a session variable or in a database table and then would be checked some time later using [code][Email_Status][/code] to see if the email message was sent or if the address it was sent to was invalid. [/p]

Composing Email

[p]The [code][Email_Send][/code] tag handles all of the most common types of email that can be sent through Lasso including plaintext messages, HTML messages, HTML messages with a plain text alternative messages, and messages with attachments. [/p]

[p]For more complex messages structures the [code][Email_Compose][/code] object can be used directly to create the MIME text of the message. The message can then be sent with the [code][Email_Queue][/code] tag. Both of these tags are used internally by [code][Email_Send][/code]. [/p]

[p][code][Email_Compose][/code] accepts the same parameters as [code][Email_Send][/code] except those which specify the SMTP server and priority of the outgoing message. After creating an email object with [code][Email_Compose][/code], member tags can be used to add additional text parts, html parts, attachments, or generic MIME parts. This allows very complex email structures to be created with a lot more control than [code][Email_Send][/code] provides. [/p]

[p][code][Email_Compose][/code] can also be used to create email parts. When this tag is called without a [code]-To[/code], [code]-From[/code], or [code]-Subject[/code] then a MIME part is created rather than a complete email message. This part can then be fed into the [code][Email_Compose->AddPart][/code] tag or into the [code]-Attachments[/code] or [code]-HTMLImages[/code] parameters to place the part within a complex email message. [/p]

[p]The [code][Email_Queue][/code] tag is designed to be fed an [code][Email_Compose][/code] object. It requires three parameters, the [code]-Data[/code], [code]-From[/code], and [code]-Recipients[/code] attributes of the [code][Email_Compose][/code] object. In addition, SMTP server parameters and the sending priority can be specified just like in [code][Email_Send][/code]. Queued emails must be less than 8MB in size including all encoded attachments. [/p]

[p]The [code][Email_Immediate][/code] tag takes the same parameters as the [code][Email_Queue][/code] tag, but sends the message immediately rather than adding it to the email queue. This tag can be used to send messages larger than 8MB if required. A status of sent or an error will still be added to the queue, but the body of the sent message will not be included. Use of the [code][Email_Immediate][/code] tag is not recommended since it bypasses the priority, error handling, and connection handling features of the email sending system. [/p]

Table 10: Email Composing and Queuing Tags

[table][tr][th]Tag[/th][th]Description[/th][th] [/th][/tr]

[tr][td][Email_Batch] … [/Email_Batch][/td][td]Temporarily suspends some back-end operations of the email queue so that a batch of email messages can be queued quickly. Any messages which are already queued will continue to send while this tag is open. [/td][/tr]

[tr][td][Email_Compose][/td][td]Creates an email object. Accepts the same parameters as [Email_Send]: -To, -From, -Body, -HTML, -Subject etc. If -To, -From, and -Subject are not specified then a MIME part is created, otherwise a full MIME email is created. [/td][/tr]

[tr][td][Email_Compose->AddAttachment][/td][td]Adds an attachment to an email 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. [/td][/tr]

[tr][td][Email_Compose->AddTextPart][/td][td]Adds a text part to an email 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. [/td][/tr]

[tr][td][Email_Compose->AddHTMLPart][/td][td]Adds an HTML part to an email 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. [/td][/tr]

[tr][td][Email_Compose->AddPart][/td][td]Adds a generic part to an email object. Requires a parameter -Data which specifies the data for the part. the part must be properly formatted as a MIME part. No formatting or encoding will be performed. [/td][/tr]

[tr][td][Email_Compose->Data][/td][td]Returns the MIME text of the composed email. [/td][/tr]

[tr][td][Email_Compose->From][/td][td]Returns the from address of the composed email. [/td][/tr]

[tr][td][Email_Compose->Recipients][/td][td]Returns a list of recipients of the composed email. [/td][/tr]

[tr][td][Email_Queue][/td][td]Queues a message for sending. Requires either an [Email_Compose] object or a -Data parameter including 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 email merge. [/td][/tr]

[tr][td][Email_Immediate][/td][td]The same as [Email_Queue], but sends the message immediately without storing it in the database. A -Tokens parameter can also be specified and email merge will be performed just before sending the message. [/td][/tr]

[tr][td][Email_Merge][/td][td]Allows the email merge operation to be performed on any text. Requires two parameters: the text which is to be modified and a -Tokens parameter which specifies a map of tokens to be replaced in the text. Optional -TransferEncoding and -Charset parameters specify what type of encoding should be applied to the merged tokens. [/td][/tr]

[/table]

To send a batch of messages:

[p]The [code][Email_Batch] … [/Email_Batch][/code] tag can be used when a number of messages need to be queued all at once. The tag temporarily suspends some back-end operations of the email queue so that the messages can be queued faster. When the closing tag is processed the queue is allowed to resume sending the queue messages. [/p]

[p]The example below shows how an inline might be used to find a collection of email addresses. The [code][Email_Batch] … [/Email_Batch][/code] tags ensure that the messages are queued as fastly as possible. [/p]

[pre][Email_Batch]
[Inline: -Search, …]
[Records]
[Email_Send: -From='sender@example.com', -To=(Field: 'email_address'), …]
[/Records]
[/Inline]
[/Email_Bath] [/pre]

[note][b]Note: [/b]The email merge tags which are discussed earlier in this chapter can also be used to send an email message to a collection of recipients quickly. [/note]

To compose an email message:

[p]The [code][Email_Compose][/code] object can be used to compose an email message. In this example a simple email message is created in a variable [code]message[/code]. [/p]

<?LassoScript
var: 'message' = (Email_Compose:
-To='example@example.com',
-From='example@example.com',
-Subject='Example Message',
-Body='Example Message');
?>

[p]The text of the composed email message can be viewed by outputing the variable [code]$message[/code] to the page. Note that [code][Encode_HTML][/code] should always be used since certain headers of the email message use angle brackets to surround values. Also, HTML [code]<pre> … </pre>[/code] tags make it a lot easier to see the formatting of the email message. [/p]

[p]<pre>[Encode_HTML: $message]</pre> [/p]

[p]Additional text or html parts or attachments can be added using the appropriate member tags with the [code]$message[/code] variable. For example, an attachment can be added using the [code][Email_Compose->AddAttachment][/code] tag as follows: [/p]

<?LassoScript
$message->(AddAttachment: -Path='ExampleFile.txt');
?>

To queue an email message:

[p]An email message that was created using the [code][Email_Compose][/code] object can be queued for sending using the [code][Email_Queue][/code] tag. The following example shows how to send the email message created above. The three required parameters [code]-Data[/code], [code]-From[/code], and [code]-Recipients[/code] can all be fetched from the members of the [code][Email_Compose][/code] object. [/p]

<?LassoScript
Email_Queue:
-Data=$message->Data,
-From=$emessage->From,
-Recipients=$message->Recipients;
?>

[p]The [code][Email_Queue][/code] tag will send to the default SMTP server set up in the Utility > Email > Setup section of Site Administration. If the email needs to be sent to a different SMTP server the [code]-Host[/code], [code]-Port[/code], [code]-Timeout[/code], [code]-Username[/code], and [code]-Password[/code] parameter can be used just as they can with the [code][Email_Send][/code] tag. [/p]

SMTP Type

[p]All communication with remote SMTP servers is handled by a data type called [code][Email_SMTP][/code]. These connections are normally handled automatically by the [code][Email_Send][/code], [code][Email_Queue][/code], [code][Email_Immediate][/code], and background email sending process. [/p]

[p]The [code][Email_SMTP][/code] type can be used directly for low-level access to remote SMTP servers, but this is not generally necessary. [/p]

Table 11: SMTP Tags

[table][tr][th]Tag[/th][th]Description[/th][th] [/th][/tr]

[tr][td][Email_SMTP][/td][td]Creates a new SMTP connection object. [/td][/tr]

[tr][td][Email_SMTP->Open][/td][td]Requires a -Host that specifies the SMTP host to connect to. Also accepts optional -Port, -Username, -Password, and -Timeout parameters [/td][/tr]

[tr][td][Email_SMTP->Send][/td][td]Sends a single message to the SMTP server. Requires a -Message parameter with the MIME data for the message, -Recipients with an array of recpient email address, and -From with the email address of the sender. [/td][/tr]

[tr][td][Email_SMTP->Command][/td][td]Sends a raw command to the SMTP server. The -Send parameter specifies the command to send. The -Expects parameter specifies the numeric result code that is expected as a result. This tag normally 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. [/td][/tr]

[tr][td][Email_SMTP->Close][/td][td]Closes the connection to the remote server. [/td][/tr]

[tr][td][Email_MXLookup][/td][td]This tag takes a domain as a 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. [/td][/tr]

[/table]

To lookup an SMTP server:

[p]Use the [code][Email_MXLookup][/code] tag. This tag returns a map that describes the preferred MX server for the domain. An example lookup for AOL is shown below. If the administrator has entered routes into Lasso Site Administration then that information will be returned by this tag. Otherwise, the first time an MX record is looked up it will be cached and the same information will be returned on subsequent lookups. [/p]

[pre][Email_MXLookup: 'aol.com'] [/pre]

[pre] map: (domain)=(aol.com), (password)=(), (host)=(mailin-02.mx.aol.com), (ssl)=(), (cache)=(3), (username)=(), (timeout)=(), (route)=(0) [/pre]

To communicate with an SMTP server:

[p]The [code][Email_SMTP][/code] object can be used to send one or more messages directly to an SMTP server. In the following example a message is created using the [code][Email_Compose][/code] tag. That message is then sent to an example SMTP server [code]smtp.example.com[/code] using an SMTP AUTH username and password. Once the message is sent the connection is closed. [/p]

[p]This example does not perform any error checking and only sends one message. The actual source code for the built-in email sender background process presents a good example of how this code looks in a full working solution. [/p]

<?LassoScript

[pre]	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 + 'rn');
#smtp->close; [/pre]

[pre]?>

[/pre]