Trigger a Flow When Receiving a New Email Examples - Mule 4

The following examples illustrate how you configure the Anypoint Connector for Email (Email Connector) source listeners On New Email - IMAP and On New Email - POP3 to identify and retrieve unread email messages, initiating a flow.

Configure the Delete After Retrieve Parameter

Email Connector On New Email - IMAP and On New Email - POP3 sources support the Delete after retrieve parameter that enables the deletion of retrieved emails from the mailbox folder after the operation process is complete. By deleting processed emails, you can ensure that the next processed emails are new ones. Because the POP3 protocol doesn’t support watermarking, the Delete after retrieve parameter is commonly used with this protocol.
The parameter is disabled by default to avoid deleting emails by mistake.

The following example shows how to configure this parameter in Anypoint Studio:

Select the On New Email - IMAP or On New Email - POP3 source in the Studio canvas.
In the source configuration screen, enable the Delete after retrieve parameter.

The following screenshot shows the Delete after retrieve configuration for the On New Email - IMAP source:

Figure 1. Delete after retrieve with On New Email - IMAP operation

In the XML editor, the configuration deleteAfterRetrieve="true" is under the listener-imap tag:

<flow name="OnNewEmail-IMAP">
		<email:listener-imap config-ref="Email_IMAP" watermarkEnabled="false" deleteAfterRetrieve="true">
			<scheduling-strategy >
				<fixed-frequency />
			</scheduling-strategy>
		</email:listener-imap>
	</flow>

The following screenshot shows the Delete after retrieve configuration for the On New Email - POP3 source:

Figure 2. Delete after retrieve with On New Email - POP3 operation

In the XML editor, the configuration deleteAfterRetrieve="true" is under the listener-pop3 tag:

<flow name="OnNewEmail-POP3">
  <email:listener-pop3 config-ref="Email_POP3" deleteAfterRetrieve="true">
    <scheduling-strategy >
      <fixed-frequency />
    </scheduling-strategy>
  </email:listener-pop3>
</flow>

Configure the Enable Watermark Parameter

Email Connector can watermark emails over the IMAP protocol by received date. The On New Email - IMAP source supports the Enable Watermark parameter, causing only those messages containing emails received after the last poll executed to be dispatched.

The following example shows how to configure this parameter in Anypoint Studio:

Select the On New Email - IMAP source in the Studio canvas.
On the source configuration screen, enable the Enable Watermark parameter.

The following screenshot shows this parameter configuration for the source:

Figure 3. Enable Watermark with On New Email - IMAP source

In the XML editor, the configuration watermark="true" is under the listener-imap tag:

<flow name="OnNewEmail-IMAP">
    <email:listener-imap config-ref="Email_IMAP" watermark="true">
        <scheduling-strategy>
            <fixed-frequency/>
        </scheduling-strategy>
    </email:listener-imap>
</flow>

Configure the IMAP Matcher and POP3 Matcher Parameters

Email Connector On New Email - IMAP and On New Email - POP3 sources support Imap matcher and Pop3 matcher parameters that enable you to configure custom matchers and thereby provide another way of filtering dispatched messages. Each source matcher can filter emails by dates, addresses, subject, flags, and so on.

The following example shows how to configure these parameters in Anypoint Studio by dispatching all messages that contain the word IMPORTANT:

Select the On New Email - IMAP or On New Email - POP3 source in the Studio canvas.
On the source configuration screen, for the Imap matcher or Pop3 matcher parameters, select either:
- Edit inline
  Set all the inline fields Seen, Answered, Deleted, Recent, and so on.
- Global reference
  Create a global reference configuration to automatically set all the inline fields.

Set the Subject regex field as IMPORTANT.

The following screenshot shows the Imap matcher edit inline configuration for the On New Email - IMAP source:

Figure 4. Imap matcher with On New Email - IMAP source

In the XML editor, the configuration imap-matcher subjectRegex="IMPORTANT" is under the listener-imap tag:

<flow name="OnNewEmail-IMAP">
    <email:listener-imap config-ref="Email_IMAP">
        <scheduling-strategy>
            <fixed-frequency/>
        </scheduling-strategy>
        <email:imap-matcher subjectRegex="IMPORTANT"/>
    </email:listener-imap>
</flow>

Configure the Attachment Naming Strategy Parameter

Email Connector On New Email - IMAP, On New Email - POP3, List - IMAP, and List - POP3 operations support the Attachment naming strategy parameter, which enables you to specify a strategy for naming attachments. You can set the parameter in a global element or override it at the operation level. The parameter has the following options: * NAME (Default)
Email Connector names the attachment after the value of the filename field in the Content-Disposition line of the attachment. If the filename field is not present or is empty, then the attachment is named Unnamed. If multiple attachments have no name, they are called Unnamed, Unnamed_1, Unnamed_2, and so on. * NAME_HEADERS
Email Connector first tries to obtain the name from the filename field in the Content-Disposition line (the same as when using NAME). If that fails, the connector looks for the name header in the Content-Type line of the attachment. If the name header is not present or is empty, then the attachment is named Unnamed. * NAME_HEADERS_SUBJECT
If both NAME_HEADERS and NAME_HEADERS_SUBJECT fail, then the connector checks if the attachment itself is an email (a nested message) and looks for the subject of the email. If the subject is not empty, then the attachment is named after the subject. Otherwise, the attachment is named Unnamed.

The following example shows how to configure this parameter in the global element:

In Studio, navigate to the Global Element view and click Create to open the Choose Global Type window.
In the Filter box, type email and choose either Email IMAP or Email POP3, and click OK.
In the Global Element Properties window, in the main Advanced tab, for the Attachment naming strategy field, select one of the following options:
- NAME
- NAME_HEADERS
- NAME_HEADERS_SUBJECT
In the General tab, for Connection select any of the connection types to provide to the configuration.
Specify the connection information for the connector, such as Host, Port, and TLS configuration.
On the subsequent Advanced tab, optionally specify timeout configuration and reconnection information, including a reconnection strategy.
Click OK.

The following screenshot shows the Attachment naming strategy configuration in the global element:

Figure 5. Attachment naming strategy Global Element

In the XML editor, the configuration attachmentNamingStrategy="NAME" is under the imap-config tag:

<email:imap-config name="gmail" attachmentNamingStrategy="NAME">
  <email:imap-connection host="imap.gmail.com" port="993" user="user@gmail.com" password="mypassword">
  </email:imap-connection>
</email:imap-config>

The following example shows how to override the naming strategy at the On New Email - IMAP source level:

Select the On New Email - IMAP source in the Studio canvas.
On the source configuration screen, in the Advanced tab, for the Attachment naming strategy field select one of the following options:
- NAME
- NAME_HEADERS
- NAME_HEADERS_SUBJECT

The following screenshot shows the Attachment naming strategy override at the On New Email - IMAP level source:

Figure 6. Attachment naming strategy override source level

In the XML editor, the configuration attachmentNamingStrategy="NAME" is under the listener-imap tag:

<flow name="OnNewEmail-IMAP">
		<email:listener-imap  config-ref="Email_IMAP" attachmentNamingStrategy="NAME">
			<scheduling-strategy >
				<fixed-frequency />
			</scheduling-strategy>
		</email:listener-imap>
	</flow>

Configure the Enable Remote Search for IMAP Matcher Parameter

When using the On New Email - IMAP source and Imap matcher parameter, you can specify whether you want the filters to be applied server-side by enabling the Enable Remote Search parameter.

This parameter is disabled by default because some email servers are not fully compliant with rfc-3501 search terms. Enabling the parameter decreases traffic by reducing the number of emails sent to the client-side for processing.

For this feature to be fully functional, the email server should support the use of at least the basic filtering flags: Answered, Deleted, Seen and Recent.

The following example shows how to configure this parameter in Anypoint Studio by enabling server-side filtering to exclude all answered emails:

Select the On New Email - IMAP source in the Studio canvas.
In the source configuration screen, for the Imap matcher, select Edit inline.
In the Answered field, select the value EXCLUDE.
Enable the Enable Remote Search parameter.

The following screenshot shows the Enable Remote Search configuration for the On New Email - IMAP source:

Figure 7. Enable Remote Search with On New Email - IMAP source

In the XML editor, the configuration remoteSearchFilterEnabled="true" is under the listener-imap tag:

<email:listener-imap config-ref="gmail" remoteSearchFilterEnabled="true">
    <scheduling-strategy>
        <fixed-frequency/>
    </scheduling-strategy>
    <email:imap-matcher answered="EXCLUDE"/>
</email:listener-imap>