Introduction

The mail transport allows to send and receive messages using MIME compliant mail messages. The transport sender transmits outgoing messages using SMTP, while the transport listener connects to one or more mail accounts and periodically polls these accounts for new incoming messages. The implementation is based on JavaMail and therefore supports any mail store protocol for which a JavaMail provider is available.

Transport listener

Configuration

    <transportReceiver name="mailto" class="org.apache.axis2.transport.mail.MailTransportListener"/>

Endpoint configuration

Endpoints can be configured both at the transport level and at the service level. In order to receive messages using the mail transport, the listener or the service must be configured with a set of parameters to access the corresponding mailbox account. If messages from the mail account should be directly dispatched to a given service, than the parameters must be specified on that service. If on the other hand messages from that account can't be pre-dispatched to a specific service (e.g. because the account is used to receive responses to outgoing messages), then the parameters must be added to the transportReceiver element in axis2.xml.

All parameters starting with mail. are interpreted as JavaMail environment properties. The most relevant are mail.<protocol>.host and mail.<protocol>.user, where <protocol> is typically pop3 or imap. Assuming that Sun's JavaMail implementation is used, the complete list of supported properties for these two protocols can be found here and here.

In additional to the JavaMail environment properties, the following transport specific service parameters are used:

Parameter Required Description
transport.PollInterval No The poll interval in seconds.
transport.mail.Address Yes The address used to calculate the endpoint reference for the service. It is assumed that mails sent to this address will be delivered to the mailbox account configured for the service. Note that the transport has no means to validate this value and an incorrect address will not be detected.
mail.<protocol>.password Yes The password for the mailbox account.
transport.mail.Protocol Yes The mail store protocol to be used. The value must be protocol identifier recognized by JavaMail. Usual values are pop3 and imap. Note that the SSL variants of these two protocols are not considered as distinct protocols. Rather, SSL is configured using the appropriate JavaMail environment properties.
transport.mail.ContentType No This parameter allows to override the content type of incoming messages. This parameter is useful if the service can only receive messages of a single content type and the client is known to send incorrect content type information. If this parameter is set, the Content-Type MIME header in incoming messages is ignored.
transport.mail.ReplyAddress No The reply-to address to be used when no From or Reply-To header is present in the request message.
transport.mail.Folder No The folder to read messages from. Defaults to INBOX.
transport.mail.PreserveHeaders, transport.mail.RemoveHeaders No These two properties control which MIME headers of the received message will be stored in the TRANSPORT_HEADERS property of the message context. Both parameters expect a comma separated list of header names as value. transport.mail.PreserveHeaders specifies a whitelist of headers to retain, while transport.mail.RemoveHeaders specifies a blacklist of headers to remove. Note that the two parameters should not be used simultaneously.
transport.mail.ActionAfterProcess No Determines what the transport should do with the message after successful processing. Possible values are MOVE and DELETE. The default value is DELETE.
transport.mail.ActionAfterFailure No Determines what the transport should do with the message if processing fails. Possible values are MOVE and DELETE. The default value is DELETE. [FIXME: we should reconsider this; it is dangerous!]
transport.mail.MoveAfterProcess Conditional Specifies the destination folder if transport.mail.ActionAfterProcess is MOVE.
transport.mail.MoveAfterFailure Conditional Specifies the destination folder if transport.mail.ActionAfterFailure is MOVE.
transport.mail.MaxRetryCount No The number of connection attempts. When the maximum number of retries is exceeded, a new poll is scheduled after the normal poll interval. The default value is 0, i.e. connection failures are simply ignored.
transport.mail.ReconnectTimeout No The interval between two connection attempts if the first failed. The default value is 0, i.e. a new connection is attempted immediately. [FIXME: either it is not implemented as intended or the name of the property is misleading; it is not a timeout, but an interval]

Content extraction

Content is extracted from incoming mails using the following rules:

  1. If the content type of the message is not multipart/mixed, the message is extracted from the body of the message.
  2. If the content type of the message is multipart/mixed, the listener will attempt to find a MIME part with a content type different from text/plain and for which a message builder is registered. If a matching part is found, the message will be extracted from that part. Otherwise, the listener will extract the message from the last text/plain part if a message builder is registered for that content type. Finally, if no message builder is registered for any of the content types appearing in the multipart message, an error is triggered.

Note that these rules only apply if the content type has not been overridden using the transport.mail.ContentType property. If this property is set, the message will always be extracted from the body of the message and support for multipart/mixed is disabled.

In all cases the transport listener will use the corresponding message builder registered in the Axis configuration to build the SOAP infoset from the message.

The special rules for multipart/mixed are designed to enable the following use cases:

  • Allow humans to send messages to a Web service using a standard mail client. The user can do so by adding the message as attachment to the mail. Note that this only works if the mail client correctly sets the Content-Type header on the attachment. This works best for SOAP 1.1 messages: when attaching a file with suffix .xml, most mail clients will set the content type to text/xml, exactly as required for SOAP 1.1.
  • Allow clients to send a human readable message together with the actual message. This is useful if the message may be read by a human before being processed.

Note that these rules don't interfere with the support for SOAP with Attachments, because SwA uses multipart/related.

Transport sender

Configuration

    <transportSender name="mailto" class="org.apache.synapse.transport.mail.MailTransportSender">
        <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
        <parameter name="mail.smtp.port">587</parameter>
        <parameter name="mail.smtp.starttls.enable">true</parameter>
        <parameter name="mail.smtp.auth">true</parameter>
        <parameter name="mail.smtp.user">synapse.demo.0</parameter>
        <parameter name="mail.smtp.password">mailpassword</parameter>
        <parameter name="mail.smtp.from">synapse.demo.0@gmail.com</parameter>
    </transportSender>