Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

ServiceMix Mail

The ServiceMix Mail component provides support for receiving and sending mails via the enterprise service bus.

Maven Archetype

You can use Maven servicemix-mail-service-unit archetype to create a service unit:

Code Block
mvn archetype:create \
    -DarchetypeGroupId=org.apache.servicemix.tooling \
    -DarchetypeArtifactId=servicemix-mail-service-unit \
    -DarchetypeVersion=2010.01 \
    -DgroupId=your.group.id \
    -DartifactId=your.artifact.id \
    -Dversion=your-version

Endpoints Configuration

Poller Endpoint (Consumer)

Code Block
langxml
titlePolling (Consumer) Endpoint
<mail:poller service="test:myMailService"
             endpoint="pollerEndpoint"
             targetService="test:myMailProcessor"
             period="10000"
             connection="imap://user@testserver:143/INBOX?password=myPass"
             deleteProcessedMessages="false"
             processOnlyUnseenMessages="true" />
Note
titleMessage Exchange Pattern

The poller endpoint will only generate InOnly exchanges.

Info
titlePoller Endpoint Attributes
borderStylesolidbgColor='lighblue'

Name

Type

Description

Default

connection

string

sets the connection information

null (must be spec'd)

deleteProcessedMessages

boolean

delete mail from server when it is processed

false

processOnlyUnseenMessages

boolean

process only mails which are new (unseen)

true

marshaler

class

org.apache.servicemix.mail.marshaler.AbstractMailMarshaler

DefaultMailMarshaler

maxFetchSize

int

sets max amount of mails to fetch, -1 means no limit

-1

debugMode

boolean

sets the debug mode for the javamail api

false

customTrustManagers

string

sets one or more custom trust managers for use with ssl

null

storage

class

sets the storage to use for remembering the seen messages when using pop protocol (org.apache.servicemix.store.Store)

null

customProperties

java.util.Map

a map of custom properties for the connection

null

The DefaultMailMarshaler (used if no other is set) will convert in the following way:

  • Headers of the mail are copied 1:1 into the message properties (and concatenated if needed)
  • if the mail has only plain text, the content will be put to property MSG_TAG_TEXT and to the message content
  • if the mail has only html, the content will be put to property MSG_TAG_HTML and to the message content
  • if the mail has both plain text and html, then both will be put to the right property and the content of the message will be the plain text
  • attachments are copied 1:1 from mail to message

The connection URI

The connection uri has to be specified in the following way:

No Format
 
Template: <protocol>://<user>@<host>[:<port>][/<folder>]?password=<password>
  OR  
Template: <protocol>://<host>[:<port>][/<folder>]?user=<user>;password=<password>


Example: 
   imap://user@imapserver:143/INBOX?password=mypass
   pop3://pop3server/INBOX?user=me@myhome.org;password=mypass

Info
titleURI Attributes
borderStylesolidbgColor='lighblue'

Name

Description

protocol

the protocol to use (example: pop3 or imap)

user

the user name used to log into an account

host

the name or ip address of the mail server

port

the port number to use (optional)

folder

the folder to poll from (optional)

password

the password for the login

 
 

Sender Endpoint (Provider)

Code Block
langxml
titleSender (provider) endpoint
<mail:sender service="test:myMailService" 
             endpoint="senderEndpoint"
             sender="no-reply@servicemix.org"
             receiver="testreceiver@targethost.com"
             connection="smtp://lhein@testserver?password=myPass" /> 
Info
titleSender Endpoint Attributes
borderStylesolidbgColor='lighblue'

Name

Type

Description

Default

connection

string

sets the connection information

null (must be spec'd)

sender

string

defines the sender address of the mail

no-reply@localhost

receiver

string

defines the receiver address of the mail

null

marshaler

class

org.apache.servicemix.mail.marshaler.AbstractMailMarshaler

DefaultMailMarshaler

debugMode

boolean

sets the debug mode for the javamail api

false

ignoreMessageProperties

java.util.List

a list of properties of the IN message which will be ignored

false

customProperties

java.util.Map

a map of custom properties for the connection

null

customTrustManagers

string

sets one or more custom trust managers for use with ssl

null

The DefaultMailMarshaler (used if no other is set) will convert in the following way:

  • all properties of the message MSG_TAG_xxxx will be evaluated and used for preparing the mail
  • if MSG_TAG_TEXT and/or MSG_TAG_HTML are specified, then the content will be used for preparing the mail content
  • if there are no MSG_TAG_TEXT and MSG_TAG_HTML properties, the content of the message will be parsed and converted to the mail body as plain text or html content
  • attachments are copied 1:1 from mail to message

How is the sender determined?

If there is a preconfigured sender for the endpoint from xbean.xml, it will be used
else if MSG_TAG_FROM is defined in the message properties, then it will be used
else the method getDefaultSender() of the marshaler is invoked

How is the receiver determined?

If there is a TO property in the normalized message, then it will be used.
If this property is missing, then the pre-configured receiver will be used.

Warning
titleCommon pitfall regarding the receiver

If you are just setting up a mail-bridge (means just a poller connected to a sender for mail forwarding) you will need
to provide a sender property ignoreMessageProperties as List, containing a list of to ignore message properties.
Inside you should at least define the org.apache.servicemix.mail.to value, otherwise the receiver will be the receiver of the original mail.
That would just forward the original mail to the account you are polling from generating a nice mail loop. Be warned!

Cookbook recipes

Children Display
pageservicemix-mail cookbook
excerpttrue

How to use customProperties

Via this attribute you can provide a map of properties which will be applied to the connection properties. Doing so enables you to
completely configure the connection properties.

Code Block
langxml
titlePolling endpoint with ignored TOP headers (same is also for sender)
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns:mail="http://servicemix.apache.org/mail/1.0"
       xmlns:test="http://www.servicemix.org/example"
       xmlns:util="http://www.springframework.org/schema/util">

<mail:poller service="test:myMailService"
             endpoint="pollerEndpoint"
             targetService="test:myMailProcessor"
             period="10000"
             connection="imap://lhein@testserver:143/INBOX?password=myPass"
             deleteProcessedMessages="false"
             processOnlyUnseenMessages="true" 
             customProperties="#customProps"/>

  <util:map id="customProps">
    <entry key="mail.pop3.forgettopheaders" value="true" />
  </util:map>

</beans>

For a list of properties used by the SUN implementation influencing the connection have a look at the Mail API documentation:
http://java.sun.com/products/javamail/javadocs/overview-summary.html
Have especially a look at the protocol specific package summaries.

How to use ignoreMessageProperties

Via this property you can provide a list of properties of the normalized in message which will be set to null
before marshaling it. This will enable you for example to have a simple email forward bridge with a poller and a
sender which will forward the received message to a new email address. Without skipping at least the TO address property
the mail would be sent again to the account you are polling from (see how the receiver is determined).

Code Block
langxml
titleSending endpoint with skipping the adress fields
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns:mail="http://servicemix.apache.org/mail/1.0"
       xmlns:test="http://www.servicemix.org/example"
       xmlns:util="http://www.springframework.org/schema/util">

  <mail:sender service="test:myMailService" 
             endpoint="senderEndpoint"
             sender="no-reply@servicemix.org"
             receiver="testreceiver@targethost.com"
             connection="smtp://lhein@testserver?password=myPass" 
             ignoreMessageProperties="#ignoreProps" /> 

  <util:list id="ignoreProps">
    <value>org.apache.servicemix.mail.to</value>
    <value>org.apache.servicemix.mail.cc</value>
    <value>org.apache.servicemix.mail.bcc</value>
    <value>org.apache.servicemix.mail.from</value>
    <value>org.apache.servicemix.mail.replyto</value>
  </util:list>

</beans>

For all xbean file endpoint configuration take a look at Xml schemas

Marshalers

You can write your own marshalers for conversion between mail and normalized message and vice versa.
To do this you simply need to subclass the org.apache.servicemix.mail.marshaler.AbstractMailMarshaler or even the
DefaultMailMarshaler if you don't want to start from scratch.

Subclassing the AbstractMailMarshaler

For providing your own marshaler you only need to implement two methods:

convertMailToJBI(...)

This method is responsible for translating a received mail message into a jbi compliant normalized message ready to be sent to the bus.

convertJBIToMail(...)

This method is responsible for translating a received normalized message into a mail message ready to be sent to the mail server.

After finishing your marshaler you can simply configure your endpoints to use it:

Code Block
langxml
titleMarshaler example
<mail:poller service="test:myMailService" 
             endpoint="senderEndpoint"
             sender="no-reply@servicemix.org" 
             connection="imap://lhein@testserver:143?password=myPass" > 

    <property name="marshaler">
        <bean class="com.mycompany.MyMailMarshaler" />
    </property>

</mail:poller>

Mapping of headers and properties

All mail headers are mapped (nearly) one-to-one into message properties. If there are multiple mail headers with the same name, then the values will be concatenated and separated by the semicolon (;-character).

There are some more important properties which affect the handling of the message / mail (constants are defined in AbstractMailMarshaler):

Info
titleSpecial message properties
borderStylesolidbgColor='lighblue'

Constant

String-Value

Description

MSG_TAG_TO

org.apache.servicemix.mail.to

The address(es) the mail was or will be sent to.

MSG_TAG_CC

org.apache.servicemix.mail.cc

The addess(es) the mail was or will be sent to as copy.

MSG_TAG_BCC

org.apache.servicemix.mail.bcc

The addess(es) the mail will be sent to as blind copy.

MSG_TAG_FROM

org.apache.servicemix.mail.from

The addess the mail was received from or will be used as sender.

MSG_TAG_SUBJECT

org.apache.servicemix.mail.subject

The subject of the received mail or for the mail to be sent.

MSG_TAG_REPLYTO

org.apache.servicemix.mail.replyto

The address to be used as reply-to.

MSG_TAG_SENTDATE

org.apache.servicemix.mail.sentdate

The date the email was sent.

MSG_TAG_MAIL_CONTENT_TYPE

org.apache.servicemix.mail.type

The mail mime type.

MSG_TAG_MAIL_CHARSET

org.apache.servicemix.mail.charset

The charset to use.

MSG_TAG_MAIL_USE_INLINE_ATTACHMENTS

org.apache.servicemix.mail.attachments.inline

Should attachments be set as inline

MSG_TAG_TEXT

org.apache.servicemix.mail.text

Contains the plain text content of the mail body if existing.

MSG_TAG_HTML

org.apache.servicemix.mail.html

Contains the html content of the mail body if existing. (or put the HTML as the content of the NMsg)

MSG_TAG_USER

org.apache.servicemix.mail.username

Contains the user name to use for authentication to outgoing mail server.

MSG_TAG_PASSWORD

org.apache.servicemix.mail.password

Contains the user password to use for authentication to outgoing mail server.

MSG_TAG_HOST

org.apache.servicemix.mail.host

Contains the host name of the mail server to use for outgoing mail.

MSG_TAG_PROTOCOL

org.apache.servicemix.mail.protocol

Contains the protocol to use for the outgoing mail.

MSG_TAG_PORT

org.apache.servicemix.mail.port

Contains the port number to use for the outgoing mail server.

Mail Content Types

These are the available content types:

  • text/plain
  • text/html
  • text/xml
  • multipart/*
  • multipart/mixed
  • multipart/alternative
  • unknown

On incoming mails you may evaluate this property on the normalized message to find out which kind of mime type the mail had. On outgoing mails you can control the mime type to use for the mail. If you don't set the content type it will be auto-sensed by the marshaler.
 
 

IMAPS and POP3S

If you want to use secure protocols like IMAPS or POP3S you have several oportunities to do that.

The standard way

The standard way would be to just set the protocol in the connection uri to imaps instead of imap. (same for smtp and pop3)
Java will then try to verify the certificate of the mail server by following the chain of certificates signing the server's certificate back to one of these well known CA certificates specified in the default java keystore file. (see SSLNOTES.txt of JavaMail API for details)
If the certificate has no chain (is self signed) then this chain following is impossible. For this case you have to specify the key store to use via system properties:
java -Djavax.net.ssl.trustStore=$HOME/.keystore ...
To import keys to that store you may use the keytool command.

The alternative way

You have the possibility to write your own TrustManager and let the component use this custom trust manager. If you want no verification of the servers certificate at all then you can use the shipped DummyTrustManager.

Warning
titleSecurity Warning

Using the DummyTrustManager will provide you NO SECURITY AT ALL!

How to write a custom trust manager?

1. You need to subclass a trust manager which implements the TrustManager interface directly or indirectly. The constructor has to be parameterless.
2. You have to specify the attribute customTrustManagers in the endpoint configuration inside your xbean.xml file. The content will be the full name of the class including the package name (for example: customTrustManagers="com.mycompany.mypackage.MyTrustManager"). If you want to define more then one just use the semicolon ( ; ) to separate the class names.

Code Block
langxml
titleCustom Trust Manager Example
<mail:poller service="test:myMailService" 
             endpoint="pollEndpoint" 
             targetService="test:myMailProcessingService"
             period="10000"
             connection="imaps://lhein@imapserver/INBOX?password=mypass"
             deleteProcessedMessages="false"
             processOnlyUnseenMessages="true" 
             customTrustManagers="org.apache.servicemix.mail.security.DummyTrustManager" /> 

If you are not using a secure protocol the attribute customTrustManager will be ignored at all.

How to debug if I got problems connecting to the mail server?

There is a additional attribute you may specify in the endpoints configuration. This attribute is called debugMode and accepts the values "true" or "false". This will switch the JavaMail debug mode on or off providing useful details to you via console or servicemix.log file.

Using template engines

NOTHING DONE YET...FEEL FREE TO HELP US OUT HERE.....TODO

Velocity

NOTHING DONE YET...FEEL FREE TO HELP US OUT HERE.....TODO