Mail

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.

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 schedule or even store the sensitive values such as the password to the Safe Box.

Variable NameDescription
_EMAIL_SERVERThe server name or IP address
_EMAIL_PROTOCOLThe server type, either "POP3" or "IMAP"
_EMAIL_USERThe user name
_EMAIL_SECURITYThe security, one of "password", "google" or "microsoft"
_EMAIL_PASSWORDThe 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 NameDescription
_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=false
Mail 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.