Spring Integration provides support for outbound email with the
MailSendingMessageHandler. It delegates to a configured instance of Spring's
JavaMailSender mailSender = context.getBean("mailSender", JavaMailSender.class); MailSendingMessageHandler mailSendingHandler = new MailSendingMessageHandler(mailSender);
MailSendingMessageHandler has various mapping strategies that use Spring's
MailMessage abstraction. If the received Message's payload is already
MailMessage instance, it will be sent directly.
Therefore, it is generally recommended to precede this
consumer with a Transformer for non-trivial MailMessage construction requirements. However, a few simple
Message mapping strategies are supported out-of-the-box. For example, if the message payload is a byte array,
then that will be mapped to an attachment. For simple text-based emails, you can provide a String-based
Message payload. In that case, a MailMessage will be created with that String as the text content. If you
are working with a Message payload type whose toString() method returns appropriate mail text content, then
consider adding Spring Integration's ObjectToStringTransformer prior to the outbound
Mail adapter (see the example within the section called “Configuring Transformer with XML” for more detail).
The outbound MailMessage may also be configured with certain values from the
MessageHeaders. If available, values will be mapped to the outbound mail's
properties, such as the recipients (TO, CC, and BCC), the from/reply-to, and the subject. The header names are
defined by the following constants:
MailHeaders.SUBJECT MailHeaders.TO MailHeaders.CC MailHeaders.BCC MailHeaders.FROM MailHeaders.REPLY_TO
Spring Integration also provides support for inbound email with the
MailReceivingMessageSource. It delegates to a configured instance of Spring
MailReceiver interface, and there are two implementations:
ImapMailReceiver. The easiest way to
instantiate either of these is by passing the 'uri' for a Mail store to the receiver's constructor. For example:
MailReceiver receiver = new Pop3MailReceiver("pop3://usr:[email protected]/INBOX");
Another option for receiving mail is the IMAP "idle" command (if supported by the mail server you are using).
Spring Integration provides the
ImapIdleChannelAdapter which is itself a Message-producing
endpoint. It delegates to an instance of the
ImapMailReceiver but enables asynchronous
reception of Mail Messages. There are examples in the next section of configuring both types of inbound Channel
Adapter with Spring Integration's namespace support in the 'mail' schema.
Spring Integration provides a namespace for mail-related configuration. To use it, configure the following schema locations.
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:int-mail="http://www.springframework.org/schema/integration/mail" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/integration/mail http://www.springframework.org/schema/integration/mail/spring-integration-mail.xsd">
To configure an outbound Channel Adapter, provide the channel to receive from, and the MailSender:
<int-mail:outbound-channel-adapter channel="outboundMail" mail-sender="mailSender"/>
Alternatively, provide the host, username, and password:
<int-mail:outbound-channel-adapter channel="outboundMail" host="somehost" username="someuser" password="somepassword"/>
|Keep in mind, as with any outbound Channel Adapter, if the referenced channel is a PollableChannel, a <poller> sub-element should be provided with either an interval-trigger or cron-trigger.|
To configure an Inbound Channel Adapter, you have the choice between polling or event-driven (assuming your mail server supports IMAP IDLE - if not, then polling is the only option). A polling Channel Adapter simply requires the store URI and the channel to send inbound Messages to. The URI may begin with "pop3" or "imap":
<int-mail:inbound-channel-adapter id="imapAdapter" store-uri="imaps://[username]:[password]@imap.gmail.com/INBOX" java-mail-properties="javaMailProperties" channel="recieveChannel" should-delete-messages="true" should-mark-messages-as-read="true" auto-startup="true"> <int:poller max-messages-per-poll="1" fixed-rate="5000"/> </int-mail:inbound-channel-adapter>
If you do have IMAP idle support, then you may want to configure the "imap-idle-channel-adapter" element instead. Since the "idle" command enables event-driven notifications, no poller is necessary for this adapter. It will send a Message to the specified channel as soon as it receives the notification that new mail is available:
<int-mail:imap-idle-channel-adapter id="customAdapter" store-uri="imaps://[username]:[password]@imap.gmail.com/INBOX" channel="recieveChannel" auto-startup="true" should-delete-messages="false" should-mark-messages-as-read="true" java-mail-properties="javaMailProperties"/>
... where javaMailProperties could be provided by creating and populating
java.utils.Properties object. For example via util namespace
provided by Spring.
|If your username contains the '@' character use '%40' instead of '@' to avoid parsing errors from the underlying JavaMail API.|
<util:properties id="javaMailProperties"> <prop key="mail.imap.socketFactory.class">javax.net.ssl.SSLSocketFactory</prop> <prop key="mail.imap.socketFactory.fallback">false</prop> <prop key="mail.store.protocol">imaps</prop> <prop key="mail.debug">false</prop> </util:properties>
IMAP IDLE and lost connection
When using IMAP IDLE channel adapter there might be situations where connection to the server may be lost (e.g., network failure) and since Java Mail documentation explicitly states that the actual IMAP API is EXPERIMENTAL it is important to understand the differences in the API and how to deal with them when configuring IMAP IDLE adapters. Currently Spring Integration Mail adapters was tested with Java Mail 1.4.1 and Java Mail 1.4.3 and depending on which one is used special attention must be payed to some of the java mail properties that needs to be set with regard to auto-reconnect.
The following behavior was observed with GMAIL but should provide you with some tips on how to solve re-connect issue with other providers, however feedback is always welcome. Again, below notes are based on GMAIL.
With Java Mail 1.4.1 if
mail.imaps.timeout property is set for a relatively short period of time (e.g., ~ 5 min)
IMAPFolder.idle() will throw
FolderClosedException after this timeout.
However if this property is not set (should be indefinite) the behavior that was observed is that
method never returns nor it throws an exception. It will however reconnect automatically if connection was lost for a short
period of time (e.g., under 10 min), but if connection was lost for a long period of time (e.g., over 10 min), then
IMAPFolder.idle() will not throw
FolderClosedException nor it will re-establish connection
and will remain in the blocked state indefinitely, thus leaving you no possibility to reconnect without restarting the adapter.
So the only way to make re-connect to work with Java Mail 1.4.1 is to set
mail.imaps.timeout property explicitly
to some value, but it also means that such value shoudl be relatively short (under 10 min) and the connection should be
re-estabished relatively quickly. Again, it may be different with other providers.
With Java Mail 1.4.3 there was significant improvements to the API ensuring that there will always be a condition which
IMAPFolder.idle() method to return via
FolderClosedException or simply return, thus allowing us to proceed with auto-reconnect.
Currently auto-reconnect will run infinitely making attempts to reconnect every 10 sec.
In both configurations |
|When configuring a polling email adapter's should-mark-messages-as-read attribute, be aware of the protocol you are configuring to retrieve messages. For example POP3 does not support this flag which means setting it to either value will have no effect as messages will NOT be marked as read.|
When using the namespace support, a header-enricher Message Transformer is also available. This simplifies the application of the headers mentioned above to any Message prior to sending to the Mail-sending Channel Adapter.
<int-mail:header-enricher subject="Example Mail" to="[email protected]" cc="[email protected]" bcc="[email protected]" from="[email protected]" reply-to="[email protected]" overwrite="false"/>
Finally, the <imap-idle-channel-adapter/> also accepts the 'error-channel' attribute. If a downstream exception is thrown and an 'error-channel' is specified, a MessagingException message containing the failed message and original exception, will be sent to this channel. Otherwise, if the downstream channels are synchronous, any such exception will simply be logged as a warning by the channel adapter.
Very often you may encounter a requirement to filter incoming messages
(e.g., You want to only read emails that have 'Spring Integration' in the Subject line). This
could be easily accomplished by connecting Inbound Mail adapter with an expression-based Filter. Although it would work, there is a
downside to this approach. Since messages would be filtered after going through inbound mail adapter all such messages would be marked as read (SEEN) or
Un-read (depending on the value of
should-mark-messages-as-read attribute). However in reality what would be more useful is to mark messages
as SEEN only if they passed the filtering criteria. This is very similar to looking at your email client while scrolling through all the
messages in the preview pane, but only flagging messages as SEEN that were actually opened and read.
In Spring Integration 2.0.4 we've introduced
mail-filter-expression attribute on
imap-idle-channel-adapter. This attribute allows you to provide an expression which is a combination of SpEL and Regular Expression.
For example if you would like to read only emails that contain 'Spring Integration' in the Subject line, you would configure
like this this:
mail-filter-expression="subject matches '(?i).*Spring Integration.*"
javax.mail.internet.MimeMessage is the root context of SpEL Evaluation Context, you can filter on any value available
through MimeMessage including the actual body of the message. This one is particularly important since reading the body of the message would
typically result in such message to be marked as SEEN by default, but since we now setting PEAK flag of every incomming message to 'true', only
messages that were explicitly marked as SEEN will be seen as read.
So in the below example only messages that match the filter expression will be output by this adapter and only those messages will be marked as SEEN.
In this case based on the
mail-filter-expression only messages that contain 'Spring Integration' in the subject line will be
produced by this adapter.
<int-mail:imap-idle-channel-adapter id="customAdapter" store-uri="imaps://some_google_address:[email protected]/INBOX" channel="receiveChannel" should-mark-messages-as-read="true" java-mail-properties="javaMailProperties" mail-filter-expression="subject matches '(?i).*Spring Integration.*'"/>
Another reasonable question is what happens on the next poll, or idle event, or what happens when such adapter is restarted. Will there be a potential duplication of massages to be filtered? In other words if on the last retrieval where you had 5 new messages and only 1 passed the filter what would happen with the other 4. Would they go through the filtering logic again on the next poll or idle? After all they were not marked as SEEN. The actual answer is no. They would not be subject of duplicate processing due to another flag (RECENT) that is set by the Email server and is used by Spring Integration mail search filter. Folder implementations set this flag to indicate that this message is new to this folder, that is, it has arrived since the last time this folder was opened. In other while our adapter may peek at the email it also lets the email server know that such email was touched and therefore will be marked as RECENT by the email server.