Migrating to the Email connector

The POP3, IMAP and SMTP transports were completely rewritten. They evolved away from the Mule 3 transport model into a single operation-based connector.

This change enables many new capabilities:

The ability to list emails contents on demand, unlike the old IMAP and POP3 transports, which only provided a polling inbound endpoint.
Simplified experience to send emails.
Simplified experience to get the data of incoming emails.
Consistency between all mule connectors.
Advanced email matching functionality.

They were merged to a bring similar experience either you want to receive or send and

Migrating IMAP, POP3 or SMTP Server Configurations

Here you can see examples on how to migrate each one of the email transports configurations that were in mule 3 to the new mule 4 email connector.

In the following Mule 4 configuration examples you’ll see that most of the parameters that were declared in the inbound-endpoint or outbound-endpoint such as user, password, host, port between others have been moved to the connection element.

Migrating a POP3 Inbound Endpoint

Mule 3 Example: POP3 Inbound Configuration with Polling

<pop3:connector name="pop3"/>

<flow name="list">
    <pop3:inbound-endpoint checkFrequency="100" user="bob" password="password" host="pop.example.com" port="995"/>
    ...
</flow>

Mule 4 Example: POP3 Configuration

<email:pop3-config name="pop3">
  <email:pop3-connection connector-ref="pop3" host="pop.example.com" port="995" user="bob" password="password"/>
</email:pop3-config>

<flow name="list">
  <scheduler>
    <scheduling-strategy><fixed-frequency frequency="100"></scheduling-strategy>
  </scheduler>
  <email:list-pop3 config-ref="pop3"/>
  ...
</flow>

the list-pop3 operation does not perform the polling, an scheduler is in charge to trigger the flow.

Migrating an IMAP Inbound Endpoint

Mule 3 Example: IMAP Inbound Configuration with Polling

<imap:connector name="imap" checkFrequency="100"/>

<flow name="retrieve-emails">
  <imap:inbound-endpoint user="bob" password="password" host="pop.example.com" port="995"/>
  ...
</flow>

Mule 4 Example: POP3 Configuration

<email:imap-config name="imap">
  <email:imap-connection connector-ref="imap" host="pop.example.com" port="995" user="bob" password="password"/>
</email:imap-config>

<flow name="list">
  <scheduler>
    <scheduling-strategy><fixed-frequency frequency="100"></scheduling-strategy>
  </scheduler>
  <email:list-imap config-ref="imap"/>
  ...
</flow>

the list-imap operation does not perform the polling, an scheduler is in charge to trigger the flow.

Inbound Email Attachments

In Mule 3, attachments in the received email were set on the inboundAttachments field of the Message. In the Email connector for Mule 4, the attachments are a field of the message payload, modeled as a Map and accessible through DataWeave. For instance, to reference an attachment called photo_png, the expression is #[payload.attachments['photo_png']].

Migrating an SMTP Outbound Endpoint

Mule 3 Example: SMTP Outbound Configuration.

<smtp:connector name="smtp"/>

<flow name="send-email">
  ...
  <smtp:outbound-endpoint connector-ref="smtp" host="smtp.example.com" user="bob" password="password"
                          port="587" subject="Hello Ale!" from="bob@mulesoft.com" to="ale@mulesoft.com" />
</flow>

Mule 4 Example: SMTP Configuration

<email:smtp-config name="smtp">
    <email:smtp-connection host="smtp.example.com" port="587" user="bob" password="password"/>
</email:smtp-config>

<flow name="send">
    <email:send config-ref="smtp" subject="Hello Ale!" from="bob@mulesoft.com">
        <email:to-addresses>
            <email:to-address value="ale@mulesoft.com"/>
        </email:to-addresses>
        <email:body>
            <email:content>#[payload]</email:content>
        </email:body>
    </email:send>
</flow>

In the Mule 3 transport, the properties of the outgoing email (subject, addresses, and so on) could be configured through outbound properties set in the event, before the execution of the outbound SMTP endpoint. In that case, the outbound properties took precedence over the values configured in the endpoint or connector themselves.

Unlike Mule 3, attachments to be sent with an email must be configured explicitly on the email:send operation, rather that obtained from the outboundAttachments field of the Message. A suggested pattern for sending attachments is set them as variables in the flow and then reference those variables in the email:send operation to send those attachments.

Migrating SSL/TLS Secured Connections

In Mule 3, each transport/connector had its own TLS element. In Mule 4, the TLS context is the common element for configuring TLS across modules. In the next example we can see a Mule 3 example and how can it be migrated to Mule 4.

the example uses an SMTP configuration but is the same for the IMAP and POP3 configurations.

Mule 3 Example

<smtps:connector name="tls">
    <smtps:tls-client path="aKeystore" storePassword="password"/>
    <smtps:tls-trust-store path="aTruststore" storePassword="changeit"/>
</smtps:connector>

Mule 4 Example

<email:smtp-config name="tls">
    <email:smtps-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:smtps-connection>
</email:smtp-config>

Adding the Mule 4 Connector to a Project

Now that the transport are not bounded with Mule, you need to add it to your app using the Studio palette or add the following dependency in your pom.xml file in order to use it

<dependency>
    <groupId>org.mule.connectors</groupId>
    <artifactId>mule-email-connector</artifactId>
    <version>1.1.0</version> <!-- or newer -->
    <classifier>mule-plugin</classifier>
</dependency>