Get E-mail Action

Declaration

<AMPOP3MAIL ACTION="text" RESULTDATASET="test" ATTACHMENTDEST="text" SAVEMODE="text [options]" HOST="text" USER="text" PASSWORD="text" REMOVEMESSAGE="yes/no" PROXYTYPE="text" PROXYHOSTNAME="text" PROXYPORT="number">

See Also

SMTP E-mail, Dial Up, HTTP Download, HTTP Post, Open Web Page

Description

Retrieves and/or removes e-mail messages from a POP3/IMAP/WEBDAV (Exchange Server) mail box. A dataset is created and populated with the message information. The dataset can be scanned using the Loop Dataset action and accessed by referencing %datasetname.field%. Note that messages will be processed even if they have already been processed unless the Remove mail from server parameter is checked.

Practical Usage

Commonly used to build an automated e-mail attendant. Can automatically download and detect content of messages. Based on the content of the messages, an automated reply (using Send EMail) could be made or data could be written to a database (using SQL Query).

Parameters

General Tab

Action to take

Text, Required
MARKUP: ACTION="all_messages"

Specifies the action that should take place during execution. The available options are:

Remove mail from server

yes/no, Optional - Default No
MARKUP: REMOVEMESSAGES="YES"

If retrieving messages, specifies that messages should be removed (deleted) from the server after they are downloaded. This option is ignored if the Action to take parameter is set to Delete all messages or Delete single message.

Save Attachments

yes/no, Optional - Default No
MARKUP: ATTACHMENTDEST="YES"

If the Action to take parameter is set to Get all messages or Get single message, specifies that any corresponding attachments will be downloaded along with the message.

Host

Text, Required
MARKUP: USERNAME="Anonymous"

Specifies the address of the mail server. This can be a host and domain name or IP address.

User Name

Text, Required
MARKUP: USERNAME="Anonymous"

Specifies the username that should be used when logging on to the Server.

Password

Text, Required
MARKUP: PASSWORD="password here"

Specifies the password that should be used when logging on to the Server. The Username should be preconfigured at the server level. When the step is created using the Task Builder it is written to the task encrypted.

Create and Populate Dataset

Text, Required
MARKUP: RESULTDATASET="DATESETNAME"

Name of the dataset that should be created and populated with the mail message data upon execution. To access the data in subsequent steps simply specify %DATASETNAME.FIELDNAME% inside a Loop Dataset <AMLOOPDATASET> action (to recurse the rows). See Notes below for more information.

Message ID/Message sequence number

Text, Optional - Default "Default"
MARKUP: MESSAGE="3"

Specifies the Message ID or index of the message to act on. This parameter is only valid if the Action to take parameter is set to Get single message or Delete single message.

 

Advanced Tab

Protocol Type

Text, Required
MARKUP: PROTOCOLTYPE="IMAP"

Specifies the protocol type to use. The available options are:

NOTE: Certain parameters may or may not be available depending on the protocol type selected.

Security

Text, Required
MARKUP: SECURITY="explicit"

Specifies the type of security protocol the mail server uses. This parameter is unavailable if the protocol type selected is WEBDAV (EXCHANGE SERVER). The available options are:

Port

Number, Optional - Default 110
MARKUP: PORT="100"

Specifies the port that should be used to connect to the mail server. When selecting POP3 as the protocol type, this parameter is set to port 110 as default. When selecting IMAP as the protpcol type, this parameter is set to port 143 as default. However, this parameter can be customized to allow the other port numbers. This parameter is unavailable if the protocol type selected is WEBDAV (EXCHANGE SERVER).

MailBox URL

Text, Required
MARKUP: MAILBOXURL="http://myserver/exchange/mailboxname"

Specifies the Exchange Server mailbox URL used to be used. This parameter is available only if the protocol type selected is WEBDAV (EXCHANGE SERVER).

Domain Name

Text, Required
MARKUP: DOMAINNAME="text"

Specifies the Exchange Server domain name to be used. This parameter is available only if the protocol type selected is WEBDAV (EXCHANGE SERVER).

Current Folder

Text, Required
MARKUP: CURRENTFOLDER="Inbox"

Specifies the current folder in which to retrieve e-mail messages from. The default folder that should be entered is normally Inbox. However, this parameter can be customized to specify a particular sub-folder to retrieve messages from. For example: Inbox/Support. This parameter becomes available only if the protocol type selected is IMAP.

Certificate

Text, Required
MARKUP: CERTIFICATE="c:\certificate\certname.pfx"

Specifies the full path and filename of the certificate (.cer or .pfx extension) used to authenticate with. This parameter is available only if the protocol selected under the Security parameter is Explicit TLS/SSL or Implicit TLS/SSL.

Password

Text, Optional
MARKUP: CERTIFICATEPASSPHRASE="encrypted"

Specifies the password or passphrase which corresponds to the certificate entered (certificates with .pfx extensions may include a password/passphrase). This parameter is available only if the protocol selected under the Security parameter is Explicit TLS/SSL or Implicit TLS/SSL.

Ignore invalid server certificate

yes/no, Optional - Default No
MARKUP: IGNOREINVALIDCERTIFICATE="YES"

If a server SSL certificate is issued by unknown or invalid certificate authority, AutoMate may generate an error. If this parameter is enabled, AutoMate will automatically ignore any invalid server certificate it detects. This parameter is available only if the protocol selected under the Security parameter is Explicit TLS/SSL or Implicit TLS/SSL.

 

Attachments Tab

Save Attachments in Folder

Text, Optional - Default (none)
MARKUP: ATTACHMENTDEST="c:\tempattachmentfoldername"

Specifies the folder into which attachments should be saved.

If filename already exists

text [options], Optional - Default "ignore"
MARKUP: SAVEMODE="overwrite"

Specifies how to handle an attachment if one already exists with the same filename.

The available options are:

 

Filters Tab

NOTE: Filters tab settings are available only when the Action to take parameter located in the General tab is set to Get all messages or Delete all messages. This allows retrieval or removal of particular e-mail messages which match only the filter(s) specified. To specify more than one item per field, use wildcards (i.e. * or ?). For example, to specify all From recipients within a specific domain, enter *@networkautomation.com in the From field.

Have Attachments

Text, Optional
MARKUP: HASATTCHMENT="yes"

Specifies whether messages with or without attachments should be retrieved/deleted. The available options are:

Only if newer than

Number, Optional
MARKUP: IFNEWERTHAN ="01/27/2009 9.00.00 AM"

Specifies that only messages newer than the date/time specified will be retrieved/deleted.

Only if older than

Number, Optional
MARKUP: IFOLDERTHAN ="01/27/2009 9.00.00 AM"

Specifies that only messages older than the date/time specified will be retrieved/deleted.

 

Proxy Tab

Proxy Type

Text [options], Optional - Default (none)
MARKUP: PROXYTYPE="Socks5"

Specifies proxy protocol that should be used.  If you are unsure of the value to use in this parameter, contact your network administrator.

The available options are:

Note:  To create the most portable tasks it is best to specify "system default" and specify proxy settings in the Preferences of the Task Administrator (Proxy Tab).  By proceeding this way, tasks created in one environment that may have a proxy server will be portable to others that do not - and vice-versa.

Proxy Port

Number, Optional - Default 1028
MARKUP: PROXYPORT="3000"

Specifies the port that should be used to connect to the proxy server. Most proxy servers operate on port 1028 (the default) however the proxy server can be customized to operate on other ports

Proxy Host

Text, Optional - Default (blank)
MARKUP: PROXYSERVER="proxy.host.com"

Specifies the hostname (server.domain.com) or IP address (xxx.xxx.xxx.xxx) of the proxy server.

User Name (Proxy)

Text, Optional - Default (none)
MARKUP: PROXYUSERNAME="username"

Specifies the username that should be used to authenticate when connecting through the proxy server. This option is only valid when Socks 5 is specified in the Proxy type as it is the only version that supports authentication.

Password (Proxy)

Text, Optional - Default (none)
MARKUP: PROXYPASSWORD="encrypted"

Specifies the password that should be used to authenticate when connecting through the proxy server. When the step is created using the Task Builder it is written to the task encrypted. This option is only valid when Socks 5 is specified in the Proxy type as it is the only version that supports authentication.

Notes

A fixed field Dataset is generated

A dataset is a multiple column, multiple row container object. This action creates and populates a dataset with the following fields:

datasetname
|--Attachments

|--Body

|--CCAddress

|--FromAdress

|--Headers

|--MessageID

|--ReplyAddress

|--Subject

|--ToAddress


along with the standard fields included in every dataset

|--CurrentRow

|--TotalRows

|--TotalColumns

|--ExecutionDate

|--RowsAffected

|--SQLQuery

|--Datasource

A record (row) is created for each mail message that is retrieved from the server. To access this data use the Loop Dataset Action to loop through the records, inside the loop you can extract the data from the field of your choice (from the current record) by using an embedded expression as follows:

%mydatasetname.subject%

This can be used in any parameter in any action. So, to display the data in a message box the AML code would look like this:

 <AMMESSAGEBOX MESSAGETEXT="%mydatasetname.subject%" WINDOWTITLE="The Subject of the message is">

At runtime the text %mydatasetname.subject% is replaced by the contents of the subject of the current record.

More on datasets

Custom Description

This action includes the Description tab for entering a custom step description.

More on setting custom step description

Standard Error Handling Options

This action also includes the standard Error Causes and On Error failure handling options/tabs.

More on Error Handling Options

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressing F2.

More on variables
More on expressions

More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

<AMPOP3MAIL ACTION="all_messages" RESULTDATASET="MAILMESSAGES" ATTACHMENTDEST="c:\messageattachments" SAVEUNIQUE="YES" HOST="mail.server.com" USER="myusername" PASSWORD="

<AMLOOPDATASET DATASET="mailmessages">

  <AMMESSAGEBOX MESSAGETEXT="The current message subject is %mailmessages.subject%." WINDOWTITLE="Current Message %mailmessages.CurrentRow%">

</AMLOOP>