Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.2)
  3. Reference Materials for Mule ESB 3
  4. = Reference Materials for Mule ESB 3

  5. POP3 Transport Reference

POP3 Transport Reference

Introduction

The POP3 transport can be used for receiving messages from POP3 inboxes. The POP3S tranport connects to POP3 mailboxes using the javax.mail API.

Warning

POP3 Polling May Fail if geronimo-mail is in the CLASSSPATH. For information on this problem, consult MULE-4875.

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.

Namespace and Syntax

XML namespace:

xmlns:pop3 "http://www.mulesoft.org/schema/mule/pop3"xmlns:pop3s "http://www.mulesoft.org/schema/mule/pop3s"

XML schema location:

http://www.mulesoft.org/schema/mule/pop3 http://www.mulesoft.org/schema/mule/pop3/3.2/mule-pop3.xsdhttp://www.mulesoft.org/schema/mule/pop3s http://www.mulesoft.org/schema/mule/pop3s/3.2/mule-pop3s.xsd

Connector syntax:

<pop3:connector name="pop3Connector" backupEnabled="true" backupFolder="backup" checkFrequency="90000"                 deleteReadMessages="false" mailboxFolder="INBOX" moveToFolder="PROCESSED"/><pop3s:connector name="pop3sConnector" backupEnabled="true" backupFolder="backup" checkFrequency="90000"                  deleteReadMessages="false" mailboxFolder="INBOX" moveToFolder="PROCESSED"/>  <pop3s:tls-client path="clientKeystore" storePassword="mulepassword" />   <pop3s:tls-trust-store path="greenmail-truststore" storePassword="password" /> </pop3s:connector>

Endpoint syntax: You can define your endpoints 2 different ways:

  1. Prefixed endpoint:

<pop3:inbound-endpoint user="bob" password="password" host="localhost" port="65433"/> <pop3s:inbound-endpoint user="bob" password="password" host="localhost" port="65433"/>

  1. Non-prefixed URI:

<inbound-endpoint address="pop3://bob:password@localhost:65433"/><inbound-endpoint address="pop3s://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 POP3 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-3.0.xsd       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.2/mule.xsd       http://www.mulesoft.org/schema/mule/pop3 http://www.mulesoft.org/schema/mule/imap/3.2/mule-pop3.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:pop3s="http://www.mulesoft.org/schema/mule/pop3s"       xsi:schemaLocation="       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.2/mule.xsd       http://www.mulesoft.org/schema/mule/pop3s http://www.mulesoft.org/schema/mule/pop3s/3.2/mule-pop3s.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:

<?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:pop3="http://www.mulesoft.org/schema/mule/pop3"       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-3.0.xsd       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.2/mule.xsd       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.2/mule-file.xsd       http://www.mulesoft.org/schema/mule/pop3 http://www.mulesoft.org/schema/mule/pop3/3.2/mule-pop3.xsd       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/3.2/mule-email.xsd       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.2/mule-vm.xsd">    <pop3:connector name="pop3Connector"  />    <expression-transformer name="returnAttachments">        <return-argument evaluator="attachments-list" expression="*" optional="false"/>  ❶    </expression-transformer>    <file:connector name="fileName">        <file:expression-filename-parser/>    </file:connector>        <model name="test">        <service name="incoming-orders">            <inbound>                <pop3:inbound-endpoint user="bob" password="password" host="mailServer"                       port="110" transformer-refs="returnAttachments"/> ❷            </inbound>            <outbound>                <list-message-splitter-router> ❸                    <file:outbound-endpoint path="./received" outputPattern="#[function:datestamp].dat"> ❹                        <expression-transformer>                            <return-argument expression="payload.inputStream" evaluator="groovy" /> ❺                        </expression-transformer>                    </file:outbound-endpoint>                                    </list-message-splitter-router>                            </outbound>        </service>    </model></mule>

The built-in transformer is declared on ❶ and gets the list of email attachments. This transformer is then applied to the pop3 inbound endpoint defined at ❷. Then we define a list list-message-splitter-router on ❸ 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 on ❹. ❺ defines a simple groovy expression which gets the inputStream of the attachment to write the file.

Here is the flow-based 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:pop3="http://www.mulesoft.org/schema/mule/pop3"       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-3.0.xsd       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.2/mule.xsd       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.2/mule-file.xsd       http://www.mulesoft.org/schema/mule/pop3 http://www.mulesoft.org/schema/mule/pop3/3.2/mule-pop3.xsd       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/3.2/mule-email.xsd       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.2/mule-vm.xsd">    <pop3:connector name="pop3Connector"  />    <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">        <pop3:inbound-endpoint user="bob" password="password" host="mailServer"                                port="110" transformer-refs="returnAttachments"/> ❷        <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>

Here is the secure version of the same configuration:

<?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:pop3s="http://www.mulesoft.org/schema/mule/pop3s"       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-3.0.xsd       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.2/mule.xsd       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.2/mule-file.xsd       http://www.mulesoft.org/schema/mule/pop3s http://www.mulesoft.org/schema/mule/pop3s/3.2/mule-pop3s.xsd       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/3.2/mule-email.xsd       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.1/mule-vm.xsd">    <pop3s:connector name="pop3sConnector"> ❶        <pop3s:tls-client path="clientKeystore" storePassword="mulepassword" />         <pop3s:tls-trust-store path="greenmail-truststore" storePassword="password" />    </pop3s:connector>    <expression-transformer name="returnAttachments">        <return-argument evaluator="attachments-list" expression="*" optional="false"/>  ❷    </expression-transformer>    <file:connector name="fileName">        <file:expression-filename-parser/>    </file:connector>        <model name="test">        <service name="incoming-orders">            <inbound>                <pop3s:inbound-endpoint user="bob" password="password" host="mailServer"                       port="110" transformer-refs="returnAttachments"/> ❸            </inbound>            <outbound>                <list-message-splitter-router> ❹                    <file:outbound-endpoint path="./received" outputPattern="#[function:datestamp].dat"> ❺                        <expression-transformer>                            <return-argument expression="payload.inputStream" evaluator="groovy" /> ❻                        </expression-transformer>                    </file:outbound-endpoint>                                    </list-message-splitter-router>                            </outbound>        </service>    </model></mule>

The pop3s connector has tls client and server keystore information as defined on ❶. The built-in transformer is declared on ❷ and gets the list of email attachments. This transformer is then applied to the inbound endpoint on ❸. Then we define a list list-message-splitter-router on ❹ 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 on ❺. ❻ defines a simple groovy expression which gets the inputStream of the attachment to write the file.

Configuration Reference

Connectors

The POP3 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

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 will be resolved 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

tls-trust-store

Configures the trust store. The attributes are:

  • path: The location (which will be resolved 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:pop3="http://www.mulesoft.org/schema/mule/pop3"       xsi:schemaLocation="       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.2/mule.xsd       http://www.mulesoft.org/schema/mule/pop3 http://www.mulesoft.org/schema/mule/pop3/3.2/mule-pop3.xsd">     <pop3:connector name="pop3Connector" backupEnabled="true" backupFolder="newBackup" checkFrequency="1234"                      mailboxFolder="newMailbox" deleteReadMessages="false"/>...

Secure version:

<?xml version="1.0" encoding="UTF-8"?><mule xmlns="http://www.mulesoft.org/schema/mule/core/2.2"       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"       xmlns:spring="http://www.springframework.org/schema/beans"       xmlns:pop3s="http://www.mulesoft.org/schema/mule/pop3s"       xsi:schemaLocation="       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.2/mule.xsd       http://www.mulesoft.org/schema/mule/pop3s http://www.mulesoft.org/schema/mule/pop3s/3.2/mule-pop3s.xsd"><pop3s:connector name="pop3sConnector">  <pop3s:tls-client path="clientKeystore" storePassword="mulepassword" />   <pop3s:tls-trust-store path="greenmail-truststore" storePassword="password" /> </pop3s:connector><model name="test">  <service name="relay">    <inbound>      <pop3s:inbound-endpoint user="bob" password="password" host="localhost" port="65436" />     </inbound>...

Endpoints

POP3 and POP3S endpoints include details about connecting to a POP3 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 IP address of the POP3 server, such as www.mulesoft.com, localhost, or 127.0.0.1

  • port: the port number of the POP3 server. If not set for the POP3S connector, the default port is 995.

For example:

<pop3:inbound-endpoint user="bob" password="foo" host="pop.gmail.com" checkFrequency="3000" />

Or if using a POP3S connector:

<pop3s:inbound-endpoint user="bob" password="foo" host="pop.gmail.com" checkFrequency="3000" />

You can also define the endpoints using a URI syntax:

<inbound-endpoint address="pop3://bob:foo@pop.gmail.com:995"/><inbound-endpoint address="pop3s://bob:foo@pop.gmail.com:995"/>

This logs into the bob mailbox on pop.gmail.com using password foo (using the default port 995 for the POP3S endpoint).

xslt: Read http://www.mulesoft.org/xslt/mule/schemadoc/3.1/individual-transport-or-module-wiki.xsl error because of: java.io.IOException: Server returned HTTP response code: 401 for URL: http://svn.codehaus.org/mule/branches/mule-3.1.x/tools/schemadocs/src/main/resources/xslt//individual-transport-or-module-wiki.xsl

Here is how you define transformers in your Mule configuration file:

<email:bytes-to-mime-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" xsi:type=""/><email:email-to-string-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" xsi:type=""/><email:mime-to-bytes-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" xsi:type=""/><email:object-to-mime-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" useInboundAttachments="true" useOutboundAttachments="true"/>{Note}Need to explain attributes somewhere; can we pull them in from xsd?{Note}<email:string-to-email-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" xsi:type=""/>

Each transformer supports all the common transformer attributes and properties:

xslt: Read http://www.mulesource.org/xslt/mule/schemadoc/3.0/single-element-wiki.xsl error because of: java.io.IOException: Server returned HTTP response code: 401 for URL: http://svn.codehaus.org/mule/branches/mule-3.1.x/tools/schemadocs/src/main/resources/xslt//single-element-wiki.xsl

The object-to-mime-transformer has the following attributes:

Attribute Description Default Value

useInboundAttachments

Whether to transform inbound attachment in the input message into MIME parts.

true

useOutboundAttachments

Whether to transform outbound attachment in the input message into MIME parts.

true

To use these transformers, make sure you include the 'email' namespace in your mule configuration.

Filters

Filters can be set on an endpoint to filter out any unwanted messages. The Email transport provides a couple of filters that can either be used directly or extended to implement custom filtering rules.

Filter Description

org.mule.providers.email.filters.AbstractMailFilter

A base filter implementation that must be extended by any other mail filter.

org.mule.providers.email.filters.MailSubjectRegExFilter

Applies a regular expression to a Mail Message subject.

This is how you define the MailSubjectRegExFilter in your Mule configuration:

<message-property-filter pattern="to=barney@mule.org"/>

The 'pattern' attribute is a regular expression pattern. This is defined as java.util.regex.Pattern.

Schema Reference

Java API Reference

The Javadoc for this transport can be found here.

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

The following known limitations affect email transports:

Escape Your Credentials

If you use a URI-style endpoint and you include the user name and password, escape any characters that are illegal for URIs. Only alphabet, numeric, "-", "_", "." and "+" are allowed. For example, if the user name is user@myco.com, you should enter it as user%40myco.com.