15. Mail Support

15.1 Mail-Sending Channel Adapter

Spring Integration provides support for outbound email with the MailSendingMessageHandler. It delegates to a configured instance of Spring's JavaMailSender:

 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 a 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 also allows you to override corresponding MailMessage values. For example: If MailMessage.to is set to '[email protected]' and MailHeaders.TO Message header is provided it will take precedence and override the corresponding value in MailMessage

15.2 Mail-Receiving Channel Adapter

Spring Integration also provides support for inbound email with the MailReceivingMessageSource. It delegates to a configured instance of Spring Integration's own MailReceiver interface, and there are two implementations: Pop3MailReceiver and 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:pwd@localhost/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.

15.3 Mail Namespace Support

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"

To configure an outbound Channel Adapter, provide the channel to receive from, and the MailSender:

<mail:outbound-channel-adapter channel="outboundMail"

Alternatively, provide the host, username, and password:

<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"
      <int:poller max-messages-per-poll="1" fixed-rate="5000"/>

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"

... where javaMailProperties could be provided by creating and populating a regular java.utils.Properties object. For example via util namespace provided by Spring.

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

In both configurations channel and should-delete-messages are the REQUIRED     attributes. The important thing to understand is why should-delete-messages is required.     The issue is with the POP3 protocol, which does NOT have any knowledge of messages that were READ. It can only know what's been read      within a single session. This means that when your POP3 mail adapter is running, emails are successfully consumed as as they become available during each poll     and no single email message will be delivered more then once. However, as soon as you restart your adapter and begin a new session     all the email messages that might have been retrieved in the previous session will be retrieved again. That is the nature of POP3. Some might argue     that should-delete-messages should be TRUE by default. In other words, there are two valid and mutually exclusive use cases      which make it very hard to pick a single "best" default. You may want to configure your adapter as the only email receiver in which     case you want to be able to restart such adapter without fear that messages that were delivered before will not be redelivered again.      In this case setting should-delete-messages to TRUE would make most sense. However, you may have another use case where      you may want to have multiple adapters that simply monitor email servers and their content. In other words you just want to 'peek but not touch'.      Then setting should-delete-messages to FALSE would be much more appropriate. So since it is hard to choose what should be     the right default value for the should-delete-messages attribute, we simply made it a required attribute, to be set by the user. Leaving it up to the user also means, you will be less likely to end up with unintended behavior.
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.

<mail:header-enricher subject="Example Mail"
                     to="[email protected]"
                     cc="[email protected]"
                     bcc="[email protected]"
                     from="[email protected]"
                     reply-to="[email protected]"

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.