IMAP Transport Reference

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	JavaDoc SchemaDoc		-	-	-	-	-	one-way	one-way	org.mule.transport:mule-transport-imap
IMAPS	JavaDoc SchemaDoc		-	-	-	-	-	one-way	one-way	org.mule.transport:mule-transport-imaps

Transport

Doc

Inbound

Outbound

Request

Transactions

Streaming

Retries

MEPs

Default MEP

Maven Artifact

IMAP

JavaDoc SchemaDoc

check

one-way

org.mule.transport:mule-transport-imap

IMAPS

JavaDoc SchemaDoc

check

one-way

org.mule.transport:mule-transport-imaps

Legend

Transport - The name/protocol of the transport
Docs - Links to the JavaDoc and SchemaDoc for the transport
Inbound - Whether the transport can receive inbound events and can be used for an inbound endpoint
Outbound - Whether the transport can produce outbound events and be used with an outbound endpoint
Request - Whether this endpoint can be queried directly with a request call (via MuleClient or the EventContext)
Transactions - Whether transactions are supported by the transport. Transports that support transactions can be configured in either local or distributed two-phase commit (XA) transaction.
Streaming - Whether this transport can process messages that come in on an input stream. This allows for very efficient processing of large data. For more information, see Streaming.
Retry - Whether this transport supports retry policies. Note that all transports can be configured with Retry policies, but only the ones marked here are officially supported by MuleSoft
MEPs - Message Exchange Patterns supported by this transport
Default MEP - The default MEP for endpoints that use this transport that do not explicitly configure a MEP
Maven Artifact - The group name a artifact name for this transport in Maven

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/3.3/mule-imap.xsd
http://www.mulesoft.org/schema/mule/imaps http://www.mulesoft.org/schema/mule/imaps/3.3/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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/3.3/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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/imaps http://www.mulesoft.org/schema/mule/imaps/3.3/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 iterates through all of the email attachments. Next we define a file outbound endpoint which 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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.3/mule-file.xsd
       http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/3.3/mule-imap.xsd
       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/3.3/mule-email.xsd
       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.3/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 thls 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 which 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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.3/mule-file.xsd
       http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/3.3/mule-imap.xsd
       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/3.3/mule-email.xsd
       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.3/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>

Note: In this code example, spring-beans-current.xsd is a placeholder. To locate the correct version, see http://www.springframework.org/schema/beans/.

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. This is very useful when working with public email services such as GMail where marking messages for deletion doesn’t work. Instead set the @moveToFolder=GMail/Trash.		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

Attribute

Description

Default

Required

backupEnabled

Whether to save copies to the backup folder

False

backupFolder

The folder where messages are moved after they have been read.

checkFrequency

Period (ms) between poll connections to the server.

60000

Yes

mailboxFolder

The remote folder to check for email.

INBOX

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

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.
This is very useful when working with public email services such as GMail where marking messages for deletion doesn’t work. Instead set the @moveToFolder=GMail/Trash.

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

For the secure version, the following elements are also required:

Element	Description
tls-client	Configures the client key store with the following attributes: path: The location (which resolves relative to the current classpath and file system, if possible) of the keystore that contains public certificates and private keys for identification storePassword: The password used to protect the keystore class: The type of keystore used (a Java class name)
tls-trust-store	Configures the trust store. The attributes are: path: The location (which resolves relative to the current classpath and file system, if possible) of the trust store that contains public certificates of trusted servers storePassword: The password used to protect the trust store

Element

Description

tls-client

Configures the client key store with the following attributes:

path: The location (which resolves relative to the current classpath and file system, if possible) of the keystore that contains public certificates and private keys for identification
storePassword: The password used to protect the keystore
class: The type of keystore used (a Java class name)

tls-trust-store

Configures the trust store. The attributes are:

path: The location (which resolves relative to the current classpath and file system, if possible) of the trust store that contains public certificates of trusted servers
storePassword: The password used to protect the trust store

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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/imap http://www.mulesoft.org/schema/mule/imap/3.3/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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/imaps http://www.mulesoft.org/schema/mule/imaps/3.3/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 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
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 logs 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.

Schema

imap Schema - http://www.mulesoft.org/schema/mule/imaps/3.3/mule-imaps.xsd
Schema Structure - http://www.mulesoft.org/docs/site/3.3.0/schemadocs/schemas/mule-imap_xsd/schema-overview.html

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>

Mule-Maven Dependencies

If you are building Mule ESB from source or including Mule artifacts in your Maven project, it may be necessary to add the 'mule-deps' repository to your Maven configuration. This repository contains third-party binaries which may not be in any other public Maven repository.

To add the 'mule-deps' repository to your Maven project, add the following to your pom.xml:

<repositories>
    <repository>
        <id>mule-deps</id>
        <name>Mule Dependencies</name>
        <url>http://dist.codehaus.org/mule/dependencies/maven2</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Limitations

For more information about the limitations, see the Limitations section in the Email Transport Reference.

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs