Contact Free trial Login

Triggering a Flow When a New Email is Received

The Email connector provides a listener (called On New Email in the Studio and Design Center UIs) that polls an email folder from a mailbox for all the unread emails in it, generating a new message for each email that is found.

The key part of this functionality is how to determine that an email is new. There are three strategies for making this determination:

  • Setting the deleteAfterRetrieve parameter to true. This setting deletes each email from the mailbox folder after it has been processed so that all emails found in the next poll will be new.

  • Using a matcher to filter the polled emails.

  • The IMAP protocol also can take advantage of the watermark parameter to only pick emails that have been received after the last poll was executed.

Listener

The Email Connector provides two listeners that function similarly for the IMAP and POP3 protocols. However, the name of the XML element used depends on the email protocol:

  • listener-imap

  • listener-pop3

You can configure a scheduling-strategy on the listener to change the polling frequency of the components.

Example: IMAP Email Listener (On New Email Trigger)
<flow name="OnNewEmail">
    <email:listener-imap config-ref="imap-config">
        <scheduling-strategy>
            <fixed-frequency frequency="2000"/>
        </scheduling-strategy>
    </email:listener-imap>
    <flow-ref name="processEmail"/>
</flow>
Example: POP3 Email Listener (On New Email Trigger)
<flow name="OnNewEmail">
    <email:listener-pop3 config-ref="pop3-config">
        <scheduling-strategy>
            <fixed-frequency frequency="2000"/>
        </scheduling-strategy>
    </email:listener-pop3>
    <flow-ref name="processEmail"/>
</flow>

Delete After Retrieve

Both the POP3 and IMAP listeners can set the deleteAfterRetrieve parameter to true, enabling the deletion of the polled emails after processing is complete. This feature is disabled by default to avoid deleting emails by mistake.

Example: Delete After Retrieve
<flow name="OnNewEmailDeleteAfterProcessed">
    <email:listener-pop3 config-ref="pop3-config" deleteAfterRetrieve="true">
        <scheduling-strategy>
            <fixed-frequency/>
        </scheduling-strategy>
    </email:listener-pop3>
    <flow-ref name="processEmail"/>
</flow>

This parameter is commonly used with the POP3 protocol because there is no watermark support for it. By deleting processed emails, you can ensure that the next processed emails are new ones.

Is is important to understand that this feature DELETE the emails from the configured Mailbox Folder.

Watermarking

The Email connector can watermark emails when over the IMAP protocol, filtering emails based on their received date.

To enable watermark using the listener-imap trigger, just set the watermark parameter to true so that dispatched messages only contain emails received after the last poll executed.

Example: IMAP Watermark Email Listener
<flow name="OnNewEmailWatermark">
    <email:listener-imap config-ref="imap-config" watermark="true">
        <scheduling-strategy>
            <fixed-frequency/>
        </scheduling-strategy>
    </email:listener-imap>
    <flow-ref name="processEmail"/>
</flow>

Matchers

Custom matcher configurations provide another way of filtering the dispatched messages.

Both the POP3 and IMAP listeners have their own matchers that can filter emails by dates, addresses, subject, and flags (SEEN, ANSWERED, and so on).

Example: Email Listener with Matcher
<flow name="OnNewEmailWatermark">
    <email:listener-imap config-ref="imap-config">
        <scheduling-strategy>
            <fixed-frequency/>
        </scheduling-strategy>
        <email:imap-matcher subjectRegex="IMPORTANT"/>
    </email:listener-imap>
    <flow-ref name="processEmail"/>
</flow>

The example above only dispatches email messages that contain the word "IMPORTANT" in their subject.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub