Downloading Email From a Mail Server [IMAP]

Last Updated: 12/06/2018 Introduced in Version: 2.0

Overview

A flow can retrieve messages from a mail server, display messages in a form or use them in others ways. To enable a flow to download emails from an IMAP mail server, in the Step Tabs panel, under the category Communication > IMAP, drag a Get Email component to the workspace and configure its properties in the Properties panel. The Get Email component is also available for use with a POP mail server.

Example

Our example flow will retrieve one message from our Gmail account and display its body text and headers in a form. A form to display the email – Form 1 – has already been created for this example.

Begin by navigating to a project folder and clicking the Create Flow button.

 

We’ll give the flow a name and select Create to open it in the Flow Designer.

 

In the Steps Tab locate All Steps> Communication>IMAP and select Get Headers component. Select Add or drag and drop onto the flow designer. 

 
 

To retrieve message headers, Get Headers 1 must be configured with the appropriate settings for the Gmail server. Most of the following settings are specific to the IMAP protocol. To download messages from a mail server via POP, refer to the article on Downloading Email From a Mail Server [POP].

We will configure Get Headers 1’s settings in the Properties panel, in the Inputs section. Because we only want to get one message, in the Count section, we will enter “1” in the Value field.

To authenticate our connection, we will enter the password for the email account in the Value fields in the sections Password.
To make the connection itself, in the Server section, we will enter “imap.gmail.com” in the Value field. In the Port section, in the Value field, we’ll enter “993”. We will also want to ensure that our authentication details are kept secure. In the Secure Connection section, we’ll select the Value checkbox.
To authenticate our connection, we will enter the username for the email account in the Value fields in the sections Username.
 
 

Once our flow has retrieved a message header, the Get Email component uses the header to retrieve the full message.

In the Steps Tab, under Communication > IMAP, we drag a Get Email component to the workspace.
 
 
 

Just as we configured the step Get Headers 1, we will also have to configure Get Email 1 with similar settings. We will configure Get Email 1’s settings in the Properties panel, in the Inputs section. To authenticate our connection, we will enter the username and password for the email account in the Value fields in the sections Username and Password.

To make the connection itself, in the Server section, we will enter  “imap.gmail.com” in the Value field. In the Port section, in the Value field, we’ll enter “993”. We will also want to ensure that our authentication details are kept secure. In the Secure Connection section, we’ll select the Value checkbox.

 

 

The Get Email step also uses a Unique ID. This field works on the assumption that previous steps may output more than one message header, from which we may only want to get a certain category of message. In the Unique ID section, we can select a category by selecting Select Value in the Mapping type drop down list. To set the path, we click the Path selector.

In the resulting pop-up, we select the path: GetHeaders1_Headers > All UniqueId > First. This path will select the header associated with the first (and, in this example, only) header outputted by Get Headers 1, when all messages are sorted by their unique identifiers.

Once our flow has retrieved a message, it needs to display that message in a form, which we’ve already designed.

In the Toolbox panel, under the category Forms [Interaction] > [Current Folder], we drag a Form 1 component to the workspace.
 
 
 

Next, we must map the outcomes of our flow steps.

Get Email 1 offers two possible outcomes – Found and Not Found. In the event that our email account contains no messages, there will be no point in displaying the form, so we will direct our flow to the End Step. If there is an email message, we want to display it in our form. The form also contains a Done button, and when the user clicks it, our flow will be directed to the End Step. In either circumstance, our user’s travel through our flow will be completed.

The [Form] Form 1 step displays next to an exclamation mark in a red box indicating an error, as it requires a list of email objects to input.

We select the [Form] Form 1 step and click the Show Mapping Editor link at the top of the Properties panel.

 

 

Our mapping consists of a single item – Headers – mapped to our input Email. With that done, we can click OK to close the Mapping Editor.

 

This completes our flow. It is now ready to save and test in the debugger.

 

Our flow works. As required, we are presented with a form that displays the details of a single message downloaded from our Gmail account. Now that the flow is complete, we need to run the flow. You can do this either by selecting Debug in the Flow Designer, or you can close the Flow Designer, right click on the Flow, and select Run Flow.

 

Additional Resources