Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Chapter 10. Mail Subsystem

10.1. Configuring the 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

  1. Configure the SMTP server and the outbound socket binding using the following CLI commands, for example:

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp:add(host=localhost, port=25)
    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp, username=user, password=pass, tls=true)
  2. Call the configured mail session within an application

    @Resource(lookup="java:jboss/mail/MySession")
    private Session session;

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

10.2. Configuring Custom Transports

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.

  1. Add a new mail session and specify the JNDI name.

    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
  2. Add an outbound socket binding and specify the host and port.

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp-binding:add(host=localhost, port=25)
  3. Add an SMTP server and specify the outbound socket binding, username, and password.

    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding, username=user, password=pass, tls=true)
Note

You can configure a POP3 or IMAP server using similar steps.

POP3 Server

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

IMAP Server

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

10.3. Use a Credential Store for Passwords

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.

Using a Credential Store Using the Management CLI

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

Note

The following is an example of how to specify a credential-reference attribute that uses a clear-text password.

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

Using a Credential Store Using the Management Console

  1. Access the management console. For more information, see the Management Console.
  2. Navigate to ConfigurationSubsystemsMail.
  3. In the Mail Session tab, select the mail session for which you would like to use the credential store.
  4. Click on View to configure your mail session attributes and credential references.