ServiceMix Mail

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

Installation

Installing the servicemix-mail component can be done in several ways:

• drop the installer zip in an hotdeploy directory monitored by ServiceMix
• using ant tasks

Note that when using ant tasks, the component is not started, you will have to start it manually using ant tasks or a console.

Creation

You can use Maven to create a service unit.

mvn archetype:create \
    -DarchetypeGroupId=org.apache.servicemix.tooling \
    -DarchetypeArtifactId=servicemix-mail-service-unit \
    -DgroupId=com.mycompany.myproduct \
    -DartifactId=mycomponent.artifact

Endpoints

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

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

Consumer Endpoint (Polling)

The following table shows the additional configuration possibilities of the endpoint other than the configuration of the default PollingEndpoint class.

 
 
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:

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

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

Provider Endpoint (Sending)

The following table shows the configuration possibilities of the endpoint.

 
 
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.

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:

<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):

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.

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.

<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

TODO

Velocity

TODO