SMTP Transport Reference

Introduction

The SMTP transport can be used for sending messages over SMTP using the javax.mail API. The implementation supports CC/BCC/ReplyTo addresses, attachments and custom Header properties. It also provides support for javax.mail.Message transformation. The SMTPS connector enables SMTP over SSL using the javax.mail APIs. It supports all the elements and attributes of the SMTP transport, plus some required properties for setting up the client key store and the trust store for the SSL connection.

TLS/SSL connections are made on behalf of an entity, which can be anonymous or identified by a certificate. The key store provides the certificates and associated private keys necessary for identifying the entity making the connection. Additionally, connections are made to trusted systems. The public certificates of trusted systems are stored in a trust store, which is used to verify that the connection made to a remote system matches the expected identity.

Transport Info

xslt: Page not found: Transport Feature Matrix in space MULECDEV

Unable to render {include} Couldn’t find a space with key: MULECDEV

Namespace and Syntax

XML namespace:

xmlns:smtp="http://www.mulesoft.org/schema/mule/smtp"
xmlns:smtps="http://www.mulesoft.org/schema/mule/smtps"

XML Schema location:

http://www.mulesoft.org/schema/mule/smtp http://www.mulesoft.org/schema/mule/smtp/3.1/mule-smtp.xsd
http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/3.1/mule-smtps.xsd

Connector syntax:

<smtp:connector name="smtpConnector" bccAddresses="abc@example.com" ccAddresses="bcd@example.com" contentType="foo/bar"
fromAddress="cde@example.com" replyToAddresses="def@example.com"
subject="subject">
  <smtp:header key="foo" value="bar" />
  <smtp:header key="baz" value="boz" />
</smtp:connector>

<smtps:connector name="smtpsConnector" bccAddresses="abc@example.com" ccAddresses="bcd@example.com" contentType="foo/bar"
fromAddress="cde@example.com" replyToAddresses="def@example.com"
subject="subject">
  <smtps:header key="foo" value="bar" />
  <smtps:header key="baz" value="boz" />
  <smtps:tls-client path="clientKeystore" storePassword="mulepassword" />
  <smtps:tls-trust-store path="greenmail-truststore" storePassword="password" />
</smtps:connector>

<smtp:gmail-connector name="smtpGmailConnector"  bccAddresses="abc@example.com" ccAddresses="bcd@example.com" contentType="foo/bar"
fromAddress="cde@example.com" replyToAddresses="def@example.com"
subject="subject">
  <smtp:header key="foo" value="bar" />
  <smtp:header key="baz" value="boz" />
</smtp:gmail-connector>

Endpoint syntax:
You can define your endpoints 2 different ways:

Prefixed endpoint:

<smtp:outbound-endpoint host="localhost" port="65437" from="steve@mycompany.com"
                            to="bob@example.com" subject="Please verify your account details"/>
<smtps:outbound-endpoint host="localhost" port="65437" from="steve@mycompany.com"
                            to="bob@example.com" subject="Please verify your account details"/>

Non-prefixed URI:

smtp://muletestbox:123456@smtp.mail.yahoo.co.uk?address=dave@mycompany.com
smtps://muletestbox:123456@smtp.mail.yahoo.co.uk?address=dave@mycompany.com

See the sections below for more information.

Features

Simple to configure email access on outbound endpoints
Easy to configure TLS security

Usage

If you want to include the SMTP email transport in your configuration, these are the namespaces you need to define:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:smtp="http://www.mulesoft.org/schema/mule/smtp"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.1/mule.xsd
       http://www.mulesoft.org/schema/mule/smtp http://www.mulesoft.org/schema/mule/smtp/3.1/mule-smtp.xsd">
...

Secure version:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:smtps="http://www.mulesoft.org/schema/mule/smtps"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.1/mule.xsd
       http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/3.1/mule-smtps.xsd">

Then you need to configure your connector and endpoints as described below.

Configuration Example

Say your CFO wants an email notification of all processed orders. The following configuration will pick up any files in the 'processed' directory, convert them to a string and send it as the email body to the CFO.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:smtps="http://www.mulesoft.org/schema/mule/smtps"
       xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
       xmlns:file="http://www.mulesoft.org/schema/mule/file"
       xmlns:email="http://www.mulesoft.org/schema/mule/email"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.1/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.1/mule-file.xsd
       http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/3.1/mule-smtps.xsd
       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/3.1/mule-email.xsd
       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.1/mule-vm.xsd">

    <smtp:connector name="smtpConnector"  />

    <flow name="processed-orders">
        <file:inbound-endpoint path="/tmp/processed"> ❶
            <file:file-to-string-transformer/> ❷
        </file:inbound-endpoint>
        <smtps:outbound-endpoint host="smtpsServer" port="25" from="bob" subject="processed order" to="cfo@example.com"> ❸
            <email:string-to-email-transformer/> ❹
        </smtps:outbound-endpoint>
    </flow>
</mule>

This configuration defines a inbound file endpoint which looks in the '/tmp/processed' directory ❶ and converts any files found to a string ❷. An outbound smtp server is defined on ❸. A string-to-email-transformer ❹ will convert the string to email format before the email is sent.

Secure version:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:smtps="http://www.mulesoft.org/schema/mule/smtps"
       xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
       xmlns:file="http://www.mulesoft.org/schema/mule/file"
       xmlns:email="http://www.mulesoft.org/schema/mule/email"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.1/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.1/mule-file.xsd
       http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/3.1/mule-smtps.xsd
       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/3.1/mule-email.xsd
       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.1/mule-vm.xsd">

    <smtps:connector name="smtpsConnector"> ❶
        <smtps:tls-client path="clientKeystore" storePassword="mulepassword" />
        <smtps:tls-trust-store path="greenmail-truststore" storePassword="password" />
    </smtps:connector>

    <flow name="processed-orders">
        <file:inbound-endpoint path="/tmp/processed"> ❷
            <file:file-to-string-transformer/> ❸
        </file:inbound-endpoint>
        <smtps:outbound-endpoint host="smtpsServer" port="25" from="bob" subject="processed order" to="cfo@example.com"> ❹
            <email:string-to-email-transformer/> ❺
        </smtps:outbound-endpoint>
    </flow>
</mule>

The smtps connector has a TLS client and server keystore information as defined on ❶. An inbound file endpoint looks in the '/tmp/processed' directory ❷ and converts any files found to a string ❸. An outbound smtp server is defined on ❹. A string-to-email-transformer ❺ will convert the string to email format before the email is sent.

Configuration Reference

Connectors

The SMTP connector supports all the common connector attributes and properties and the following optional elements and attributes:

Attribute	Description	Required
bccAddresses	Comma separated list of addresses for blind copies.	False
ccAddresses	Comma separated list of addresses for copies.	False
contentType	Mime type for the outgoing message.	False
fromAddress	The from address for the outgoing message.	False
replyToAddresses	The reply-to address for the outgoing message.	False
subject	The default subject for the outgoing message if none is set in the message.	False

Attribute

Description

Default

Required

bccAddresses

Comma separated list of addresses for blind copies.

False

ccAddresses

Comma separated list of addresses for copies.

False

contentType

Mime type for the outgoing message.

False

fromAddress

The from address for the outgoing message.

False

replyToAddresses

The reply-to address for the outgoing message.

False

subject

The default subject for the outgoing message if none is set in the message.

False

Element	Description
header	Additional header name and value, added to the message.

Element

Description

header

Additional header name and value, added to the message.

For the secure version, the following elements are also required:

Element	Description
tls-client	Configures the client key store with the following attributes: path: The location (which will be resolved relative to the current classpath and file system, if possible) of the keystore that contains public certificates and private keys for identification storePassword: The password used to protect the keystore class: The type of keystore used (a Java class name)
tls-trust-store	Configures the trust store. The attributes are: path: The location (which will be resolved relative to the current classpath and file system, if possible) of the trust store that contains public certificates of trusted servers storePassword: The password used to protect the trust store

Element

Description

tls-client

Configures the client key store with the following attributes:

path: The location (which will be resolved relative to the current classpath and file system, if possible) of the keystore that contains public certificates and private keys for identification
storePassword: The password used to protect the keystore
class: The type of keystore used (a Java class name)

tls-trust-store

Configures the trust store. The attributes are:

path: The location (which will be resolved relative to the current classpath and file system, if possible) of the trust store that contains public certificates of trusted servers
storePassword: The password used to protect the trust store

For example:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:smtp="http://www.mulesoft.org/schema/mule/smtp"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.0/mule.xsd
       http://www.mulesoft.org/schema/mule/smtp http://www.mulesoft.org/schema/mule/smtp/3.0/mule-smtp.xsd">
...
<smtp:connector name="smtpConnector" bccAddresses="abc@example.com" ccAddresses="bcd@example.com" contentType="foo/bar"
fromAddress="cde@example.com" replyToAddresses="def@example.com"
subject="subject">
  <smtp:header key="foo" value="bar" />
  <smtp:header key="baz" value="boz" />
</smtp:connector>

Secure version:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:smtps="http://www.mulesoft.org/schema/mule/smtps"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.0/mule.xsd
       http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/3.0/mule-smtps.xsd">

<smtps:connector name="smtpsConnector">
  <smtps:tls-client path="clientKeystore" storePassword="mulepassword" />
  <smtps:tls-trust-store path="greenmail-truststore" storePassword="password" />
</smtps:connector>
<model name="test">
  <service name="relay">
    <inbound>
      <vm:inbound-endpoint path="send" />
  </inbound>
  <outbound>
    <pass-through-router>
      <smtps:outbound-endpoint host="localhost" port="65439" to="bob@example.com" />
    </pass-through-router>
  </outbound>
...

The gmail-connector connector supports all of the above.
For example:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:smtp="http://www.mulesoft.org/schema/mule/smtp"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.0/mule.xsd
       http://www.mulesoft.org/schema/mule/smtp http://www.mulesoft.org/schema/mule/smtp/3.0/mule-smtp.xsd">
...
<smtp:gmail-connector name="smtpGmailConnector"  bccAddresses="abc@example.com" ccAddresses="bcd@example.com" contentType="foo/bar"
fromAddress="cde@example.com" replyToAddresses="def@example.com"
subject="subject">
  <smtp:header key="foo" value="bar" />
  <smtp:header key="baz" value="boz" />
</smtp:gmail-connector>

Endpoints

SMTP endpoints describe details about the SMTP server and the recipients of messages sent from the SMTP endpoint. You configure the endpoints just as you would with any other transport, with the following additional attributes:

Attribute	Description
user	The user name of the mailbox owner
password	The password of the user
host	The IP address of the SMTP server, such as www.mulesoft.com, localhost, or 127.0.0.1
port	The port number of the SMTP server
to	The destination for the email
from	The address of the sender of the email
subject	The email subject
cc	A comma-separated list of email addresses to copy on this email
bcc	A comma-separated list of email addresses to blind-copy on this email
replyTo	The address used by default if someone replies to the email

Attribute

Description

user

The user name of the mailbox owner

password

The password of the user

host

The IP address of the SMTP server, such as www.mulesoft.com, localhost, or 127.0.0.1

port

The port number of the SMTP server

The destination for the email

from

The address of the sender of the email

subject

The email subject

A comma-separated list of email addresses to copy on this email

bcc

A comma-separated list of email addresses to blind-copy on this email

replyTo

The address used by default if someone replies to the email

For example:

<outbound>
  <pass-through-router>
    <smtp:outbound-endpoint host="localhost" port="65437" from="steve@mycompany.com"
                            to="bob@example.com" subject="Please verify your account details"/>
  </pass-through-router>
</outbound>

Secure version:

<outbound>
  <pass-through-router>
    <smtps:outbound-endpoint host="localhost" port="65437" from="steve@mycompany.com"
                            to="bob@example.com" subject="Please verify your account details"/>
  </pass-through-router>
</outbound>

You can also define the endpoints using a URI syntax:

<outbound-endpoint address="smtp://muletestbox:123456@smtp.mail.yahoo.co.uk?address=dave@mycompany.com"/>
<outbound-endpoint address="smtps://muletestbox:123456@smtp.mail.yahoo.co.uk?address=dave@mycompany.com"/>

This will send mail using smtp.mail.yahoo.co.uk (using the default SMTP port) to the address dave@mycompany.com. The SMTP request is authenticated using the username muletestbox and the password 123456.

xslt: Read http://www.mulesoft.org/xslt/mule/schemadoc/3.1/individual-transport-or-module-wiki.xsl error because of: java.io.IOException: Server returned HTTP response code: 401 for URL: http://svn.codehaus.org/mule/branches/mule-3.1.x/tools/schemadocs/src/main/resources/xslt//individual-transport-or-module-wiki.xsl

Here is how you define transformers in your Mule configuration file:

<email:bytes-to-mime-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" xsi:type=""/>
<email:email-to-string-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" xsi:type=""/>
<email:mime-to-bytes-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" xsi:type=""/>
<email:object-to-mime-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass=""
useInboundAttachments="true" useOutboundAttachments="true"/>
{Note}Need to explain attributes somewhere; can we pull them in from xsd?{Note}
<email:string-to-email-transformer encoding="" ignoreBadInput="" mimeType="" name="" returnClass="" xsi:type=""/>

Each transformer supports all the common transformer attributes and properties:

xslt: Read http://www.mulesource.org/xslt/mule/schemadoc/3.0/single-element-wiki.xsl error because of: java.io.IOException: Server returned HTTP response code: 401 for URL: http://svn.codehaus.org/mule/branches/mule-3.1.x/tools/schemadocs/src/main/resources/xslt//single-element-wiki.xsl

The object-to-mime-transformer has the following attributes:

Attribute	Description	Default Value
useInboundAttachments	Whether to transform inbound attachment in the input message into MIME parts.	true
useOutboundAttachments	Whether to transform outbound attachment in the input message into MIME parts.	true

Attribute

Description

Default Value

useInboundAttachments

Whether to transform inbound attachment in the input message into MIME parts.

true

useOutboundAttachments

Whether to transform outbound attachment in the input message into MIME parts.

true

To use these transformers, make sure you include the 'email' namespace in your mule configuration.

Filters

Filters can be set on an endpoint to filter out any unwanted messages. The Email transport provides a couple of filters that can either be used directly or extended to implement custom filtering rules.

Filter	Description
org.mule.providers.email.filters.AbstractMailFilter	A base filter implementation that must be extended by any other mail filter.
org.mule.providers.email.filters.MailSubjectRegExFilter	Applies a regular expression to a Mail Message subject.

Filter

Description

org.mule.providers.email.filters.AbstractMailFilter

A base filter implementation that must be extended by any other mail filter.

org.mule.providers.email.filters.MailSubjectRegExFilter

Applies a regular expression to a Mail Message subject.

This is how you define the MailSubjectRegExFilter in your Mule configuration:

<message-property-filter pattern="to=barney@mule.org"/>

The 'pattern' attribute is a regular expression pattern. This is defined as java.util.regex.Pattern.

Exchange patterns / features of the transport

(see [transport matrix])

Schema Reference

You can view the full schema for the SMTP email transport here. The secure version is Namespace overview.

Java API Reference

The Javadoc for this transport can be found here.

Maven module

The email transports are implemented by the mule-transport-email module. You can find the source for the email transport under transports/email.

If you are using Maven to build your application, use the following dependency snippet to include the email transport in your project:

<dependency>
  <groupId>org.mule.transports</groupId>
  <artifactId>mule-transport-email</artifactId>
</dependency>

Unable to render {include} Couldn’t find a space with key: MULE3INSTALL

Limitations

The following known limitations affect email transports:

So far, all configuration has been static, in that you define all the information in the configuration of the endpoint. However, you can set the connector properties to control the settings of the outgoing message. These properties will override the endpoint properties. If you always want to set the email address dynamically, you can leave out the to attribute (or the address parameter if you’re using URIs} on the SMTP endpoint.

Escape Your Credentials
If you use a URI-style endpoint and you include the user name and password, escape any characters that are illegal for URIs. Only alphabet, numeric, "-", "_", "." and "+" are allowed. For example, if the user name is user@myco.com, you should enter it as user%40myco.com.

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

SMTP Transport Reference

Introduction

Transport Info

Namespace and Syntax

Features

Usage

Configuration Example

Configuration Reference

Connectors

Endpoints

Filters

Exchange patterns / features of the transport

Schema Reference

Java API Reference

Maven module

Limitations