IMAP Transport Reference
Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version. |
The IMAP transport can be used for receiving messages from IMAP inboxes using the javax.mail
API. The IMAPS Transport uses secure connections over SSL/TLS.
Using the IMAP transport provides a simple way to interact with an IMAP server without having to write your own IMAP client. It allows you to log in to an IMAP server at a specified frequency, pull messages from the server, optionally filter them based on the email subject, and transform them into standard java objects which you can use in your application.
TLS/SSL connections are made on behalf of an entity, which can be anonymous or identified by a certificate. The key store provides the certificates and associated private keys necessary for identifying the entity making the connection. Additionally, connections are made to trusted systems. The public certificates of trusted systems are stored in a trust store, which is used to verify that the connection made to a remote system matches the expected identity.
Transport Info
Transport | Doc | Inbound | Outbound | Request | Transactions | Streaming | Retries | MEPs | Default MEP | Maven Artifact |
---|---|---|---|---|---|---|---|---|---|---|
IMAP |
one-way |
one-way |
org.mule.transport:mule-transport-imap |
|||||||
IMAPS |
one-way |
one-way |
org.mule.transport:mule-transport-imaps |
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:imap="http://www.mulesoft.org/schema/mule/imap"
xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
xmlns:file="http://www.mulesoft.org/schema/mule/file"
xmlns:email="http://www.mulesoft.org/schema/mule/email"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/current/mule-imap.xsd
http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/current/mule-email.xsd
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd">
<imap:connector name="imapConnector" />
<expression-transformer name="returnAttachments">
<return-argument evaluator="attachments-list" expression="*" optional="false"/> ❶
</expression-transformer>
<file:connector name="fileName">
<file:expression-filename-parser/>
</file:connector>
<imaps:connector name="imapsConnector"> ❶
<imaps:tls-client path="clientKeystore" storePassword="mulepassword" />
<imaps:tls-trust-store path="greenmail-truststore" storePassword="password" />
</imaps:connector>
<flow name="incoming-orders">
<imap:inbound-endpoint user="bob" password="password"
host="emailHost" port="143" transformer-refs="returnAttachments"
disableTransportTransformer="true"/> ❷
<collection-splitter/>
<file:outbound-endpoint path="./received"
outputPattern="#[function:datestamp].dat"> ❹
<expression-transformer>
<return-argument expression="payload.inputStream" evaluator="groovy" /> ❺
</expression-transformer>
</file:outbound-endpoint>
</flow>
</mule>
Namespace and Syntax
XML namespace:
xmlns:imap "http://www.mulesoft.org/schema/mule/imap"
xmlns:imaps "http://www.mulesoft.org/schema/mule/imaps"
XML Schema location:
http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/current/mule-imap.xsd
http://www.mulesoft.org/schema/mule/imaps http://www.mulesoft.org/schema/mule/imaps/current/mule-imaps.xsd
Connector syntax:
<imap:connector name="imapConnector" backupEnabled="true" backupFolder="backup" checkFrequency="90000"
deleteReadMessages="false" mailboxFolder="INBOX" moveToFolder="PROCESSED"/>
<imaps:connector name="imapsConnector" backupEnabled="true" backupFolder="backup" checkFrequency="90000"
deleteReadMessages="false" mailboxFolder="INBOX" moveToFolder="PROCESSED"/>
<imaps:tls-client path="clientKeystore" storePassword="mulepassword" />
<imaps:tls-trust-store path="greenmail-truststore" storePassword="password" />
</imaps:connector>
Endpoint syntax: You can define your endpoints 2 different ways:
-
Prefixed endpoint:
<imap:inbound-endpoint user="bob" password="password" host="localhost" port="65433"/> <imaps:inbound-endpoint user="bob" password="password" host="localhost" port="65433"/>
-
Non-prefixed URI:
<inbound-endpoint address="imap://bob:password@localhost:65433"/> <inbound-endpoint address="imaps://bob:password@localhost:65433"/>
See the sections below for more information.
Features
-
Simple to configure email access on inbound endpoints: including authentication information and check frequency
-
Automate the handling of email attachments
-
Automatically back up messages to a specified folder
-
Automatically delete read messages
-
Easy to configure tls security
Usage
If you want to include the IMAP email transport in your configuration, these are the namespaces you need to define:
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:imap="http://www.mulesoft.org/schema/mule/imap"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/current/mule-imap.xsd">
...
For the secure version, you would use the following:
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:imaps="http://www.mulesoft.org/schema/mule/imaps"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/imaps http://www.mulesoft.org/schema/mule/imaps/current/mule-imaps.xsd">
...
Then you need to configure your connector and endpoints as described below.
Configuration Example
Say you had a business and wanted to take orders through email attachments. After you receive the email, you want to save the order attachments so they could be picked up by your order fulfillment process. The following Mule configuration checks an email box for emails, and saves the attachments to the local disk, where it can be picked up from a separate fulfillment process:
The built-in transformer is declared ❶ and gets the list of email attachments. This transformer is then applied to the pop3 inbound endpoint defined ❷. Then we define a list list-message-splitter-router ❸ which will iterate through all of the email attachments. Next we define a file outbound endpoint which will write the attachment to the './received' directory with a datestamp as the file name ❹. A simple groovy expression ❺ gets the inputStream of the attachment to write the file.
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:imap="http://www.mulesoft.org/schema/mule/imap"
xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
xmlns:file="http://www.mulesoft.org/schema/mule/file"
xmlns:email="http://www.mulesoft.org/schema/mule/email"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/current/mule-imap.xsd
http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/current/mule-email.xsd
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd">
<imap:connector name="imapConnector" />
<expression-transformer name="returnAttachments">
<return-argument evaluator="attachments-list" expression="*" optional="false"/> ❶
</expression-transformer>
<file:connector name="fileName">
<file:expression-filename-parser/>
</file:connector>
<flow name="incoming-orders">
<imap:inbound-endpoint user="bob" password="password" host="emailHost"
port="143" transformer-refs="returnAttachments" disableTransportTransformer="true"/> ❷
<collection-splitter/>
<file:outbound-endpoint path="./received" outputPattern="#[function:datestamp].dat"> ❹
<expression-transformer>
<return-argument expression="payload.inputStream" evaluator="groovy" /> ❺
</expression-transformer>
</file:outbound-endpoint>
</flow>
</mule>
The IMAPS connector has the TLS client and server keystore information ❶. The built-in transformer is declared ❷ and gets the list of email attachments. This transformer is then applied to the inbound endpoint ❸. Then we define a list list-message-splitter-router ❹ which iterates through all of the email attachments. Next we define a file outbound endpoint that writes the attachment to the './received' directory with a datestamp as the file name ❺. A simple groovy expression ❻ gets the inputStream of the attachment to write the file.
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:imap="http://www.mulesoft.org/schema/mule/imap"
xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
xmlns:file="http://www.mulesoft.org/schema/mule/file"
xmlns:email="http://www.mulesoft.org/schema/mule/email"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/current/mule-imap.xsd
http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/current/mule-email.xsd
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd">
<imap:connector name="imapConnector" />
<expression-transformer name="returnAttachments">
<return-argument evaluator="attachments-list" expression="*" optional="false"/> ❶
</expression-transformer>
<file:connector name="fileName">
<file:expression-filename-parser/>
</file:connector>
<imaps:connector name="imapsConnector"> ❶
<imaps:tls-client path="clientKeystore" storePassword="mulepassword" />
<imaps:tls-trust-store path="greenmail-truststore" storePassword="password" />
</imaps:connector>
<flow name="incoming-orders">
<imap:inbound-endpoint user="bob" password="password" host="emailHost"
port="143" transformer-refs="returnAttachments" disableTransportTransformer="true"/> ❷
<collection-splitter/>
<file:outbound-endpoint path="./received" outputPattern="#[function:datestamp].dat"> ❹
<expression-transformer>
<return-argument expression="payload.inputStream" evaluator="groovy" /> ❺
</expression-transformer>
</file:outbound-endpoint>
</flow>
</mule>
Configuration Reference
Connectors
The IMAP connector supports all the common connector attributes and properties and the following additional attributes:
Attribute | Description | Default | Required |
---|---|---|---|
backupEnabled |
Whether to save copies to the backup folder |
False |
No |
backupFolder |
The folder where messages are moved after they have been read. |
No |
|
checkFrequency |
Period (ms) between poll connections to the server. |
60000 |
Yes |
mailboxFolder |
The remote folder to check for email. |
INBOX |
No |
deleteReadMessages |
Whether to delete messages from the server when they have been downloaded. If set to false, the messages are set to defaultProcessMessageAction attribute value. |
true |
No |
moveToFolder |
The remote folder to move mail to once it has been read. It is recommended that 'deleteReadMessages' is set to false when this is used. |
No |
|
defaultProcessMessageAction |
The action performed if the deleteReadMessages attribute is set to false. Valid values are: ANSWERED, DELETED, DRAFT, FLAGGED, RECENT, SEEN, USER, and NONE |
SEEN |
No |
For the secure version, the following elements are also required:
Element | Description |
---|---|
tls-client |
Configures the client key store with the following attributes:
|
tls-trust-store |
Configures the trust store. The attributes are:
|
For example:
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:imap="http://www.mulesoft.org/schema/mule/imap"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/current/mule-imap.xsd">
<imap:connector name="imapConnector" backupEnabled="true" backupFolder="backup" checkFrequency="90000"
deleteReadMessages="false" mailboxFolder="INBOX" moveToFolder="PROCESSED"/>
...
Secure version:
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:imaps="http://www.mulesoft.org/schema/mule/imaps"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/imaps http://www.mulesoft.org/schema/mule/imaps/current/mule-imaps.xsd">
<imaps:connector name="imapsConnector" backupEnabled="true" backupFolder="backup" checkFrequency="90000"
deleteReadMessages="false" mailboxFolder="INBOX" moveToFolder="PROCESSED"/>
<imaps:tls-client path="clientKeystore" storePassword="mulepassword" />
<imaps:tls-trust-store path="greenmail-truststore" storePassword="password" />
</imaps:connector>
...
Endpoints
IMAP and IMAPS endpoints include details about connecting to an IMAP mailbox. You can configure the endpoints just as you would with any other transport, with the following additional attributes:
-
user: The user name of the mailbox owner.
-
password: The password of the user. Note that for Mule Runtime versions prior to 3.8.x, you need to escape the % character using %25 (HTML code for %).
-
host: The name or IP address of the IMAP server, such as www.mulesoft.com, localhost, or 127.0.0.1.
-
port: The port number of the IMAP server.
For example:
<imap:inbound-endpoint user="bob" password="password" host="localhost" port="65433"/>
Secure version:
<imaps:inbound-endpoint user="bob" password="password" host="localhost" port="65433"/>
You can also define the endpoints using a URI syntax:
<inbound-endpoint address="imap://bob:password@localhost:65433"/>
<inbound-endpoint address="imaps://bob:password@localhost:65433"/>
This will log into the bob
mailbox on localhost
on port 65433 using password password
. You can also specify the endpoint settings using a URI, but the above syntax is easier to read.
For more information about transformers, see the Transformers section in the Email Transport Reference.
For more information about filters, see the Filters section in the Email Transport Reference.
Maven Module
The email transports are implemented by the mule-transport-email module. You can find the source for the email transport under transports/email.
If you are using maven to build your application, use the following dependency snippet to include the email transport in your project:
<dependency>
<groupId>org.mule.transports</groupId>
<artifactId>mule-transport-email</artifactId>
</dependency>
Limitations
For more information about the limitations, see the Limitations section in the Email Transport Reference.