3.4.3 Mail
DESCRIPTION
Mail - Get incoming mail from an IMAP or POP3 server. To send an email through an SMTP server use the Sendmail command.
The command supports three actions:
- Get - download mail from the server. The messages may be optionally filtered by their attributes.
- Set - set the SEEN flag of a message.
- Delete - Delete a message or messages.
Note that deleting of a Gmail message is subject to its options at the Settings page of the Forwarding and POP/IMAP tab. It may be archived, moved to trash or deleted immediately. Make sure to verify the options to get the expected outcome.
All actions support authentication parameters as follows:
server=<server_address>
- The the server name or IP address, for example imap.gmail.com. It may optionally contain the port number.
protocol=<IMAP|POP3>
- The server type (protocol), either "IMAP" or "POP3". If the parameter is omitted the command defaults to "IMAP". If the security parameter is set to "google" or "microsoft" the protocol falls back to IMAP regardless of this option.
user=<user_name>
- The mail server user name.
security=<password|google|microsoft>
-The security type (since 6.2.2), one of:
- "password" - plain password authentication. The password may be specified through the password parameter.
- "google" - OAuth2 authentication to the GMail IMAP server.
- "microsoft" - OAuth2 authentication to the MS Outlook IMAP server.
To enable either of the OAuth2 schemes you have to download the authentication token through the Tools→OAuth Token Manager window. Tokens are long lived but may be invalidated on the user side (password change, revocation through the Google Dev Console or MS Azure account, ...) or after they are not used for a long time (typically 6 months). Downloaded tokens are encrypted and stored in the Robot configuration file.
password=<password>
-The password. It is used only when the security is set to "password".
These parameters must be used only in the first Mail command. They are then saved internally and reused for subsequent commands called within the same script execution session.
The authentication parameters may be also specified through special variables. This approach allows to inject the authentication data from the command line or a workitem or even store the sensitive values such as the password to the Safe Box.
| Variable Name | Description |
|---|---|
| _EMAIL_SERVER | The server name or IP address |
| _EMAIL_PROTOCOL | The server type, either "POP3" or "IMAP" |
| _EMAIL_USER | The user name |
| _EMAIL_SECURITY | The security, one of "password", "google" or "microsoft" |
| _EMAIL_PASSWORD | The password |
Retrieving Mail
Since "Mail get" does not cache the messages locally and always loads the data anew it is recommended to filter the messages and/or set the maximum amount of messages searched. For example,
Mail get max=10 read=false subject="Request"
will search the 10 most recent emails for unread messages containing the word of "Request" in the subject.
The retrieved messages are sorted by the date (the newest first). Attachments are downloaded automatically to a temporary location on the hard drive and deleted at the end of the session. Message attributes are exposed to the script in form of variables:
| Variable Name | Description |
|---|---|
| _EMAIL_TOTAL_COUNT=<number> | Total number of messages in the last connected email folder |
| _EMAIL_NEW_COUNT=<number> | Number of new (unread) messages in the last connected email folder |
| _EMAIL_COUNT=<number> | Number of retrieved messages that matched the specified criteria |
| _EMAIL_FROM_<n>=<address> | Sender address of the n-th message |
| _EMAIL_TO_<n>=<address(es)> | Recipient or a semicolon separated list of recipients of the n-th message |
| _EMAIL_SUBJECT_<n>=<text> | Subject of the n-th message |
| _EMAIL_BODY_<n>=<text> | Body of the n-th message |
| _EMAIL_READ_<n>=<true|false> | The SEEN flag indicator (false=unread, true=read) of the n-th message |
| _EMAIL_FOLDER_<n>=<name> | The folder name the n-th message belongs to. |
| _EMAIL_UID_<n>=<id> | Identifier of the n-th message. It is used for the "set" and "delete" operations |
| _EMAIL_ATT_COUNT_<n>=<number> | Number of attachments of the n-th message |
| _EMAIL_ATT_NAME_<n>_<k>=<name> | File name of k-th attachment of the n-th message as it is specified in the message |
| _EMAIL_ATT_FILE_<n>_<k>=<file_path> | File path to the k-th attachment of the n-th message on the local hard drive |
SYNOPSIS
Mail get [server=<server_address>] [protocol=<IMAP|POP3>] [user=<user_name>] [password=<password>] [folder=<folder_name>] [from=<email_address>] [subject=<text>] [body=<text>] [attachment=<text>] [read=<true|false>] [max=<number>]
* Red colour indicates obligatory parameters
OPTIONS
folder=<folder_name>
- The folder on the IMAP server to connect to. If the parameter is omitted or the server type is POP3 it defaults to "INBOX".
from=<email_address>
- The sender address or it's part.
subject=<text>
- The message subject or a phrase it contains.
body=<text>
- The message body or a phrase it contains.
attachment=<text>
- An attachment name or a string it contains. For example, to retrieve messages with an attached text file use ".txt".
read=<true|false>
- Retrieve only read (true) or unread (false) messages.
max=<number>
- Maximum number of the most recent messages to process. This parameter allows to avoid long delays on accounts containing a large number of messages. The default value is 100.
uid=<message_id>
-Identifier of the message to retrieve. It may be retrieved from the _EMAIL_UID variable populated by a previous call of "Mail get". When specified all other filtering parameters are ignored and the command returns the message only.
SYNOPSIS
Mail set [server=<server_address>] [protocol=<IMAP|POP3>] [user=<user_name>] [password=<password>] [folder=<folder_name>] [uid=<message_id>] [read=<true|false>]
* Red colour indicates obligatory parameters
OPTIONS
folder=<folder_name>
- The folder on the IMAP server to connect to. If the parameter is omitted or the server type is POP3 it defaults to "INBOX".
uid=<message_id>
-Identifier of the message to be updated. It may be retrieved from the _EMAIL_UID variable populated by "Mail get". When the parameter is omitted the command will update all messages retrieved by the most recently executed "Mail get" action.
read=<true|false>
- The target state of the SEEN flag. Use "false" to set the message status to unread or "true" to read.
SYNOPSIS
Mail delete [server=<server_address>] [protocol=<IMAP|POP3>] [user=<user_name>] [password=<password>] [folder=<folder_name>] [uid=<message_id>]
* Red colour indicates obligatory parameters
OPTIONS
folder=<folder_name>
- The folder on the IMAP server to connect to. If the parameter is omitted or the server type is POP3 it defaults to "INBOX".
uid=<message_id>
- Identifier of the message to be deleted. It may be retrieved from the _EMAIL_UID variable populated by "Mail get". When the parameter is omitted the command will delete all messages retrieved by the most recently executed "Mail get" action.
RETURNS
The command returns 0 (SUCCESS) only. If the mail server connection fails it throws an error which terminates the script.
EXAMPLES
Mail get server=imap.gmail.com user=john.doe@gmail.com password=welcome max=10 read=falseMail set read=true
- Search the most recent 10 emails from the specified Google account for unread ones and mark them as "read"
Var _EMAIL_SERVER=imap.gmail.com
Var _EMAIL_USER=john.doe@gmail.com
Var _EMAIL_PASSWORD=welcome
Mail get max=20 read=false attachment=".xls"
for (i=1; {i}<={_EMAIL_COUNT}; i={i}+1) {
Excel open file={_EMAIL_ATT_FILE_{i}_1}
Excel select ref=A1
Log "Value at A1 of the file {_EMAIL_ATT_NAME_{i}_1} is: {_EXCEL_CELL_VALUE}"
Mail set uid={_EMAIL_UID_{i}} read=true
}
- Download recent unread messages with a Microsoft Excel 97 file (.xls) in the first attachment. Open the file and log the first cell value. Then mark the message as "read".
This example shows how to automate processes by emails. Users may send requests (forms) by email to the specified address where it is picked up by a running Robot instance and processed.