Description

Retrieves and/or removes e-mail messages from a POP3 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" check box is checked.

Commonly used to build and Automated Workflow email attendant. Can automatically download and detect content of messages. Based on the content of the messages, an Automated Workflow reply (using SMTP Email <AMSMTPMAIL>) could be made or data could be written to a database (using SQL Query <AMSQLQUERY>).

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">

Example

<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>

General Tab Parameters

Action to take: Specifies the action to take place.

• all_headers: Get all message headers (subject, date, to and from information). This is a fast way to see what is on the server, without downloading potential large message bodies and/or attachments.

• all_messages: Get all messages, include message bodies and attachments. This could take a long time if on a slow connection and there are messages containing a large attachment or a large amount of text in any of the message bodies.

• one_message: Retrieves a single message as indicated in the "Message Number" parameter. Message numbers can be retrieved by downloading headers only (all_headers) first.

• remove_all_messages: Clears the target mailbox by deleting all messages found on the specified server.

• remove_message: Deletes/removes a single message as designated in the "message number" parameter. Message numbers can be retrieved by downloading headers only (all_headers) first.

Text, Required
MARKUP: ACTION="all_messages"

Remove messages from Server: If retrieving messages, specifies that messages should be removed (deleted) from the POP3 server after they are downloaded. This option is ignored if ACTION= is set to remove_all_messages or remove_message.

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

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

Text, Required
MARKUP: USERNAME="Anonymous"

User name: Specifies the username that should be used when logging on to the POP3 Server. The Username should be preconfigured at the server level.

Text, Required
MARKUP: USERNAME="Anonymous"

Password: Specifies the password that should be used when logging on to the POP3 Server. The Username should be preconfigured at the server level. When the step is created using the Designer it is written to the Workflow encrypted.

Text, Required
MARKUP: PASSWORD="password here"

Port: Specifies the port that should be used to connect to the server. Most POP3 servers operate on port 110 (the default) however the mail server can be customized to operate on other ports.

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

Message number: Specifies the index of the message to act on. This parameter is only valid if action is set to one_message or remove_message

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

Create and populate dataset with e-mail: 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.

Text, Required
MARKUP: RESULTDATASET="DATESETNAME"

Attachments Tab Parameters

**Available only when Get all messages or Get single message is specified on the General tab.**

Save attachments in folder: Specifies the folder into which attachments should be saved. Click the Expression Builder icon to build and insert an expression.

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

If file name already exists: Specifies how to handle an attachment if one already exists with the same filename.

• Do not save (ignore): The file is not saved, old file is retained. (default)

• Save with a unique file name (unique): The file is rename to a unique filename before saving. New filename will be reflected in the dataset results.

• Overwrite existing files (overwrite): The old file is overwritten with the new one.

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

Proxy Tab Parameters

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

• System Default (default, recommended):  The settings specified are used.

• None:  Explicitly instructs the action not to use a proxy server regardless of the system default

• Socks 4:  Instructs the action to go through a Socks 4 compliant server

• Socks 4a:  Instructs the action to go through a Socks 4a compliant server

• Socks 5:  Instructs the action to go through a Socks 5 compliant server

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

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

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

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

Proxy port: 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.

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

User ID (Proxy): 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.

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

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

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

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.

See Also

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