Email - Get single message

Declaration

<AMGETEMAIL ACTIVITY="one_message" RESULTDATASET="text" 
MESSAGE="number" ATTACHMENTDEST="text" SERVER="text" 
TIMOUT="number" USERNAME="text" PASSWORD="text" 
SECURITY="text (options)" />

Description: Retrieves a single message from the server and populates a dataset with the results.

Practical Usage

Commonly used retrieve an email message by its message ID or message sequence number.

Connection Parameters

Property	Type	Required	Default	Markup	Description
Connection	---	---	---	---	Indicates where user credentials, server settings and other preferences required to establish a connection to the email server should originate from. This is a design mode parameter used only during task construction and configuration, thus, comprises no markups. The available options are: Host (default) - Specifies that user credentials, server settings and advanced preferences are configured individually for this activity. This option is normally chosen if only a single activity is required to complete an operation. Session - Specifies that user credentials, server settings and advanced preferences are obtained from a pre-configured session created in an earlier step with the use of the Email - Create session activity. This option is normally chosen if a combination of related activities are required to complete an operation. Linking several activities to a single session eliminates redundancy. Additionally, a single task supports construction and simultaneous execution of multiple sessions, improving efficiency.
Session	Text	Yes if Connection set to Session	EmailSession1	SESSION="emailSess1"	The name of the session. The default value is EmailSession1. This parameter is available only if the Connection parameter is set to Session.
Protocol	Text (options)	Yes if Connection set to Host	SMTP	PROTOCOLTYPE="POP3" PROTOCOLTYPE="IMAP" PROTOCOLTYPE="WEBDAV" PROTOCOLTYPE="EWS"	The type of email protocol to connect to. This parameter is available only if the Connection parameter is set to Host. Different parameters become available depending on which option is chosen. The available options are: POP3 (default) - An application-layer Internet standard protocol used by local email clients to retrieveemailfrom a remoteserver over a TCP/IP connection.POP3 allows you to download email messages on your local computer and read them even when you are offline. IMAP - IMAP (Internet Message Access Protocol) is a mail protocol used for accessing email on a remote web server from a local client. WEBDAV (Exchange 2003, 2007) - WEBDAV(World Wide Web Distributed Authoring and Versioning) is the Internet Engineering Task Force standard for collaborative authoring on the Web. EWS (Exchange 2007 & newer, Online) - EWS (Exchange Web Services) provides the functionality to enable client applications to communicate with the Exchange server. It provides access to much of the same data that is made available through Microsoft Outlook. EWS clients can integrate Outlook data into Line-of-Business (LOB) applications.
Server	Text	Yes	(Empty)	SERVER="mail.server.com"	The SMTP server that should be used to send the message. This parameter is available only if the Protocol parameter is set to POP3 or IMAP.
Port	Number	No	110	PORT="3333"	The port that should be used when connecting to the SMTP server. Most SMTP servers run on port 110 (default port number) however, this parameter can be customized to connect to another port. This parameter is available only if the Protocol parameter is set to POP3 or IMAP.
Security	Text (options)	Yes	No security	SECURITY="NONE" SECURITY="EXPLICI" SECURITY="IMPLICIT	The type of security that this action should use. This parameter is available only if the Protocol parameter is set to POP3 or IMAP. The available options are: No Security (default) - Specifies that no security will be administered. Explicit TLS/SSL - Indicates that Explicit Transport Layer (TLS) and Secure Sockets Layer (SSL) security will be administered. Implicit TLS/SSL - Indicates that Implicit Transport Layer (TLS) and Secure Sockets Layer (SSL) security will be administered.
Authentication Type	Text (options)	Yes if Authentication is enabled	(Empty)	AUTHTYPE="plain" AUTHTYPE="DigestMD5" AUTHTYPE="CramMD5" AUTHTYPE="Login" AUTHTYPE="ClearText" AUTHTYPE="APOP" AUTHTYPE="NTLM" AUTHTYPE="GSSapi"	Specifies the authentication type to administer. The following options are: Auto (default) - Advanced Workflows will automatically determine the authentication type being used. Plain - Consists of a single message from the client to the server. The client sends the authorization identity (identity to login as), followed by a US-ASCII Null character, followed by the authentication identity (identity whose password will be used), followed by a US-ASCII Null character, followed by the clear-text password. The client may leave the authorization identity empty to indicate that it is the same as the authentication identity." DigestMD5 - An algorithm that is used to verify data integrity through the creation of a 128-bit message digest from data input (which may be a message of any length) that is claimed to be as unique to that specific data as a fingerprint is to the specific individual.During a DIGEST-MD5 authentication exchange between a client and the server, there is additional information passed which is used to construct a more robust hashing algorithm when compared against a CRAM-MD5 authentication making it more difficult to decipher. CramMD5 - Challenge Response Authentication Mechanism is similar to DIGEST-MD5 in that it verifies data integrity through the creation of a 128-bit message digest. Login - Authentication through logon credentials. ClearText - Transmitted or stored text that has not been subjected to encryption and is not meant to be encrypted. As such, cleartext does not require decryption to be displayed. APOP - Authenticated Post Office Protocolpermits a client computer to retrieve email from a Post Office Protocol (POP) server while providing authentication technology that includes password encryption upon client receipt. NTLM - Abbreviation for "Windows NT LAN Manager." NTLM is the default for network authentication in the Windows NT 4.0 operating system. GSSapi - The Generic Security Service Application Program Interface is an application programming interface for programs to access security services. OAuth20 - Provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end-user). It also provides a process for end-users to authorize third-party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.
Username	Text	Yes if Authentication is enabled	(Empty)	USERNAME="theuser"	The user name to use to logon to the mail server and authenticate the mail transaction. NOTE: The From address entered should belong to the authenticated user.
Password	Text	Yes if Authentication is enabled	(Empty)	PASSWORD="encrypted"	The password used to logon to the mail server and authenticate the mail transaction.
Domain name	Text	Yes if Use Authentication is set to YES	(Empty)	DOMAINNAME="my.domain.com"	The domain name to authenticate with. This parameter is available only if the Use Authentication parameter is selected.
Certificate	Text	Yes if Security set to Explicit TLS/SSL or Implicit TLS/SSL	(Empty)	CERTIFICATE= "c:\folder\certname.pfx"	The full path and filename of the certificate (.cer or .pfx extension) used to authenticate with. This parameter is available only if the Security parameter is set to Explicit TLS/SSL or Implicit TLS/SSL.
Passphrase	Text	Yes if Security set to Explicit TLS/SSL or Implicit TLS/SSL	(Empty)	CERTIFICATEPASSPHRASE= "encrypted"	The certificate passphrase. This parameter is available only if the Security parameter is set to Explicit TLS/SSL or Implicit TLS/SSL.
Current folder	Text	No	Inbox	CURRENTFOLDER="inbox"	Specifies the current mailbox folder that this activity should be performed on. The default value is Inbox. To denote other Exchange well-known folders (e.g., Calendar, Drafts, Tasks, etc.) enter the Exchange property name for that folder. To specify subfolders, use a "/" (e.g., Inbox/SubFolderName). For more details regarding Exchange "well-known" folders, see the Additional Notes section below.
Timeout	Number	No	60	TIMEOUT="120"	The specified period of time that will be allowed to elapse (in seconds) before the server will close a client connection. This ensures that connections do not persist forever, if the client crashes or the network goes down. Open connections consume resources, and may prevent other clients from accessing the same mailbox. The default value is 60 seconds.
If the Protocol parameter is set to WebDAV (Exchange 2003, 2007) or EWS (Exchange 2007 & newer, Online), the following parameters become available.
Email address	Text	Yes	(Empty)	EMAILADDRESS= "guy@domain.com"	The email address to communicate with.
Exchange Server	Text	Yes	(Empty)	SERVER= "https://www.server.com"	The Exchange server to communicate with. This parameter is available only if the Protocol Type parameter is set to Exchange 2003 (WebDav), Exchange 2007 (EWS) or Exchange 2010 (EWS).
Autodiscover service URL	Yes/No	No	No	AUTODISCOVERURL="yes"	The Autodiscover service configures and maintains server settings for client computers that are running Microsoft Office Outlook 2007 and supported mobile devices. It provides access to Microsoft Exchange features for Outlook 2007 clients that are connected to your Microsoft Exchange messaging environment. If this parameter is set to YES, specifies that Autodiscover service requests will be performed. This parameter is set to NO by default and is only available if the Protocol Type parameter is set to Exchange 2007 (EWS) or Exchange 2010 (EWS).
Allow redirection	Yes/No	No	No	AUTODISCOVERURL="yes"	If set to YES, redirection (or mail forwarding) to another server will be allowed. This parameter is set to NO by default and is only available if the Protocol Type parameter is set to Exchange 2007 (EWS) or Exchange 2010 (EWS).
Impersonate	Yes/No	No	No	IMPERSONATE="YES"	Enables an account on an Exchange server to perform actions by using the permissions that are associated with another account. This option is available only under the Microsoft Exchange Web Services (EWS) protocol. font-size: 8pt; font-weight: bold;">NOTE: Impersonation differs from delegation in that a delegate account performs actions on behalf of a primary account; an impersonating account performs actions as if it were the primary account.
Ignore invalid server certificates	Yes/No	No	No	IGNOREINVALIDCERTIFICATE= "yes"	If set to YES, invalid or expired SSL server certificates that are detected will be ignored. If set to NO and an invalid server certificate is found, this step will throw an error stating that the security certificate on the server is not valid. This parameter is set to NO by default and is only available if the Protocol Type parameter is set to Exchange 2007 (EWS) or Exchange 2010 (EWS).
Authentication Type	Text (options)	No	(Empty)	AUTHTYPE="basic" AUTHTYPE="default" AUTHTYPE="form"	Specifies the authentication type to administer. The following options are: Basic Default Form
Username	Text	Yes if Use Authentication is set to YES.	(Empty)	USERNAME="theUser"	A valid user name used to logon to the mail server and authenticate the mail transaction. This parameter is available only if the Use Authentication parameter is set to YES. NOTE: The From address entered should belong to the authenticated user.
Password	Text	Yes if Use Authentication is set to YES.	(Empty)	PASSWORD="EncryptedText"	A valid password used to logon to the mail server and authenticate the mail transaction. This parameter is available only if the Use Authentication parameter is set to YES. NOTE: The From address entered should belong to the authenticated user.
Proxy type	Text (options)	No	System default	PROXYTYPE="socks4" PROXYTYPE="socks4a" PROXYTYPE="socks5" PROXYTYPE="http"	The 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: System default None Socks4 Socks4a Socks5 HTTP
Proxy server	Text	No	(Empty)	PROXYSERVER="proxy.host.com"	The hostname (server.domain.com) or IP address (xxx.xxx.xxx.xxx) of the proxy server.
Proxy port	Number	No	1028	PROXYPORT="3000"	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 username	Text	No	(Empty)	PROXYUSERNAME="username"	The username that should be used to authenticate when connecting through the proxy server. This option is only valid if the Use authentication parameter is enabled.
Proxy password	Text	No	(Empty)	PROXYPASSWORD="encrypted"	The password that should be used to authenticate when connecting through the proxy server. This option is only valid if the Use authentication parameter is enabled.

Email Parameters

Property	Type	Required	Default	Markup	Description
Create and populate dataset	Text	Yes	(Empty)	RESULTDATASET="theDataset"	Specifies the name of the dataset to create and populate with information about the retrieved email.
Remove mail from server	Yes/No	No	No	REMOVEMESSAGE="yes"	If set to YES, retrieved mail will be removed from the server. If set to NO, a copy of each message will remain in the server.
Message ID	Text	No	(Empty)	MESSAGEID="123456789a"	If enabled, specifies the message ID of the email message to delete. If this option is enabled, the Message sequence number parameter is ignored.
Message sequence number	Number	No	(Empty)	MESSAGE="12"	If enabled, specifies the message sequence number of the email message to delete. If this option is enabled, the Message ID parameter is ignored.
Save attachments in folder	Text	No	(Empty)	ATTACHMENTDEST="c:\temp"	If, enabled, specifies the folder in which to save attachments. Click the folder icon to navigate to the location in which attachments should be saved or simply enter the location in the provided text-box.
If file already exists	Text (options)	No	Do not save	SAVEMODE="unique" SAVEMODE="overwrite"	Determines what the step should do if an attachment file with the same name already exists in the destination folder. The available options are: Do not save (default) - The file will not be saved. Save with a unique name - The file will be saved with a unique name. Overwrite existing file - The new file will overwrite the existing file.

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Well-Known Mailbox Folders

Each user's mailbox folder has a set of properties that you can use to retrieve well-known folders such as Inbox, Calendar, Drafts, and Tasks. Specifying a subfolder requires the name of the appropriate folder from the well known folders level as the parent folder and use of a "/" sign as a delimiter (e.g., Inbox/SubFolderName). To specify a folder that you created in the well known folders level, you must specify the root of the message folder hierarchy (e.g., MsgFolderRoot/SubFolderName). The table below defines common folder names (in alphabetical order) that are used in users' mailboxes.

Name	Description
ArchiveDeletedItems	The Deleted Items folder in the archive mailbox.
ArchiveMsgFolderRoot	The root of the message folder hierarchy in the archive mailbox.
ArchiveRecoverableItemsDeletions	The root of the folder hierarchy of recoverable items that have been soft-deleted from the Deleted Items folder of the archive mailbox.
ArchiveRecoverableItemsPurges	The root of the hierarchy of recoverable items that have been hard-deleted from the Deleted Items folder of the archive mailbox.
ArchiveRecoverableItemsRoot	The root of the Recoverable Items folder hierarchy in the archive mailbox.
ArchiveRecoverableItemsVersions	The root of the Recoverable Items versions folder hierarchy in the archive mailbox.
ArchiveRoot	The root of the folder hierarchy in the archive mailbox.
Calendar	The Calendar folder.
Contacts	The Contacts folder.
DeletedItems	The Deleted Items folder.
Drafts	The Drafts folder.
Inbox	The Inbox folder.
Journal	The Journal folder.
JunkEmail	The Junk E-mail folder.
MsgFolderRoot	The root of the message folder hierarchy.
Notes	The Notes folder.
Outbox	The Outbox folder.
PublicFoldersRoot	The root of the Public Folders hierarchy.
RecoverableItemsDeletions	The root of the folder hierarchy of recoverable items that have been soft-deleted from the Deleted Items folder.
RecoverableItemsPurges	The root of the folder hierarchy of recoverable items that have been hard-deleted from the Deleted Items folder.
RecoverableItemsRoot	The root of the Recoverable Items folder hierarchy.
RecoverableItemsVersions	The root of the Recoverable Items versions folder hierarchy in the archive mailbox.
Root	The root of the mailbox.
SearchFolders	The Search Folders folder, also known as the Finder folder.
SentItems	The Sent Items folder.
Tasks	The Tasks folder.
Voicemail	The Voicemail folder.

Example

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Pop3 E-mail. Retrieve message number 10 from "mail.server.com". User name "username". Store in dataset "theDataset". Save attachment(s) to folder "c:\temp".

<AMGETEMAIL ACTIVITY="one_message" RESULTDATASET="theDataset" 
MESSAGE="10" ATTACHMENTDEST="c:\temp" FROM="Admin" 
SERVER="mail.server.com" TIMOUT="30" USERNAME="username" 
PASSWORD="AM2SEnYdJUXvbJISdh0lRevslpJuXTmF9ywaME" 
SECURITY="explicit"  />

Copyright © Fortra, LLC and its group of companies.
All trademarks and registered trademarks are the property of their respective owners.
v10 | 202212080228 | December 2022