POP3 Icon

POP3 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 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" checkbox is checked.

Practical Usage

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

Parameters

General Tab

Action to Take
Text, Required
MARKUP: ACTION="all_messages"

Specifies the action to take place. The available options are:

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.

Host
Text, Required
MARKUP: USERNAME="Anonymous"

Specifies the address of the POP3 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 POP3 Server. The Username should be preconfigured at the server level.

Password
Text, Required
MARKUP: PASSWORD="password here"

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 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 Number
Text, Optional - Default "Default"
MARKUP: MESSAGE="3"

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

Remove Messages from Mail Server
yes/no, Optional - Default No
MARKUP: REMOVEMESSAGES="YES"

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.

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

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.

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

Specifies the folder into which attachments should be saved.

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

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

Available Options Are:

ignore: The file is not saved, old file is retained. (default)
unique:
The file is rename to a unique filename before saving. New filename will be reflected in the dataset results.
overwrite:
The old file is overwritten with the new one.

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.

Available Options Are:

System Default (default, recommended) - The settings specified in the Task Administrator preferences 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 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.

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 by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, a popup expression builder is available in all these fields by pressing F2.
More on variables...

More on expressions...

More on the expression builder...

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>