Using the Email Outbound Adapter
This topic describes the behavior of the email outbound adapter (EnsLib.EMail.OutboundAdapterOpens in a new tab) and describes how to use this adapter in your productions.
Overall Behavior
Within a production, an outbound adapter is associated with a business operation that you create and configure. The business operation receives a message from within the production, looks up the message type, and executes the appropriate method. This method usually executes methods of the associated adapter.
The email outbound adapter (EnsLib.EMail.OutboundAdapterOpens in a new tab) provides settings that you use to specify the following:
-
The SMTP server to connect to and login details needed for that server, if any.
-
The default address to send email from (the From: header).
-
Recipients to add to any messages sent by the adapter, in addition to any hardcoded recipients.
It provides methods to do the following three actions:
-
Add a recipient to the To: list.
-
Add a recipient to the Cc: list.
-
Send a message.
Creating a Business Operation to Use the Adapter
To create a business operation to use the EnsLib.EMail.OutBoundAdapter, you create a new business operation class. Later, add it to your production and configure it.
You must also create appropriate message classes, if none yet exist. See Defining Messages.
The following list describes the basic requirements of the business operation class:
-
Your business operation class should extend Ens.BusinessOperationOpens in a new tab.
-
In your class, the ADAPTER parameter should equal EnsLib.EMail.OutboundAdapterOpens in a new tab.
-
In your class, the INVOCATION parameter should specify the invocation style you want to use, which must be one of the following.
-
Queue means the message is created within one background job and placed on a queue, at which time the original job is released. Later, when the message is processed, a different background job will be allocated for the task. This is the most common setting.
-
InProc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be released to the sender’s pool until the message is delivered to the target. This is only suitable for special cases.
-
-
Your class should define a message map that includes at least one entry. A message map is an XData block entry that has the following structure:
XData MessageMap { <MapItems> <MapItem MessageType="messageclass"> <Method>methodname</Method> </MapItem> ... </MapItems> }
-
Your class should define all the methods named in the message map. These methods are known as message handlers. Each message handler should have the following signature:
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class. In general, these methods will refer to properties and methods of the Adapter property of your business operation.
-
For other options and general information, see Defining a Business Operation Class.
The following example shows the general structure that you need:
Class EEMA.NewOperation1 Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.EMail.OutboundAdapter";
Parameter INVOCATION = "Queue";
Method SampleCall(pRequest As Ens.Request,
Output pResponse As Ens.Response) As %Status
{
Quit $$$ERROR($$$NotImplemented)
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="Ens.Request">
<Method>SampleCall</Method>
</MapItem>
</MapItems>
}
}
Creating Message Handler Methods
When you create a business operation class for use with EnsLib.EMail.OutboundAdapterOpens in a new tab, typically your biggest task is writing message handlers for use with this adapter, that is, methods that receive production messages and then send email messages via an SMTP server.
Each message handler method should have the following signature:
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class.
In general, the method should do the following:
-
Examine the inbound request message.
-
Create an email message to send; for information, see Creating Email Messages.
-
Optionally call the AddRecipients(), AddCcRecipients(), and AddBccRecipients()methods of the Adapter property of your business operation. These methods add email addresses to the To:, Cc:, and Bcc: headers when you send the email message. These methods are discussed after these steps.
-
Call the SendMail() method of the Adapter property of your business operation:
Set tSc=..Adapter.SendMail(email,.pf)
This method is discussed after these steps.
-
Examine the response.
-
Use information in the response to create a response message (an instance of Ens.ResponseOpens in a new tab or a subclass), which the method returns as output.
For information on defining message classes, see Defining Messages.
-
Make sure that you set the output argument (pOutput). Typically you set this equal to the response message. This step is required.
-
Return an appropriate status. This step is required.
Available Methods
The adapter provides the following methods:
Method SendMail(pMailMessage As %Net.MailMessage,
Output pFailedRecipients As %ListOfDataTypes) As %Status
Given an email message, this method sends the message by means of the configured SMTP server. It returns, as output, as list of failed recipients, if the SMTP server returns this information.
Method AddRecipients(pMailMessage As %Net.MailMessage,
pRecipients As %String)
Given an email message, this method adds the listed email addresses to the To: header of the message.
Method AddCcRecipients(pMailMessage As %Net.MailMessage,
pRecipients As %String)
Given an email message, this method adds the listed email addresses to the Cc: header of the message.
Method AddBccRecipients(pMailMessage As %Net.MailMessage,
pRecipients As %String)
Given an email message, this method adds the listed email addresses to the Bcc: header of the message. When sending an email there must be at least one address in the To: or Cc: header.
Method ContinueAfterBadSendSet(%val As %Integer) as %Status
If %val is true, the adapter continues to send the message if one or more of the recipients have an invalid address. The default is true.
Example
A method might look like the following:
Method SendMultipartEmailMessage(pRequest As EEMA.MultipartEmailMsg,
Output pResponse As Ens.Response) As %Status
{
Set part1=##class(%Net.MailMessage).%New()
Do part1.TextData.Write(pRequest.Message1)
Set part2=##class(%Net.MailMessage).%New()
Do part2.TextData.Write(pRequest.Message2)
Set part3=##class(%Net.MailMessage).%New()
Do part3.TextData.Write(pRequest.Message3)
Set email=##class(%Net.MailMessage).%New()
Set email.Subject=pRequest.Subject
Set email.IsMultiPart=1
Do email.Parts.SetAt(part1,1)
Do email.Parts.SetAt(part2,2)
Do email.Parts.SetAt(part3,3)
Set tSc=..Adapter.SendMail(email,.pf)
Set pResponse=##class(EEMA.EmailFailedRecipients).%New()
Set pResponse.FailedRecipients=pf
if pf.Count()'=""
{
set count=pf.Count()
for i=1:1:count
{
$$$TRACE("Failed recipient:"_pf.GetAt(i))
}
}
Quit tSc
}
For information on creating email messages, see the next section.
Creating Email Messages
A message can have one or more parts; each part contains content and can include headers. The message itself also has headers. The following sections discuss the topics:
You should be aware of the requirements of the SMTP server that you are using. For example, some SMTP servers require that you include a Subject: header. Similarly, some SMTP servers do not permit arbitrary From: headers.
Creating an Email Message
To create an email message, do the following:
-
Create an instance of %Net.MailMessageOpens in a new tab.
Tip:You can specify a character set as the argument to %New(); if you do so, that sets the Charset property for the message.
For information on character sets and translation tables, see Translation Tables.
-
Set the To, From, and Subject properties of your instance. These properties are required.
-
To—The list of email addresses to which this message will be sent. This property is a standard InterSystems IRIS list; to work with it, you use the standard list methods: Insert(), GetAt(), RemoveAt(), Count(), and Clear().
-
From—The email address this message is sent from.
-
Subject—The subject of the message.
-
-
Optionally set Date, Cc, Bcc, and other properties. For details, see Basic Headers.
-
If you are creating a single-part message, specify the contents and headers as described in Specifying the Content and Headers of a Message Part.
-
Or, if you are creating a multipart message, do the following:
-
Set the IsMultiPart property to 1.
-
Set the MultiPartType property to one of the following: "related", "alternative", or "mixed".
-
For each part that the message should contain, create an instance of %Net.MailMessagePartOpens in a new tab. Then specify the contents and headers as described in Specifying the Content and Headers of a Message Part.
-
For the parent email message, set the Parts property, which is an array. Insert each child message part into this array.
-
Specifying the Content and Headers of a Message Part
-
If the message is not plain text, set the following properties to indicate the kind of message you are creating:
-
If this is an HTML message, set the IsHTML property to 1.
-
If this is a binary message, set the IsBinary property to 1.
-
-
To specify the desired character set of the message and its headers, set the Charset property as needed.
Important:It is important to specify the character set before you add the contents of the message.
For information on character sets and translation tables, see Translation Tables.
-
Add the contents of the message:
-
For plain text or HTML, use the TextData property, which is an instance of %FileCharacterStreamOpens in a new tab. You do not need to specify the TranslateTable property of this stream; that occurred automatically when you specified the character set of the mail message.
The system automatically translates the character encoding to the encoding that you specified in the previous step.
-
For binary data, use the BinaryData property, which is an instance of %FileBinaryStreamOpens in a new tab.
Note that %FileCharacterStreamOpens in a new tab and %FileBinaryStreamOpens in a new tab are deprecated but are still supported for use in this way. It is not recommended to substitute different stream classes for this use case.
Tip:When you specify the Filename property of the stream, be sure to use a directory to which the users will have write access.
To work with these properties, use the standard stream methods: Write(), WriteLine(), Read(), ReadLine(), Rewind(), MoveToEnd(), and Clear(). You can also use the Size property of the stream, which gives you the size of the message contents.
-
Specifying the Message Headers
As noted previously, both the message itself and each part of a message has a set of headers.
The %Net.MailMessageOpens in a new tab and %Net.MailMessagePartOpens in a new tab classes provide properties that give you easy access to the most commonly used headers, but you can add any header you need. This section provides information on all the headers as well as how to create custom headers.
The headers of a given message part are in the character set specified by the Charset property of that part.
Basic Headers
Set the following properties (only in %Net.MailMessageOpens in a new tab) to specify the most commonly used headers of the message itself:
-
To—(Required) The list of email addresses to which this message will be sent. This property is a standard InterSystems IRIS list; to work with it, you use the standard list methods: Insert(), GetAt(), RemoveAt(), Count(), and Clear().
-
From—(Required) The email address this message is sent from.
-
Date—The date of this message.
-
Subject—A string containing the subject for this message.
-
Sender—The actual sender of the message.
-
Cc—The list of carbon copy addresses to which this message will be sent.
-
Bcc—The list of blind carbon copy addresses to which this message will be sent.
You should be aware of the requirements of the SMTP server that you are using. For example, some SMTP servers require that you include a Subject: header. Similarly, some SMTP servers do not permit arbitrary From: headers.
Content-Type Header
When you send the message, the Content-Type header for the message and for each message part is automatically set as follows:
-
If the message is plain text (IsHTML equals 0 and IsBinary equals 0), the Content-Type header is set to "text/plain".
-
If the message is HTML (IsHTML equals 1 and IsBinary equals 0), the Content-Type header is set to "text/html".
-
If the message is binary (IsBinary equals 1), the Content-Type header is set to "application/octet-stream".
-
If the message is multipart, the Content-Type header is set as appropriate for the value of the MultiPartType property.
Both %Net.MailMessageOpens in a new tab and %Net.MailMessagePartOpens in a new tab provide the ContentType property, which gives you access to the Content-Type header.
Content-Transfer-Encoding Header
Both %Net.MailMessageOpens in a new tab and %Net.MailMessagePartOpens in a new tab provide the ContentTransferEncoding property, which provides an easy way to specify the Content-Transfer-Encoding header of the message or the message part.
This property can be one of the following: "base64" "quoted-printable" "7bit" "8bit"
The default is as follows:
-
For a binary message or message part: "base64"
-
For a text message or message part: "quoted-printable"
Custom Headers
With both %Net.MailMessageOpens in a new tab and %Net.MailMessagePartOpens in a new tab, you can set or get custom headers by accessing the Headers property, which is an array with the following structure:
Array Key | Array Value |
---|---|
Name of the header, such as "Priority" | Value of the header |
You use this property to contain additional headers such as priority. For example:
Do msg.Headers.SetAt("Urgent","Priority")
Adding Attachments
You can add attachments to an email message or message part. To do so, use the following methods of %Net.MailMessagePartOpens in a new tab or %Net.MailMessageOpens in a new tab).
Each of these methods adds the attachment to the Parts array of the original message (or message part), and automatically sets the IsMultiPart property to 1.
method AttachFile(Dir As %String,
File As %String,
isBinary As %Boolean = 1,
charset As %String = "",
ByRef count As %Integer) as %Status
Attaches the given file to the email message. By default the file is sent as a binary attachment, but you can specify instead that it is text. You can also specify the character set that the file uses if it is text. (For information on character sets and translation tables, see Translation Tables.)
Specifically, this method creates an instance of %Net.MailMessagePartOpens in a new tab and places the contents of the file in the BinaryData or TextData property as appropriate, and sets the Charset property and TextData.TranslateTable properties if needed. The method returns, by reference, an integer that indicates the position of this new message part within the Parts array.
This method also sets the Dir and FileName properties of the message or message part.
method AttachNewMessage() as %Net.MailMessagePart
Creates a new instance of %Net.MailMessageOpens in a new tab, adds it to the message, and returns the newly modified parent message or message part.
method AttachEmail(mailmsg As %Net.MailMessage)
Given an email message (an instance of %Net.MailMessageOpens in a new tab), this method adds it to the message.
This method sets ContentType to "message/rfc822". In this case, you cannot add any other attachments.
For examples, see the class reference for the %Net.MailMessagePartOpens in a new tab class.
Example
For example:
ClassMethod CreateTextMessage() As %Net.MailMessage
{
Set msg = ##class(%Net.MailMessage).%New()
set msg.From = "test@test.com"
Do msg.To.Insert("xxx@xxx.com")
Do msg.Cc.Insert("yyy@yyy.com")
Do msg.Bcc.Insert("zzz@zzz.com")
Set msg.Subject="subject line here"
Set msg.IsBinary=0
Set msg.IsHTML=0
Do msg.TextData.Write("This is the message.")
Quit msg
}
Example
This section presents an example that allows you to send simple single-part or multipart email messages that contain string content. In a production system, you would probably use streams instead of strings. Because this example uses strings, however, you can easily test it by means of the production testing page.
First, the request message class for the single-part message is as follows:
Class EEMA.SimpleMsg Extends Ens.Request
{
Property Subject As %String(MAXLEN = 100);
Property Message As %String(MAXLEN = 5000);
}
The request message class for the multipart message is next. This class can contain a three-part message.
Class EEMA.MultipartMsg Extends Ens.Request
{
Property Subject As %String(MAXLEN = 100);
Property Part1 As %String(MAXLEN = 5000);
Property Part2 As %String(MAXLEN = 5000);
Property Part3 As %String(MAXLEN = 5000);
}
The following business operation can accept either of these messages, create the appropriate email message, and send that via the configured SMTP server:
Class EEMA.EmailOperation Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.EMail.OutboundAdapter";
Parameter INVOCATION = "Queue";
Method SendSimpleMessage(pRequest As EEMA.SimpleMsg,
Output pResponse As Ens.Response) As %Status
{
Set email=##class(%Net.MailMessage).%New()
//Get info from pReq
Do email.TextData.Write(pRequest.Message)
Set email.Subject=pRequest.Subject
//simple case--do not check for failed recipients
Set tSc=..Adapter.SendMail(email)
//send an empty response message after message is sent
Set pResponse=##class(Ens.Response).%New()
;Quit tSc
}
Method SendMultipartEmailMessage(pRequest As EEMA.MultipartMsg,
Output pResponse As Ens.Response) As %Status
{
Set part1=##class(%Net.MailMessage).%New()
Do part1.TextData.Write(pRequest.Part1)
Set part2=##class(%Net.MailMessage).%New()
Do part2.TextData.Write(pRequest.Part2)
Set part3=##class(%Net.MailMessage).%New()
Do part3.TextData.Write(pRequest.Part3)
Set email=##class(%Net.MailMessage).%New()
Set email.Subject=pRequest.Subject
Set email.IsMultiPart=1
Do email.Parts.SetAt(part1,1)
Do email.Parts.SetAt(part2,2)
Do email.Parts.SetAt(part3,3)
//simple case--do not check for failed recipients
Set tSc=..Adapter.SendMail(email)
//send an empty response message after message is sent
Set pResponse=##class(Ens.Response).%New()
Quit tSc
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="EEMA.SimpleMsg">
<Method>SendSimpleMessage</Method>
</MapItem>
<MapItem MessageType="EEMA.MultipartMsg">
<Method>SendMultipartEmailMessage</Method>
</MapItem>
</MapItems>
}
}
Adding and Configuring the Business Operation
To add your business operation to a production, use the Management Portal to do the following:
-
Add an instance of your custom business operation class to the production.
-
Enable the business operation.
-
Specify an SMTP mail server and credentials needed to access it.
-
Optionally specify additional addresses for the email messages.
-
Run the production.
Specifying How to Log Into the SMTP Server
To specify the SMTP server to use and any associated login credentials, specify values for the following settings of EnsLib.EMail.OutboundAdapterOpens in a new tab:
For example, you could use values like the following:
Setting | Value |
---|---|
SMTP Server | smtp.hotpop.com |
SMTP Port | 25 |
Credentials | hotpop |
In this example, hotpop is the ID of the production credentials that consist of the username isctest@hotpop.com and the corresponding password.
Specifying Additional Email Addresses
You can use the following settings of EnsLib.EMail.OutboundAdapterOpens in a new tab to specify email addresses for email messages sent by this adapter:
For any settings not listed here, see Configuring Productions.