Chapter 10. Mail Subsystem

The mail subsystem allows you to configure mail sessions in JBoss EAP and then inject those sessions into applications using JNDI. It also supports configuration using Java EE 7 @MailSessionDefinition and @MailSessionDefinitions annotations.

Configuring SMTP server for use in an application

For a full list of the attributes available for configuring mail sessions and servers, see Mail Subsystem Attributes.

When using a standard mail server, such as POP3 or IMAP, the mail server has a set of attributes that can be defined. Some of these attributes are mandatory. The most important of these is the outbound-socket-binding-ref, which is a reference to the outbound mail socket binding and is defined with a host address and port number.

Defining the outbound-socket-binding-ref may not be the most effective solution for users who have their host configuration using multiple hosts for load balancing purposes. Standard JavaMail does not support host configuration using multiple hosts for load balancing. Therefore, users who have this configuration using multiple hosts are required to implement custom mail transports. These custom mail transports do not require the outbound-socket-binding-ref and allow custom host property formats.

You can configure custom mail transports from the management CLI.

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-pop3-binding:add(host=localhost, port=110)
/subsystem=mail/mail-session=mySession/server=pop3:add(outbound-socket-binding-ref=my-pop3-binding, username=user, password=pass)

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-imap-binding:add(host=localhost, port=143)
/subsystem=mail/mail-session=mySession/server=imap:add(outbound-socket-binding-ref=my-imap-binding, username=user, password=pass)

To use a custom server, create a custom mail server without an outbound socket binding. You can specify the host information in the properties definition of the custom mail server. For example:

/subsystem=mail/mail-session=mySession/custom=myCustomServer:add(username=user,password=pass, properties={"host" => "myhost", "my-property" =>"value"})

If you define a custom protocol, any property name that includes a period (.) is considered a fully-qualified name and is passed directly. Any other format, such as my-property, is translated in the following format: mail.server-name.my-property.

The following XML is an example mail configuration that includes custom servers.

<subsystem xmlns="urn:jboss:domain:mail:2.0">
   <mail-session name="default" jndi-name="java:jboss/mail/Default">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
   </mail-session>
    <mail-session name="myMail" from="user.name@domain.org" jndi-name="java:/Mail">
        <smtp-server password="password" username="user" tls="true" outbound-socket-binding-ref="mail-smtp"/>
        <pop3-server outbound-socket-binding-ref="mail-pop3"/>
        <imap-server password="password" username="nobody" outbound-socket-binding-ref="mail-imap"/>
    </mail-session>
    <mail-session name="custom" jndi-name="java:jboss/mail/Custom" debug="true">
        <custom-server name="smtp" password="password" username="username">
            <property name="host" value="mail.example.com"/>
        </custom-server>
    </mail-session>
    <mail-session name="custom2" jndi-name="java:jboss/mail/Custom2" debug="true">
        <custom-server name="pop3" outbound-socket-binding-ref="mail-pop3">
            <property name="custom-prop" value="some-custom-prop-value"/>
        </custom-server>
    </mail-session>
</subsystem>

In addition to providing clear-text passwords in the mail subsystem, you can also use a credential store to provide passwords. The elytron subsystem provides the ability to create credential stores to securely house and use your passwords throughout JBoss EAP. You can find more details on creating and using credential stores in the Credential Store section of How to Configure Server Security.

/subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding, username=user, credential-reference={store=exampleCS, alias=mail-session-pw}, tls=true)

credential-reference={clear-text="MASK-Ewcyuqd/nP9;A1B2C3D4;351"}