Receive Mail

Receive Mail is a process starter activity that polls a mail server for the new mail. After detecting and retrieving a new mail, the Receive Mail activity starts the process.

General

The General tab has the following fields.

Field Literal Value/Module Property/Process Property Description
Name None The name to be displayed as the label for the activity in the process.
Host Yes The host name or IP address for the mail server.
Port Yes The default (110) port used to connect to POP3 server.
Protocol No

The protocol used by receive mail activity to connect to the mail server. The two types of protocols are:

• POP3
• IMAP
Authentication Type No

Select the authentication type. There are two types of authentication:

• Basic
• OAuth 2.0
User Name Yes The username for logging into the server.
Password Yes

The password for logging into the POP3 server.

When the Authentication Type is selected as OAuth 2.0, the Password field automatically gets disabled.

Oauth Configuration Yes

The name of the Oauth Configuration resource. In the OauthConfiguration Resource Template wizard, create a resource to connect to Oauth Configuration.

This field is enabled only when IMAP is selected in the Protocol field.

For more information, see OAuth Configuration Resource.
Polling Interval (Sec) Yes The polling interval (in seconds) to check for new mail. The default is 5, if no polling interval is specified.
Delete Mail None Select this check box to delete the mail from the server after process starter has retrieved it.
Note: To delete mail, place a Checkpoint activity immediately after the Receive Mail process starter. This ensures that the message is not lost in the event of a machine failure.

Alternatively, you can leave this field clear.

Enable Confidentiality None This check box specifies whether a Secure Sockets Layer (SSL) Client should be used to specify the SSL configuration. When this check box is selected, the SSL Client field displays.
SSL Client Yes The name of the resource. In the SslClientResource Resource Template wizard, create a resource to connect to the SSL client.

Test Connection Button

The Test Connection button tests the connection to the specified mail server. Use this button to ensure that your Receive Mail activity is properly configured to receive mail from the specified mail server. This button is enabled only when the POP3 protocol is selected and theHost, User Name, and Password fields on the General tab are populated.

Description

Provide a short description for the Receive Mail activity.

Advanced

The Advanced tab contains the following fields:

Field Description
Sequence Key Contains an XPath expression that specifies which process runs in a sequence. Process instances with sequencing keys evaluating to the same value, are executed in the sequence the process instance was created.
Custom Job Id This field can contain an XPath expression that specifies a custom ID for the process instance.
Provide Raw Message When selected, this field specifies the whole message to be provided in the binary form. The output schema changes to include an element named rawMessage that contains the message instead of bodyText and mimeEnvelopeElements.

The Receive Mail process starter uses the javax.mail API. This API assumes that the content type of the message is multipart/mixed. When the multipart subtype is not mixed (such as multipart/signed or multipart/alternative) or when another content type is used (for example, application/*), the javax.mail API may not correctly parse the message.

Select this check box to send the raw message to a Java Invoke activity that uses the Java activation framework to implement the appropriate handlers to process the message.

For more information about how the Java activation framework can be used for this purpose, see the API documentation for javax.activation and javax.mail.

You can also feed the binary message to the javax.mail.MimeMessage constructor in the form of a java.io.InputStream to construct a MimeMessage object. The default javax.mail API handler is used in such a case.

Write to File Select this check box to specify that the incoming messages whose body and attachments (or raw message size, if Provide Raw Message is selected) exceed the specified threshold size, must be written to a file instead of being stored in memory. You can accept large incoming messages without consuming more memory. The incoming message is written to the file with mail headers when body and attachment exceeds the specified size.

Selecting this check box displays the Directory, Creating Non-Existing Directories, and Threshold Data Size(bytes) fields.

Do not select to keep the incoming messages in memory.

Note: The files created by using this option are not deleted automatically. You must manage the storage used by these files and delete them when they are no longer used.
Directory The directory to write messages that are above the specified threshold. The process engine does not attempt to create the directory, if the specified directory does not exist. Therefore, create the directory before starting the process engine.
Create Non-Existing Directories The directory to write messages that are above the specified threshold.

If the specified directory does not exist, the process engine does not attempt to create the directory. Therefore, select the check box to create the directory before starting the process engine.

Not selecting this check box with one or more non-existing directories in the specified path in the Directory field, raises an exception.

Threshold Data Size (bytes) The maximum size (in bytes) of an incoming message that can be kept in memory. Messages larger than the specified size are written to a file in the specified directory. The file name is an output so that the subsequent activities in the process properties can access the file and read its contents.

Specifying zero (0) in this field determines all incoming messages to be saved to a file.

Output Editor

Incoming messages may contain custom headers. From the Output Editor tab, define a custom schema for the headers of the incoming mail messages. You can also specify any standard header supported by the javax.mail package. For example, X-Mailer or X-Priority. Values of headers in the incoming message populates the corresponding defined output headers of the same name.

Output

The following is the output of the activity.

Output Item Datatype Description
from string The email address of the sender of the email.
to string The recipient list of the email.
cc string The cc (carbon copy) list of the email.
replyTo string The reply to list of the email.
subject string The subject of the email.
sentdate string The date the email was sent.
Headers complex This element contains the schema you defined on the Output Editor tab. You can specify custom headers that can be included in the incoming mail messages.
bodyElement string Contains a choice element.

You can either provide the bodyText element or fileName element.

mimeEnvelopeElement complex This field is available when the Provide Raw Message check box on the Advanced tab is not selected.

Contains the message attachments. This element contains a repeating element named mimePart that comprises each mime attachment.

mimeHeaders complex This element contains the mime header for each mimePart.

mimeHeaders contain the following information:

  • content-disposition - To suggest a filename for an attachment, use "*;filename=<filename>" in this element.
    Note: E-mail servers may alter or ignore the suggested name.
  • content-type
  • content-transfer-encoding
  • content-id
  • any element

For more information about MIME headers and their syntax, see http://www.faqs.org/rfcs/rfc2045.html.

Note: When the contentType is specified as "text/*" (for example, "text/xml"), specify the attachment content in either the textContent input element or the file name storing the attachment in the fileName input element. When the contentType is anything other than "text/*":
  • The attachment content must be in the binaryContent input element.
  • The file name storing the attachment must be in the fileName input element.
binaryContent | fileName | textContent choice This element contains the mime attachment. It can be any of the following:
  • binaryContent: the content of the attachment when the attachment is binary data.
  • fileName: the file name of the attachment written on the disk.
  • textContent: the content of the attachment when the attachment is text data.