Listing Emails with the Email Connector

Email Connector can list emails from any part of the flow. This capability is a change from the Mule 3 transport, which could only retrieve emails as a result of inbound endpoint polling.

Both the POP3 and IMAP configurations contain a list operation. Although there are differences between the configurations, the examples using either list-pop3 or list-imap apply to both configurations unless stated otherwise.

Configuring the Connector

There are two configurations for listing emails that are stored on a server:

POP3 configuration
IMAP configuration

Both of these configurations share a set of parameters that are required to establish a connection, including the server host and port, and the username and password to connect with a protected mail server. The username and password parameters are optional because some servers are not secured with a username and password.

The following are examples of POP3 and IMAP configurations:

POP3 Configuration

<email:pop3-config name="pop3-config">
    <email:pop3-connection host="pop.gmail.com" port="995" user="pablo.musumeci@mulesoft.com" password="#netherlands!"/>
</email:pop3-config>

IMAP Configuration

<email:imap-config name="imap-config">
    <email:imap-connection host="imap.gmail.com" port="912" user="pablo.musumeci@mulesoft.com" password="#netherlands!"/>
</email:imap-config>

The examples look similar. For differences, see the Configurations section in the Email Connector Technical Reference.

Secured Connections

The IMAP and POP3 configurations enable connections that are secured by the secured versions of the POP3S and IMAPS protocols. These connections enable you to configure a TLS context that enables both SSL and TLS encryption.

Here is an IMAPS example:

IMAP Configuration with TLS

<email:imap-config name="tls">
    <email:imaps-connection host="${port}" port="${port}">
        <tls:context enabledProtocols="TLSv1.2,SSLv3">
            <tls:key-store path="aKeystore" password="password"/>
            <tls:trust-store path="aTruststore.jks" password="changeit"/>
        </tls:context>
    </email:imaps-connection>
</email:imap-config>

A TLS context is also available for the POP3S connection.

Listing Emails

The List operations return all the emails in the configured mailbox server that reside in a parameterized mailbox folder.

Here is the basic syntax for listing the emails in a mailbox:

For POP3

<email:list-pop3 config-ref="pop3-config" mailboxFolder="INBOX"/>

For IMAP

<email:list-imap config-ref="imap-config" mailboxFolder="INBOX"/>

The previous examples return all the emails that reside in the INBOX folder in the configured mailbox servers.

Note that the config-ref attribute points to the configurations that are declared in the configuration examples.

Getting Data from Emails

Incoming emails carry the content of the email that is in the payload, which includes the email body and any attachments. The following example iterates over all the retrieved emails:

<flow name="retrieveWithAttachments">
    ...
    <email:list-imap config-ref="imap-config"/>
    <foreach>
        <set-variable variableName="email-content" value="payload.body" />
        <set-variable variableName="json-attachment" value="payload.attachments.json" />
    </foreach>
</flow>

When working with a single email in the payload, you use payload.body to access the email content. The example above sets the body to a variable called email-content.

To access the email attachments, you can use payload.attachments.{nameOfTheAttachment}. The example above sets an attachment called json that is carried by the retrieved email within a new variable json-attachment.

Attributes

When listing emails, you might be interested not only in the email’s content but also in its metadata (for example, the subject, from addresses, to addresses, received date, and so on). These attributes vary depending on the type of configuration that you are using. For example, the IMAP protocol provides more metadata about the retrieved email like the recent, seen, deleted, and answered flags.

Email Connector uses Mule message attributes to access this information, while the message payload always contains the email’s content.

For details on the structure of email attributes, see Email Module Documentation Reference.

Matching

When listing emails, you can filter them using the <email:pop3-matcher> and <email:imap-matcher> elements. These elements define the criteria that can be used to process an email.

Here is an example of an IMAP matcher that rejects emails with subjects that do not match the [0-9] regular expression and that have not been seen before:

<email:list-imap config-ref="config">
    <email:imap-matcher subjectRegex="[0-9]" seen="EXCLUDE"/>
</email:list-imap>

All matcher attributes are optional and are ignored if they are not provided. They are also related to each other under an AND operator, meaning that all the criteria must be true.

The previous example declares an inner, non-reusable matcher that is proprietary to a particular component. However, matchers can be declared as reusable elements (as named top-level elements), such as the following pop3-matcher:

<email:pop3-matcher name="pop3Matcher"
                    subjectRegex="Email Subject"
                    fromRegex="@mulesoft"/>

<flow name="listEmails">
  ...
  <file:list pop3-matcher="pop3Matcher" />
  ...
</flow>

IMAP Matcher Versus POP3 Matcher

The IMAP protocol provides metadata about the email that allows more precise filtering than POP3.

The POP3 matcher contains these parameters:

<email:pop3-matcher
  receivedSince="2015-06-03T13:21:58+00:00"
  receivedUntil="2015-07-03T13:21:58+00:00"
  sentSince="2015-05-03T13:21:58+00:00"
  sentUntil="2015-06-03T13:21:58+00:00"
  subjectRegex="BETA:"
  fromRegex="@mulesoft"/>

The IMAP matcher looks like this:

<email:imap-matcher
  receivedSince="2015-06-03T13:21:58+00:00"
  receivedUntil="2015-07-03T13:21:58+00:00"
  sentSince="2015-05-03T13:21:58+00:00"
  sentUntil="2015-06-03T13:21:58+00:00"
  subjectRegex="BETA:"
  fromRegex="@mulesoft"
  recent="EXCLUDE|INCLUDE|REQUIRE"
  seen="EXCLUDE|INCLUDE|REQUIRE"
  deleted="EXCLUDE|INCLUDE|REQUIRE"
  answered="EXCLUDE|INCLUDE|REQUIRE"/>

Notice that the IMAP matcher includes the recent, seen, deleted, and answered parameters.

Naming Strategy for Attachments

Email Connector provides a parameter for the List and On New Email operations that enables you to specify a strategy for naming attachments. This parameter is set at the configuration level, but can be overridden at the operation level.

See Naming Strategy For Attachments for more information and examples.