...
The ServiceMix Mail component provides support for receiving and sending mails via the enterprise service bus.
Note | ||
---|---|---|
| ||
Note that this component is only available in releases > 3.2.1. |
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
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 \ -DgroupIdDarchetypeVersion=com2010.mycompany.myproduct01 \ -DartifactIdDgroupId=mycomponent.artifact |
Endpoints
Code Block | ||||
---|---|---|---|---|
| ||||
<mail:sender service="test:myMailService" your.group.id \ endpoint="senderEndpoint"-DartifactId=your.artifact.id \ sender="no-reply@servicemix.org" connection="smtp://lhein@testserver?password=myPass" /> -Dversion=your-version |
Endpoints Configuration
Poller Endpoint (Consumer)
Code Block | ||||
---|---|---|---|---|
| ||||
<mail:poller service="test:myMailService" endpoint="pollerEndpoint" targetService="test:myMailProcessor" period="10000" connection="imap://lhein@testserveruser@testserver:143/INBOX?password=myPass" deleteProcessedMessages="false" processOnlyUnseenMessages="true" /> |
...
Note | ||
---|---|---|
| ||
The poller endpoint will only generate InOnly exchanges. |
...
. |
Info | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||
|
...
|
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://lhein@imapserveruser@imapserver:143/INBOX?password=mypass pop3://pop3server/INBOX?user=me@myhome.org;password=mypass |
Info | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||
|
Provider Endpoint (Sending)
...
Sender Endpoint (Provider)
Code Block | ||||
---|---|---|---|---|
| ||||
<mail:sender service="test:myMailService"
endpoint="senderEndpoint"
sender="no-reply@servicemix.org"
receiver="testreceiver@targethost.com"
connection="smtp://lhein@testserver?password=myPass" />
|
Info | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||
|
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 | ||
---|---|---|
| ||
If you are just setting up a mail-bridge (means just a poller connected to a sender for mail forwarding) you will need |
Cookbook recipes
Children Display | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
| ||||
<?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
...
null
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 | ||||
---|---|---|---|---|
| ||||
<?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
...
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.AMailMarshalerSupportAbstractMailMarshaler 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:
...
There are some more important properties which affect the handling of the message / mail (constants are defined in AMailMarshalerSupportAbstractMailMarshaler):
Info | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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 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.
...
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