How to work with email using Gmail and RPA Framework
Sending email messages is one of the most common requirements when automating processes: it could be a report about the results of the process or maybe part of the automation itself, like emailing invoices as attachments.
The RPA Framework adds libraries that make handling email easy and convenient. This article will show you how to use the RPA.Email.ImapSmtp
library to send email messages from a Gmail account.
The library is meant to work with any SMTP server, not just Gmail. It can also read and manage email messages in any email account accessible via IMAP.
Configuration of the Gmail account
After May 30th, 2022, Google will require the use of Two Factor Authentication to access Gmail accounts.
You will need to set up an App password and use that password when sending an email (GMAIL_APP_PASSWORD
).
The other option is to use OAuth2, for which we have an OAuth2 setup example bot
If you have been using the "Less secure app access", meaning just your username and password, you will need to change to either of the options above before May 30th, 2022
Sending plain text email messages
Here is an example robot that sends a plain text message:
- We are adding the
RPA.Email.ImapSmtp
library at the top in the*** Settings ***
section, passing the server name for Gmail and the SMTP port to use as configuration. The port can be omitted when using the default value (in this case,587
). It is used here to display that it can be configured if needed. - In the
*** Variables ***
section, we set the required variables: the Gmail account username andGMAIL_APP_PASSWORD
, and the email message recipient. - In the
*** Tasks ***
section we add a new taskSend test email
, where we call theAuthorize
keyword passing our credentials, and then theSend Message
keyword, specifying the sender, recipient, subject and body of the message.
Note: It is not a good practice to write credentials in your robot code. We recommend to use Control Room vault to store your secrets securely.
Sending email messages with attachments
You can send files as attachments to a message.
To send a file called results.csv
residing in the same directory where you run the robot, the code becomes:
All we needed to do was add the line ... attachments=results.csv
to the Send Message
keyword.
Sending an email with multiple attachments
If you want to send an email message with multiple attachments, you must pass a list
of file paths as the attachments
arguments of the Send Message
keyword instead of a simple string.
If you have two files, results1.csv
and results2.csv
, in the same directory where you run the robot, the example code becomes:
- We are adding the
@{ATTACHMENTS}
list variable, filling it with the paths of our two files. - We are passing the variable containing the list as the
attachments
arguments of theSend Message
keyword.
To create and manage lists inside your keywords, check out the
Collections
library, part of the Built-in libraries provided by Robot Framework.
Sending HTML email messages with inline images
You can send images in the body of the email message using HTML.
To embed an image file called image.png
residing in the same directory where you run the robot, the code becomes:
In this case, we need to modify the Send Message
keyword:
- adding
html=True
to tell the SMTP server that we are sending an email in HTML format - adding the names (and path) of the images that we will use in the email body using the
images
parameter (images=image.png
) - now we can use the image in the body of the message, using HTML formatting:
body=<p>See this image: <img src='image.png' alt='approved image'/></p>
This is what the generated message will look like in an email client:
Sending multiple attachments and saving them
This robot sends multiple attachments, collects the messages by criterion (email subject) using the List Messages
keyword, logs some information regarding each email, and saves the attachments using the Save Attachment
keyword. It also uses a vault for the credentials.
Listing email messages by criteria
The above example robot uses the List Messages
keyword to list messages matching the given criteria. Learn more about the search syntax in the RFC 3501, IMAP4rev1 Protocol Specification.
IMAP search criteria examples and description
- See the official RFC 3501, IMAP4rev1 Protocol Specification.
- See the IMAP search example robot by Alejandro Antunes for practical examples.
Criterion example (search key) | Description |
---|---|
123 | Messages with message sequence numbers corresponding to the specified message sequence number set. |
ALL | All messages in the mailbox; the default initial key for ANDing. |
ANSWERED | Messages with the \Answered flag set. |
BCC "Text" | Messages that contain the specified string in the envelope structure's BCC field. |
BEFORE 1-May-2021 | Messages whose internal date (disregarding time and timezone) is earlier than the specified date. |
BODY "Text" | Messages that contain the specified string in the body of the message. |
CC "Text" | Messages that contain the specified string in the envelope structure's CC field. |
DELETED | Messages with the \Deleted flag set. |
DRAFT | Messages with the \Draft flag set. |
FLAGGED | Messages with the \Flagged flag set. |
FROM "Text" | Messages that contain the specified string in the envelope structure's FROM field. |
HEADER "Field" "Text" | Messages that have a header with the specified field-name (as defined in RFC-2822) and that contains the specified string in the text of the header (what comes after the colon). If the string to search is zero-length, this matches all messages that have a header line with the specified field-name regardless of the contents. Example: HEADER Message-ID <53513DD7.8090606@imap.local> |
KEYWORD "Keyword" | Messages with the specified keyword flag set. |
LARGER 4 | Messages with an RFC-2822 size larger than the specified number of octets. |
NEW | Messages that have the \Recent flag set but not the \Seen flag. This is functionally equivalent to "(RECENT UNSEEN)". |
NOT <search-key> | Messages that do not match the specified search key. Example: NOT FROM "Smith" |
OLD | Messages that do not have the \Recent flag set. This is functionally equivalent to "NOT RECENT" (as opposed to "NOT NEW"). |
ON 1-May-2021 | Messages whose internal date (disregarding time and timezone) is within the specified date. |
OR <search-key1> <search-key2> | Messages that match either search key. Examples: OR FROM "Google" SUBJECT "Hello" , OR DELETED (SEEN ANSWERED) , OR (OR DELETED SEEN) ANSWERED |
RECENT | Messages that have the \Recent flag set. |
SEEN | Messages that have the \Seen flag set. |
SENTBEFORE 1-May-2021 | Messages whose RFC-2822 Date: header (disregarding time and timezone) is earlier than the specified date. |
SENTON 1-May-2021 | Messages whose RFC-2822 Date: header (disregarding time and timezone) is within the specified date. |
SENTSINCE 1-May-2021 | Messages whose RFC-2822 Date: header (disregarding time and timezone) is within or later than the specified date. |
SINCE 1-May-2021 | Messages whose internal date (disregarding time and timezone) is within or later than the specified date. |
SMALLER 4 | Messages with an RFC-2822 size smaller than the specified number of octets. |
SUBJECT "Text" | Messages that contain the specified string in the envelope structure's SUBJECT field. |
TEXT "Text" | Messages that contain the specified string in the header or body of the message. |
TO "Text" | Messages that contain the specified string in the envelope structure's TO field. |
UID 2,4:7,9,12:* | Messages with unique identifiers corresponding to the specified unique identifier set. Sequence set ranges are permitted. Example: a message sequence number set of 2,4:7,9,12:* for a mailbox with 15 messages is equivalent to 2,4,5,6,7,9,12,13,14,15 |
UNANSWERED | Messages that do not have the \Answered flag set. |
UNDELETED | Messages that do not have the \Deleted flag set. |
UNDRAFT | Messages that do not have the \Draft flag set. |
UNFLAGGED | Messages that do not have the \Flagged flag set. |
UNKEYWORD "Keyword" | Messages that do not have the specified keyword flag set. |
UNSEEN | Messages that do not have the \Seen flag set. |
Combining IMAP search criteria (ANDing)
There is no "AND" operator. Combine search keys by appending them right after each other: