Hello and welcome to UiPath Essentials Training, E-mail Automation.
In this tutorial you will learn how to retrieve email and to send out email messages with UiPath.
Email is the oldest form of digital communication between people and to this day, many business
processes are still triggered by a simple email.
And since most of us keep close to our inbox throughout the day, getting an email report
about the status of an automated task might be essential sometimes to keeping it on track.
From an RPA perspective, two situations for interacting with email are:
Email as the input for our business process – we can receive the data in textual form,
as part of the subject or body of the email, or as an attachment, for example an Excel
file, a pdf or other file types.
Email can also represent the output of the process – in this scenario, email is most
commonly used for sending status updates to human supervisors regarding different automation
projects or when business or application exceptions occur.
Now let’s see the options available in UiPath Studio for email interaction.
Typing “mail” in the search box will retrieve all the activities that came with the UiPath.Mail.Activities
package, that is five groups of email activities.
Let’s take them one by one:
SMTP is short for Simple Mail Transfer Protocol and it’s a basic protocol used only for
sending messages.
POP3 stands for Post Office Protocol and it’s an old and almost obsolete protocol for reading
messages but most email servers support it.
IMAP or Internet Message Access Protocol is only used for receiving messages but offers
some useful features to mark messages as read or move them between folders.
Exchange is Microsoft’s enterprise email solution that UiPath integrates perfectly,
offering activities for sending and receiving messages, moving emails between folders and
deleting them.
The Outlook activities are slightly different.
They work with the API of the desktop application, so the actions already have a context.
There’s no need to set up servers, users, and other technical details – these activities
are designed to use the already existing Outlook accounts.
Finally, there are two generic email activities available for saving email messages and email
attachments on the local drive.
Ok, let’s first take a look at the options for checking email.
There are four Get Mail activities: POP3, Outlook, IMAP and Exchange.
All of them offer the same functionality of providing email messages; naturally, they
share other options as well.
Retrieving email from a particular mailbox folder
Fetching only unread messages and marking them as read, to avoid reprocessing
Limiting the number of incoming emails To set up a server connection, the server
address and port are generally required along with a user email and password.
Notice that IMAP and POP3 show validation warnings whereas Outlook and Exchange versions
don’t.
This is because while IMAP and POP3 require connection parameters, Outlook and Exchange
work with defaults and autodiscover, requiring less effort when used throughout workflows.
Having alternatives is great, however you might wonder which is the most convenient.
Well, if Outlook is already configured, that’s probably the handiest option - it requires
the least settings and offers extra features, while being compatible with any email protocols.
Now let’s take a look at how we can use these email protocols to retrieve email.
For example, IMAP: First, we need to set up the connection parameters.
These usually come from the email provider or from the IT department.
For the purpose of this exercise, we will use google mail: “imap.gmail.com”, on port number 993.
For email and password... let’s just presume that they’re passed in as arguments to our
workflow after we have already read them out of Orchestrator assets or from Windows Credential
Manager.
We’ll choose to read only unread messages, let’s say just 5 of them... and save them
in a variable named messages.
When we create this new variable the type is automatically set to List of Mail Messages.
Now let’s iterate through the received messages to check what we have in our Inbox, using
a ForEach activity.
The type of each item in the list should be specified here, so we will browse for MailMessage type.
Notice there are two results coming up - System.Net.MailMessage is the one that we are looking for.
Let’s use a message box to display the email subject for the messages in our mailbox
Typing “mail dot” and a drop-down shows the available mail message properties such
as Body, From, To and Subject. We’ll select Subject and hit Run –
the email subjects are displayed in a message box - one, two, three, four, five - so far,
so good.
Now let’s expand our example by filtering the incoming messages based on a known naming
convention and extract the attachments.
The emails have the subject line in this format: Employee, ID, personal data change request”.
We’ll first add a condition to our loop here, to look for subjects containing the
text “personal data change request”.
To work with the attached files, we’ll make use of the SaveAttachments activity.
We need to specify the mail and a local folder where the attachments will be downloaded.
To make this more interesting, let’s organize the attachments in separate subfolders for
each email; and to track them easier, we’ll use the employee ID specified in the subject
line as the folder name.
To extract the employee ID from the email subject we will use the “#” character
as a delimiter.
The Split result is an array, so we’ll take the second element,indexed as 1, and we split
it again, this time using “space” as delimiter, and isolate the first part, with index zero.
Now that we have extracted the employee ID, let’s add it to the file-path where the
attachment will be downloaded…
Let’s run this and see how it goes.
The robot takes a while for downloading the attachments.
Check out the project’s folder.
And here they are.
We had two messages in the expected format, so two folders have been created using the
employee IDs from the email subject fields.
And inside the folders we have the attachments, in this case a pdf called John Doe.
To recap, so far we have seen how to use IMAP to retrieve messages and also how to download
the attachments from unread emails with a specific subject pattern.
Now let’s move on to another example.
We will use GetOutlookMailMessages with a custom filter for getting emails from the
last 24 hours.
We’ll start a new workflow with a GetOutlookMailMessages activity and we’ll use a messages variable
just like we did in the previous example, for IMAP.
As you can see, the Inbox folder and OnlyUnread options are checked by default and no other
settings are required.
Let’s drag a MessageBox to see the number of unread emails from the Inbox:
“messages Count”, converted to String.
And run.
There are currently 5 unread messages in the Inbox - and we put very little effort into
finding that out.
There are practical situations when business process decisions are based on the timestamp
of the received emails.
Let’s continue our sample to find out the incoming time for each message.
We will use a ForEach activity to work with every email in the message list just like
before.
Then we’ll drag this MessageBox inside the loop to display information.
MailMessage object draws most of its properties from the email headers, but unfortunately
does not directly provide timestamp information, so we need to look deeper into the Headers dictionary.
"Date" is the one that we need.
Let’s run this - 1, 2, 3, 4, 5.
You could see the different timestamps when each email has arrived.
Using Headers works well for all GetMail variants, but this approach has a drawback: emails need
to be retrieved first, attachments included, and this may slow down the automation dramatically.
Fortunately, Outlook provides a distinct feature that filters the incoming correspondence based
on various criteria like Subject, SenderEmailAddress or ReceivedTime.
If we want to only process emails received in the last 24 hours, we need to provide an
expression, like this one.
Basically we set a condition that the received time needs to be greater than “one day ago”.
This expression would work well, but hard coding a date is not recommended.
The best way to do this is: starting from today... minus one day... and convert it to
String in a custom format that Outlook recognizes.
Let’s run the workflow again - only one email has been retrieved, the one received today.
Outlook Filter as exposed by UiPath, relies on the underlying Microsoft components, so
for more details and samples for building Outlook filter expressions, we can always
refer to their documentation pages.
All right – so far, we have seen how to get email messages, how to save attachments
and how to filter incoming correspondence.
Let’s also take a look at emails as output of a business process.
In the following example, we’ll build a workflow that sends out a standard notification
when business process exceptions occur.
The email will contain a desktop screenshot taken when the exception appeared and a message
defined in a template file.
To get started, we need to pick a SendMail activity.
We have three very similar options: SMTP (short for Simple Mail Transfer Protocol), Outlook
and Exchange.
Let’s use the first one.
For SMTP only, we need to set up connection parameters.
Just like we did in the POP3 example, we will use the google server - “smtp.gmail.com”,
port number 587.
The email and password are passed in as arguments.
We can customize the name of the sender, to make it a bit more representative.
Next we’ll specify the recipient, subject and a short email message.
Let’s quickly run this, to see how it works.
Within a matter of seconds, the email has reached the inbox.
• Now, let’s send out a nice, complete message – we could write the whole message
right here, but that would be hard to manage and maintain.
An easier way to accomplish that is by using a template file, either in HTML format or
plain text.
To load the template we will use the ReadTextFile activity and select the emailTemplate.txt
file, which looks like this.
We load the text in a variable called template and we can use this variable instead of the
fixed email message.
Nothing more to it.
This method comes with an additional advantage: we can use the “String Format” function
to change placeholders from the text file, with dynamic content generated at runtime.
In this example, we’ll replace the braces in the template with the current timestamp,
using a special variable called “Now”, which outputs the current time and date.
Next, let’s add a screenshot to our message.
To do that, we’ll use the TakeScreeshot activity, which provides an Image object that
needs to be saved on the hard drive, since the SendMail activities only take filepaths
for attachments.
The SaveImage activity writes the screenshot to a PNG file.
Next we add an attachment with the screenshot file and execute the workflow.
As you can see, we’ve got mail.
Let’s check it out: the email contains the standard template, you can see the timestamp
in the body of the message and also the attached file, all as expected.
This concludes our Essential Training on Email Automation.
Today you have learned about sending and receiving messages, filtering emails, downloading attachments
and using message templates.
Pretty powerful features.
Happy automation!