Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.8)
  3. Reference
  4. Transports Reference

  5. SMTP Transport Reference

SMTP Transport Reference

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

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.

Namespace and Schema

SMTP XML Namespace and Schema Location:

xmlns:smtp="http://www.mulesoft.org/schema/mule/smtp"
http://www.mulesoft.org/schema/mule/smtp http://www.mulesoft.org/schema/mule/smtp/current/mule-smtp.xsd

SMTPS XML Namespace and Schema Location:

xmlns:smtps="http://www.mulesoft.org/schema/mule/smtps"
http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/current/mule-smtps.xsd

SMTP(S) Syntax Quick Reference

SMTP

<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

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

Gmail

<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>
        <smtp:outbound-endpoint connector-ref="Gmail"
			to="${email.to}" subject="test msg"
			address="smtps://${smtp.user}:${smtp.pass}@${smtp.host}"
			responseTimeout="10000" doc:name="Send notification email" ref="Gmail"/>/>

If after selecting Gmail in the Connector Configuration dropdown you see an error Attribute sets [address], [ref], [host] are mutually exclusive., check if ref="Gmail" or other ref attribute was placed inside the <smtp:outbound-endpoint>. Deleting that should allow you to run the application cleanly.

If any malformed endpoint error shows after deployment, check the URI address properties are correct.

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

  1. 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"/>

  2. 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 for the SMTP transport.

<?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-current.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/smtp http://www.mulesoft.org/schema/mule/smtp/current/mule-smtp.xsd">
...

For SMTPS, configure the XML like so:

<?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-current.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/current/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-current.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
       http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/current/mule-smtps.xsd
       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/current/mule-email.xsd
       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/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. The string-to-email-transformer will set the current string payload of the message as the email body.

SMTPS 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-current.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
       http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/current/mule-smtps.xsd
       http://www.mulesoft.org/schema/mule/email http://www.mulesoft.org/schema/mule/email/current/mule-email.xsd
       http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/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. The string-to-email-transformer will set the current string payload of the message as the email body.

Configuration Reference

Connectors

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

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.

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-current.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/smtp http://www.mulesoft.org/schema/mule/smtp/current/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>

For the SMTPS 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

SMTPS with TLS:

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:smtps="http://www.mulesoft.org/schema/mule/smtps" xmlns:vm="http://www.mulesoft.org/schema/mule/vm" xmlns:jms="http://www.mulesoft.org/schema/mule/jms" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd
http://www.mulesoft.org/schema/mule/smtps http://www.mulesoft.org/schema/mule/smtps/current/mule-smtps.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/current/mule-jms.xsd ">
    <smtps:connector name="SMTP" validateConnections="true">
        <smtps:tls-client path="clientKeystore" storePassword="mulepassword"/>
        <smtps:tls-trust-store path="greenmail-truststore" storePassword="password"/>
    </smtps:connector>

    <flow name="relay">
        <vm:inbound-endpoint exchange-pattern="one-way" path="send"/>
        <smtps:outbound-endpoint host="localhost" port="65439" to="bob@example.com" responseTimeout="10000" connector-ref="SMTP"/>
    </flow>
</mule>

<smtp:gmail-connector> supports all of the above, but note it needs an outbound endpoint configured.

<?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-current.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/smtp http://www.mulesoft.org/schema/mule/smtp/current/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>
<smtp:outbound-endpoint connector-ref="Gmail" to="${email.to}" subject="test msg"
			address="smtps://${smtp.user}:${smtp.pass}@${smtp.host}"
			responseTimeout="10000" doc:name="Send notification email" ref="Gmail"/>

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. You can provide multiple addresses separated by commas.

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

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>

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

For more information about transformers, see the Transformers section in the Email Transport Reference.

For more information about filters, see the Filters section in the Email Transport Reference.

Exchange Patterns / Features of the Transport

See the transport matrix.

Schema Reference

You can view the full schema for the SMTP email transport here. The SMTPS version is 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>

Limitations

For more information about the limitations, see the Limitations section in the Email Transport Reference.

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.