Email

Enables processes to receive and send email messages.

You can modify the default settings for the Email service by using one of the following methods:

In Workspace, modify settings for the Email service in the Component view. (See Editing service configurations.)
In the Administration Console, select Services > Applications and Services > Service Management and click the Email service. (See Applications and Services Administration Help.)

For information about using the Email service, see Services Reference for Adobe LiveCycle ES4.

Email service configuration

The Email service can be configured with default properties for connecting to an SMTP server for sending email messages, and to either a POP3 or IMAP server for receiving messages. (See Editing service configurations.)

When you configure the connection properties, the Email service operations inherit the property values. However, the default connection properties can be overridden using the properties of each operation.

The following properties can be configured for the Email service.

SMTP Host:

The IP address or URL of the SMTP server to use for sending email.

SMTP Port Number:

The port used to connect to the SMTP server.

SMTP Authenticate:

Select if user authentication is required to connect to the SMTP server.

SMTP User:

The user name of the user account to use to log in to the SMTP server.

SMTP Password:

The password that is associated with the SMTP user account.

SMTP Transport Security:

The security protocol to use for connecting to the SMTP server:

Select None if no protocol is used (data is sent in clear text)
Select SSL if Secure Sockets Layer protocol is used.
Select TLS if Transport Layer Security is used.

POP3/IMAP Host:

The IP address or URL of the POP3 or IMAP server to use for sending email.

POP3/IMAP Username:

The user name of the user account to use to log into the POP3 or IMAP server.

POP3/IMAP Password:

The password that is associated with the POP3 or IMAP user account.

POP3/IMAP Port Number:

The port used to connect to the POP3 or IMAP server.

POP3/IMAP:

The protocol to use for sending and receiving email.

Receive Transport Security:

The security protocol to use for connecting to the SMTP server:

Select None if no protocol is used (data is sent in clear text).
Select SSL if Secure Sockets Layer protocol is used.
Select TLS if Transport Layer Security is used.

Receive operation

Receives email messages and attachments from either a POP3 or IMAP email server. You can save metadata about the email, as well as the message content. You can also set filters for email messages, and set properties about the email server and user account to use.

Email metadata and content can be saved in any location in the process data model, such as a variable or form field, that supports the type of data.

For information about the General and Route Evaluation property groups, see Common operation properties.

Filter properties

Use Filter properties to selectively retrieve email messages.

Filter Subject

A string value that represents the filter for the email subject. Only email messages that contain the specified text in their subject line are retrieved. Specify no value to receive emails regardless of the email subject.

When entering this value as an XPath expression, surround the string with single quotation marks. For the literal value and template, the quotation marks are not required.

For example, to receive emails that contain “the quick brown fox” in the subject line, specify the following string values:

XPath expression - ‘brown’
literal value - brown
template - brown

Filter From

A string value that represents the filter for the email sender’s email address. Only email messages that are sent from the specified email address are retrieved. Specify no value to receive emails from any email address.

Folder Options

Use Folder Options properties to manage email storage on the email server.

Folder

A string value that represents the name of the folder from which to retrieve the email. Specify no value to retrieve email from the default folder. This property has no effect if you use a POP3 email server.

Delete After Processing

A boolean value that, if True, indicates that email is deleted from the server after it is retrieved. A value of False indicates that the email remains on the server.

Retrieved Email Contents properties

Use Retrieved Email Contents properties to specify where to save the content of email messages.

Subject

The location to save the email subject. The data type is string.

Body (Text)

The location to save the email body as plain text. The data type is string.

Body (HTML)

The location to save the email body as HTML code. The Body data is null if the email is delivered in plain text format. The data type is string.

From properties

Use From properties to save the sender’s email address.

From

The location to save the sender’s email address. The data type is string.

Reply To

The location to save the email address to use for replying to the email message. The sender can designate an email address to use for replying to the message that is different than the address used to send the message. The data type is string.

Retrieved Email Attributes properties

Use Retrieved Email Attributes properties to save metadata about the email message.

Size

The location to save the size of the email, in bytes. The data type is int.

Received Date

The location to save the date that the email was received on the email server. The data type is date.

Send Date

The location to save the date that the email was sent. The data type is date.

Importance

The location to save the level of importance of the email. The data type is string.

X-Priority

The location to save the XPriority of the email. The data type is string.

Message ID

The location to save the unique identification of the email message. The data type is string.

Attachments properties

Use Attachments properties to specify how to store email attachments.

Attachment Mime Filter

A list value that contains string values which indicate the mime type of the attachments to retrieve. If no value is provided, all attachments are retrieved.

If you provide a literal value, clicking the ellipsis button opens the Select MIME Type For Filter dialog box. In the dialog box, select the MIME types of the attachments to retrieve and then click OK.

For information about retrieving values from a list, see Accessing data in data collections.

Attachment Count

The location to save the number of files that are attached to the email message. The data type is int.

Attachments Retrieved

The location to save the number of attachments that were retrieved from the email message. This number can be different than the number of attachments that were sent in the email message if you have specified a MIME-type filter for the Attachment MIME Filter property. The data type is int.

Map of Attachments

The location to save the retrieved attachments. You need to store the data in a map variable that holds document values. The key for each document in the map is the corresponding attachment name.

You can also save attachments as list data if that data type is better suited to how you want to process the attachments later in the process. (See List of Attachments.)

List of Attachments

The location to save the retrieved attachments. You need to store the data in a list variable that holds document values.

You can also save attachments as map data if that data type is better suited to how you want process the attachments later in the process. (See Map of Attachments.)

Connection Settings properties

Use the Connection Settings properties to specify information required for connecting to the email server.

Use Global Settings

A boolean value that specifies whether to use the connection settings in the Email service configuration or the properties of the operation. A value of True causes the service configuration to be used. A value of False causes the properties of the operation to be used. The default value is True.

If you use a literal value to configure this property, select Use Global Settings to use the service configuration. To use the operation properties, clear Use Global Settings and provide values for the other Connection Settings properties.

POP3/IMAP Host

A string value that represents the IP address or URI of the POP3 or IMAP server. For example, you can use the name of the computer that is resolved by Domain Naming Scheme (DNS).

POP3/IMAP Port Number

An int value that represents the port number that the POP3 or IMAP server uses. If no value is specified, 110 is used for POP3 servers, and 143 is used for IMAP servers.

POP3/IMAP Username

A string value that represents the email address that is associated with the user account on the POP3 or IMAP server that is used to receive the email message.

POP3/IMAP Password

A string value that represents the password to use for authenticating with the POP3 or IMAP server. The password is associated by the user account that is associated with the value of the POP3/IMAP Username property.

If no value is provided, no authentication is attempted.

POP3/IMAP

A string value that represents the protocol to use for exchanging information with the POP3 or IMAP server. Valid values are pop3 and imap. The value you use depends on the type of email server you are using.

Receive Transport Security

A string value that represents the transport security used when communicating with the POP3 or IMAP server. The following values are valid.

None:: Data is sent in clear text
SSL:: Secure Sockets Layer
TLS:: Transport Layer Security
The value you specify depends on how the email server is configured.

Test properties

Tools for testing the configuration of the Receive operation.

Test Dialog

Provides the Receive Tester dialog box that you can use to verify that the Receive operation is configured correctly. The test retrieves email messages from the email server, but does not cause the messages to be deleted from the server.

Note: The test cannot be performed if any property values are expressed using XPath expressions or process variables. At design-time, locations in the process data model are not yet associated with data.

To perform the test, click the ellipsis button which opens the dialog box, and then click Test. The results of the test appear in the dialog box.

Exceptions

The exception event attached to this operation can catch the MessageNotFoundException, ConnectionFailedException, and ReceiveMailFailedExceptionexceptions.

Send With Document operation

Sends an email message that has a single attachment. To send an email with multiple attachments, you need to use the Send With Map Of Attachments operation. (See Send With Map of Attachments operation.) Send With Document is easier to configure than Send With Map Of Attachments, which makes it useful if you need to send only one document.

For information about the General and Route Evaluation property groups, see Common operation properties.

To Addresses properties

Use the To Addresses properties to specify email recipients. You can specify email addresses directly or import email addresses from a defined user list. To import addresses from a defined user list, click Import From User List, and then select a user list.

Note: If the selected user list contains any group, then the email addresses of the users and sub-groups inside the group are not imported. However, the email address of the group is imported.

To

A string value that represents one or more email addresses to send the email to. Separate email addresses with a comma.

CC

A string value that represents one or more email addresses to send a copy of the email to. Separate email addresses with a comma.

BCC

A string value that represents one or more email addresses to send a copy of the email to. The addresses are hidden from other recipients of the email. Separate email addresses with a comma.

From Addresses properties

Use the From Addresses properties to specify the email address used to send the email message.

From

A string value that represents the email address that is associated with the email user account that is sending the email message.

Reply To

(Optional) A string value that represents the email address to which responses to the email are sent. If no value is specified, the email address specified for the From property is used.

Return To

(Optional) A string value that represents the email address to use as return address for the email envelope. If no value is specified, the email address specified for the From property is used.

Contents properties

Use the Contents properties to specify the content of the email message.

Subject

A string value that represents the text to use for the email message subject.

Message Format

A string value that represents the format to use to format the message. Valid values are TEXT (plain text) and HTML. The default value is TEXT.

Message

A string value that represents the message body of the email message. The format of the text you provide should correspond with the value specified for the Message Format property. If the value of Message Format is HTML, the text you provide should include HTML markup.

To provide a literal value, you need to use the Message Body Editor dialog box to specify the message. (See About Message Body Editor.) Click the ellipsis button to display the dialog box.

Character Set Encoding

A string value that represents the character set encoding to use on the subject and body of the email. No default is provided. When no value is provided, the default character set configured on the LiveCycle Server is used.

Provide a character set encoding value when your Workspace users need character set encoding that is different than the one used by the server. For example, if your server uses UTF-8 and your users need to read Japanese characters in email messages, set the character encoding to ISO-2022JP.

If you use a literal value to configure this property, select an encoding format from the list:

Note: The list of values depends on the operating system you use.

Big5, Big5-HKSCS
EUC-JP, EUC-KR
GB18030, GB2312, GBK
IBM-Thai, IBM00858, IBM01140, IBM01141, IBM01142, IBM01143, IBM01144, IBM01145, IBM001146, IBM001147, IBM001148, IBM001148, IBM037, IBM1026, IBM1047, IBM273, IBM277, IBM278, IBM280, IBM284, IBM285, IBM297, IBM420, IBM437, IBM500, IBM775, IBM850, IBM852, IBM855, IBM857, IBM860, IBM861, IBM862, IBM863, IBM864, IBM865, IBM866, IBM868, IBM869, IBM870, IBM871, IBM918
ISO-2022-CN, ISO-2022-JP, ISO-2022-KR, ISO-8859-1, ISO-8859-13, ISO-8859-15, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9
JIS_X0201, JIS_X0201-1990
KO18-R
Shift-JIS
TIS-620
US-ASCII
UTF16, UTF-!6BE, UTF16LE
(Default) UTF-8
windows-1250, windows-1251, windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257, windows-1258, 31j
X-Big5-Solaris, Xeuc-jp-linux, x-EUC-TW
x-eucJP-Open
x-IBM1006, x-IBM1046, x-IBM1097, x-IBM1098, x-IBM1112, x-IBM1122, x-IBM1123, x-IBM1124, x-IBM1381, x-IBM1383, x-IBM33722, x-IBM737, x-IBM834, x-IBM856, x-IBM874, x-IBM875, x-IBM921, x-IBM922, x-IBM930, x-IBM933, x-IBM935, x-IBM937, x-IBM942, x-IBM942C, x-IBM943, x-IBM943C, x-IBM948, x-IBM949, x-IBM949C, x-IBM950, x-IBM964, x-IBM970
x-ISCII91
x-ISO-2022-CN-CNS, x-ISO-2022-CN-GB, x-is-8859-11
x-JIS0208, x-JISAutoDetect
x-Johab
x-MacArabic, x-MacCentralEurope, x-MacCroatian, x-MacCyrillic, x-MacDingbat, x-MacGreek, x-MacHebrew, x-MacIceland, x-MacRoman, x-MacRomania, x-MacSymbol, x-MacThai, x-MacTurkish, x-MacUkraine
x-MS950-HKSCS
x-mswin-936
x-PCK
x-windows-50220, x-windows-50221, x-windows-874, x-windows-949, x-windows-950, xwindows-iso2022jp

Attachments properties

Use the Attachments properties to specify a file to attach to the email message.

Attachment Name

A string value that represents the file name to use for the attachment. You should include the file name extension if the email receiver needs to associate the file with software to open it.

Attachment

An object value that represents the file to attach to the email message.

Important: If you specify a string value, such as a URL for the file or a file name, a document that includes the string is attached, and not the document itself.

Connection Settings properties

Use the Connection Settings properties to specify information required for connecting to the SMTP email server.

Use Global Settings

SMTP Host

A string value that represents the IP address or URI of the email server. For example, you can use the name of the computer that is resolved by Domain Naming Scheme (DNS).

SMTP Port Number

An int value that represents the port number that the email server uses. If no value is specified, the value of 25 is used.

SMTP Authenticate

A boolean value that, if True, indicates that authentication with the email server is required for sending email. A value of False indicates that no authentication is required.

SMTP User

A string value that represents the email address that is associated with the user account on the email server that is used to send the email message.

SMTP Password

A string value that represents the password to use for authenticating with the email server. The password is associated by the user account that is associated with the value of the SMTP User property.

SMTP Transport Security

A string value that represents the transport security used when communicating with the email server. The following values are valid.

None:: Data is sent in clear text
SSL:: Secure Sockets Layer
TLS:: Transport Layer Security
The value you specify depends on how the email server is configured.

Exceptions

The exception event attached to this operation can receive the ConnectionFailedException, and SendMailFailedException exceptions.

Send With Map of Attachments operation

Sends an email message that has multiple attachments. The files to attach are saved in a map variable.

For information about the General and Route Evaluation property groups, see Common operation properties.

To Addresses properties

Use the To Addresses properties to specify who to send the email to. You can specify email addresses directly or import email addresses from a defined user list.

Note: If the selected user list contains any group, then the email addresses of the users and sub-groups inside the group are not imported. However, the email address of the group is imported.

To

A string value that represents one or more email addresses to send the email to. Separate email addresses with a comma.

CC

A string value that represents one or more email addresses to send a copy of the email to. Separate email addresses with a comma.

BCC

A string value represents one or more email addresses to send a copy of the email to, but the addresses are hidden from other recipients of the email. Separate email addresses with a comma.

From Addresses properties

Use the From Addresses properties to specify the email address used to send the email message.

From

A string value that represents the email address that is associated with the email user account that is sending the email message.

Reply To

A string value that represents the email address to which responses to the email are sent. If no value is specified, the email address specified for the From property is used.

Return To

(Optional) A string value that represents the email address to use as return address for the email envelope. If no value is specified, the email address specified for the From property is used.

Contents properties

Use the Contents properties to specify the content of the email message.

Subject

A string value that represents the text to use for the email message subject.

Message Format

A string value that represents the format to use to format the message. Valid values are TEXT (plain text) and HTML. The default value is TEXT.

Message

A string value that represents the message body of the email message. The format of the text you provide should correspond with the value specified for the Message Format property. If the value of Message Format is HTML, the text you provide should include HTML markup.

To provide a literal value, you need to use the Message Body Editor dialog box to specify the message. (See About Message Body Editor.) Click the ellipsis button to display the dialog box.

Character Set Encoding

A string value that sets the character set encoding to use on the subject and body of the email. No default is provided. When no value is provided, the default character set configured on the LiveCycle Server is used.

If you use a literal value to configure this property, select an encoding format from the list:

Note: The list of values depends on the operating system you use.

Big5, Big5-HKSCS
EUC-JP, EUC-KR
GB18030, GB2312, GBK
IBM-Thai, IBM00858, IBM01140, IBM01141, IBM01142, IBM01143, IBM01144, IBM01145, IBM001146, IBM001147, IBM001148, IBM001148, IBM037, IBM1026, IBM1047, IBM273, IBM277, IBM278, IBM280, IBM284, IBM285, IBM297, IBM420, IBM437, IBM500, IBM775, IBM850, IBM852, IBM855, IBM857, IBM860, IBM861, IBM862, IBM863, IBM864, IBM865, IBM866, IBM868, IBM869, IBM870, IBM871, IBM918
ISO-2022-CN, ISO-2022-JP, ISO-2022-KR, ISO-8859-1, ISO-8859-13, ISO-8859-15, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9
JIS_X0201, JIS_X0201-1990
KO18-R
Shift-JIS
TIS-620
US-ASCII
UTF16, UTF-!6BE, UTF16LE
(Default) UTF-8
windows-1250, windows-1251, windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257, windows-1258, 31j
X-Big5-Solaris, Xeuc-jp-linux, x-EUC-TW
x-eucJP-Open
x-IBM1006, x-IBM1046, x-IBM1097, x-IBM1098, x-IBM1112, x-IBM1122, x-IBM1123, x-IBM1124, x-IBM1381, x-IBM1383, x-IBM33722, x-IBM737, x-IBM834, x-IBM856, x-IBM874, x-IBM875, x-IBM921, x-IBM922, x-IBM930, x-IBM933, x-IBM935, x-IBM937, x-IBM942, x-IBM942C, x-IBM943, x-IBM943C, x-IBM948, x-IBM949, x-IBM949C, x-IBM950, x-IBM964, x-IBM970
x-ISCII91
x-ISO-2022-CN-CNS, x-ISO-2022-CN-GB, x-is-8859-11
x-JIS0208, x-JISAutoDetect
x-Johab
x-MacArabic, x-MacCentralEurope, x-MacCroatian, x-MacCyrillic, x-MacDingbat, x-MacGreek, x-MacHebrew, x-MacIceland, x-MacRoman, x-MacRomania, x-MacSymbol, x-MacThai, x-MacTurkish, x-MacUkraine
x-MS950-HKSCS
x-mswin-936
x-PCK
x-windows-50220, x-windows-50221, x-windows-874, x-windows-949, x-windows-950, xwindows-iso2022jp

Attachments properties

Use the Attachments properties to specify the files to attach to the email message.

Attachments

A map value that contains the attachments for the email message, represented as document values or string values. If the values are of type string, the value represents either a URL or a file name:

For a URL, the target of the URL is the content of the attachment. The LiveCycle Server needs to be able to access the URL target.
For a file name, the path is either on the LiveCycle Server or other location that the LiveCycle Server can access.

If the LiveCycle Server is running in a Windows environment, file names need to be in the following format:
```
file:///[file name]
```
For example, file:///c:/attachment.pdf.

The keys for the map are the attachment file names. The file names should include the file name extension if the email receiver needs to associate the file with software to open it. For information about retrieving values from a map, see Accessing data in data collections.

To express the literal value of the property, you need to use the Attachments dialog box. (See About Attachments.)

Connection Settings properties

Use the Connection Settings properties to specify information required for connecting to the SMTP email server.

Use Global Settings

SMTP Host

A string value represents the IP address or URI of the email server. For example, you can use the name of the computer that is resolved by Domain Naming Scheme (DNS).

SMTP Port Number

An int value that represents the port number that the email server uses. If no value is specified, 25 is used.

SMTP Authenticate

A boolean value that, if True, indicates that authentication with the email server is required for sending email. A value ofFalse indicates that no authentication is required.

SMTP User

A string value represents the email address that is associated with the user account on the email server that is used to send the email message.

SMTP Password

A string value represents the password to use for authenticating with the email server. The password is associated by the user account that is associated with the value of the SMTP User property.

SMTP Transport Security

A string value represents the transport security used when communicating with the email server. The following values are valid.

None:: Data is sent in clear text
SSL:: Secure Sockets Layer
TLS:: Transport Layer Security
The value you specify depends on how the email server is configured.

Exceptions

The exception event attached to this operation can receive the ConnectionFailedException, and SendMailFailedException exceptions.

Email exceptions

The Email service provides the following exceptions for receiving exception events.

ConnectionFailedException

Thrown when connection with the mail server cannot be established.

MessageNotFoundException

Thrown when no email messages are found on the mail server.

ReceiveMailFailedException

Thrown when messages cannot be retrieved from the mail server.

SendMailFailedException

Thrown when messages cannot be sent to the mail server.

About Message Body Editor

Use the Message Body Editor dialog box to create the body text for email messages. You can use the dialog box for creating body text in both plain text and HTML formats.

The text that you provide can include XPath expressions if part of the text is saved in a data location at run time.
If the email message is in HTML format, you need to include the HTML markup. The dialog box provides several buttons that insert opening and closing tags for several commonly-used HTML elements.
The dialog box shows a preview of the message in HTML format.

Design tab

Use the Design tab to enter the message body text. The Design tab includes the following features:

An editing area where you type the message text.
The Message Format box, located at the bottom of the tab, that indicates the message format that the operation is configured to use.
- Text: Indicates the message format is plain text.
- HTML: Indicates the message format is HTML.
A column of buttons, located along the right-side of the tab, that insert XPath expressions or HTML elements into the editing area.
- XPath: Opens XPath Builder that you can use for creating XPath expressions that are inserted into the editing area.
- Para: Inserts opening and closing p elements for defining a paragraph.
- Break: Inserts a br element for defining a line break.
- Bold: Inserts opening and closing b elements for bolding characters.
- Italics: Inserts opening and closing i elements for italicizing characters.
- Color: Inserts the following opening and closing span elements for defining text color:
```
<span style="color:Red;"></span>
```
- Font: Inserts the following opening and closing span elements for defining the font family and font size:
```
<span style="font-family: arial, sans-serif;  
    font-size: xx-small;"></span>
```
- Link: Inserts the following opening and closing a elements for defining anchors:
```
<a target="_blank" href=""></a>
```

Table: Inserts the following opening and closing table elements, than defines a table with two rows and two columns.

<table border="1" cellpadding="1" cellspacing="0" width="100%"> 
    <tr> 
        <td align="left" valign="middle" width="50%" 
        bgcolor="Silver">&nbsp;</td> 
        <td align="left" valign="middle" width="50%" 
        bgcolor="Silver">&nbsp;</td></tr> 
    <tr> 
        <td align="left" valign="middle" width="50%">&nbsp;</td> 
        <td align="left" valign="middle" width="50%">&nbsp;</td></tr> 
</table>

View full size graphic

HTML Preview tab

Use the HTML Preview tab to see how the text in the Editing area of the Design tab is rendered as HTML. The preview is refreshed automatically when you click the HTML Preview tab.

About Attachments

Use the Attachments dialog box to define file attachments to send with an email message using the Send With Map of Attachments operation. The dialog box includes a list that you populate with definitions of the file attachments.

To add a row to the list, click the + button. Click each cell in the row to specify values for each cell.

Name:

The file name. The file name should include the file name extension if the email receiver needs to associate the file with software to open it.

Interpretation:

Indicates how the operation should interpret the data that you specify as the file. Select one of the following values:

XPath indicates that the file content is expressed as an XPath expression. The expression evaluates to the location in the process data model that stores the data to use as the file content.
Literal indicates that the content is expressed as text. The text is the file content.
Template indicates that the content is expressed as a template expression. The template is the file content. (See Specifying template expressions.)
URL (XPath) indicates that the content is expressed as an XPath expression that evaluates to a data location that stores the URL of the file. The content is the target of the URL.
URL (Literal) indicates that the content is expressed as text and is interpreted as the URL for the file. The content is the target of the URL.

Value/XPath:

The content of the file. The value that you specify must coincide with the value you specified for Interpretation. Click the ellipsis button

to open XPath Builder, which you need to use to express the value.