Chapter 10. Mail Subsystem

download PDF

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 the Jakarta EE @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/server=smtp:add(outbound-socket-binding-ref=my-smtp, username=user, password=pass, tls=true)
  2. Call the configured mail session within an application

    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 Jakarta Mail 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.

  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)

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:

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

<subsystem xmlns="urn:jboss:domain:mail:3.0">
   <mail-session name="default" jndi-name="java:jboss/mail/Default">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
    <mail-session name="myMail" from="" 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 name="custom" jndi-name="java:jboss/mail/Custom" debug="true">
        <custom-server name="smtp" password="password" username="username">
            <property name="host" value=""/>
    <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"/>

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)


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


Using a Credential Store Using the Management Console

  1. Access the management console. For more information, see the Management Console.
  2. Navigate to Configuration Subsystems Mail.
  3. Select the appropriate mail session and click View.
  4. Select Server and choose the appropriate mail session server. You can configure the credential reference in the Credential Reference tab and edit other attributes in the Attributes tab.
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.