...
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.3. |
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.
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 |
Code Block |
---|
mvn archetype:create \
-DarchetypeGroupIdDartifactId=orgyour.apacheartifact.servicemix.toolingid \
-DarchetypeArtifactIdDversion=servicemix-mail-service-unit \
-DgroupId=com.mycompany.myproduct \
-DartifactId=mycomponent.artifact
|
...
Endpoints Configuration
Poller Endpoint (Consumer)
Code Block |
---|
lang | xml |
---|
title | Sender Polling (providerConsumer) endpointEndpoint |
---|
|
<mail:senderpoller service="test:myMailService"
endpoint="senderEndpointpollerEndpoint"
sendertargetService="no-reply@servicemix.org"test:myMailProcessor"
receiverperiod="testreceiver@targethost.com10000"
connection="smtpimap://user@testserver:143/lhein@testserverINBOX?password=myPass" />
|
Code Block |
---|
lang | xml |
---|
title | Polling (consumer) endpoint |
---|
|
<mail:poller service="test:myMailService"
endpointdeleteProcessedMessages="pollerEndpointfalse"
targetServiceprocessOnlyUnseenMessages="test:myMailProcessortrue"
period="10000"
connection="imap://lhein@testserver:143/INBOX?password=myPass"
deleteProcessedMessages="false"
processOnlyUnseenMessages="true" />
|
Consumer Endpoint (Polling)
Note |
---|
title | Message Exchange Pattern |
---|
|
The poller endpoint will only generate InOnly exchanges. |
The following table shows the additional configuration possibilities of the endpoint other than the configuration of the default PollingEndpoint class.
Note |
---|
title | Message Exchange Pattern |
---|
|
The poller endpoint will only generate InOnly exchanges. |
Info |
---|
title | Poller Endpoint Attributes |
---|
borderStyle | solidbgColor='lighblue' |
---|
|
|
Info |
---|
title | Poller endpoint attributes |
---|
borderStyle | solidbgColor='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 | forgetTopHeaders customTrustManagers | boolean | the POP3 TOP command will not be used to fetch message headers | false | disableTop | boolean | headers are retrieved as part of the POP3 RETR command and not TOP | false | string | sets | customTrustManagers | string | sets one or more custom trust managers for use with ssl | null | customProperties | java.util.Map | a map of custom properties for the connection | null |
|
Warning |
---|
|
The attributes "customProperties", "forgetTopHeaders" and "disableTop" are available in version 2008.02 and above only! |
...
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://lhein@imapserveruser@imapserver:143/INBOX?password=mypass
pop3://pop3server/INBOX?user=me@myhome.org;password=mypass
|
Info |
---|
title | Poller endpoint attributesURI Attributes |
---|
borderStyle | solidbgColor='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)
...
The following table shows the configuration possibilities of the endpoint.
info | title | Sender (provider) endpoint attributes |
---|
borderStyle | solidbgColor='lighblue' |
---|
|
|
<mail:sender service="test:myMailService"
endpoint="senderEndpoint"
sender="no-reply@servicemix.org"
receiver="testreceiver@targethost.com"
connection="smtp://lhein@testserver?password=myPass" />
|
Info |
---|
title | Sender Endpoint Attributes |
---|
borderStyle | solidbgColor='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 | 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 |
|
Warning |
---|
|
The attributes "customProperties" and "ignoreMessageProperties" are available in version 2008.02 and above only! |
The DefaultMailMarshaler 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 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
...
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 |
---|
title | Common 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! |
How to use customProperties
be used.
If this property is missing, then the pre-configured receiver will be used.
Warning |
---|
title | Common 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 |
---|
page | servicemix-mail cookbook |
---|
excerpt | true |
---|
|
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 |
---|
lang | xml |
---|
title | Polling 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)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 |
---|
lang | xml |
---|
title | Polling Sending endpoint with ignored TOP headers (same is also for sender)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:pollersender service="test:myMailService"
endpoint="pollerEndpointsenderEndpoint"
targetServicesender="test:myMailProcessorno-reply@servicemix.org"
periodreceiver="10000testreceiver@targethost.com"
connection="imapsmtp://lhein@testserver:143/INBOX?password=myPass"
deleteProcessedMessagesignoreMessageProperties="false#ignoreProps"
/>
processOnlyUnseenMessages="true" <util:list id="ignoreProps">
<value>org.apache.servicemix.mail.to</value>
<value>org.apache.servicemix.mail.cc</value>
customProperties="#customProps"/>
<util:map id="customProps"><value>org.apache.servicemix.mail.bcc</value>
<value>org.apache.servicemix.mail.from</value>
<entry key="mail.pop3.forgettopheaders" value="true" /><value>org.apache.servicemix.mail.replyto</value>
</util:map>list>
</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).
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 |
---|
lang | xml |
---|
title | Marshaler example |
---|
|
<mail:poller service="test:myMailService" |
Code Block |
---|
lang | xml |
---|
title | Sending 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"
receiverendpoint="testreceiver@targethost.comsenderEndpoint"
connectionsender="smtp://lhein@testserver?password=myPassno-reply@servicemix.org"
ignoreMessagePropertiesconnection="#ignorePropsimap://lhein@testserver:143?password=myPass" />
<util:list<property idname="ignorePropsmarshaler">
<value>org.apache.servicemix.mail.to</value>
<value>org.apache.servicemix.mail.cc</value>
<bean <value>org.apache.servicemix.mail.bcc</value>class="com.mycompany.MyMailMarshaler" />
<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
...
</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 |
---|
title | Special message properties |
---|
borderStyle | solidbgColor='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 |
|
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 |
---|
lang | xml |
---|
title | Marshaler 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 |
---|
title | Special message properties |
---|
borderStyle | solidbgColor='lighblue' |
---|
|
Constant | Value | Description |
---|
MSG_TAG_TO | org.apache.servicemix.mail.to text | Contains the plain text content of the mail body if existing The address(es) the mail was or will be sent to. | MSG_TAG_CC HTML | org.apache.servicemix.mail.cc html | Contains the html content of the mail body if existing. (or put the HTML as the content of the NMsg) The addess(es) the mail was or will be sent to as copy. | MSG_TAG_BCC USER | org.apache.servicemix.mail.bcc username | Contains the user name to use for authentication to outgoing mail server The addess(es) the mail will be sent to as blind copy. | MSG_TAG_FROM PASSWORD | org.apache.servicemix.mail.from password | The addess the mail was received from or will be used as sender Contains the user password to use for authentication to outgoing mail server. | MSG_TAG_TEXT HOST | org.apache.servicemix.mail.text host | Contains the plain text content host name of the mail body if existingserver to use for outgoing mail. | MSG_TAG_HTML PROTOCOL | org.apache.servicemix.mail.html protocol | Contains the html content of the mail body if existingprotocol to use for the outgoing mail. | MSG_TAG_SUBJECT PORT | org.apache.servicemix.mail.subject port | The subject of the received mail or Contains the port number to use for the outgoing 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_ALTERNATIVE_CONTENT0..n | org.apache.servicemix.mail.alternativecontent | Contains the alternative content of the mail bodyserver. |
|
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.
...