Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 9. Mail subsystem

This chapter focuses on the mail subsystem, essential for integrating email functionalities into your JBoss EAP application. This section, provides detailed procedures for configuring the mail server settings, customizing transport protocols to meet your organization’s specific needs, and enhancing security through the use of a credential store for password management.

Prerequisites

  • You have installed JBoss EAP 8.1.

9.1. Configuring the mail subsystem
Copy link

The mail subsystem allows you to configure mail sessions in JBoss EAP, and then inject those sessions into your applications using JNDI. Additionally, it supports the use of Jakarta EE annotations like @MailSessionDefinition and @MailSessionDefinitions to streamline the configuration process.

Prerequisites

  • You have JBoss EAP installed and running.
  • You have network access to the SMTP server.

Procedure

  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)
    Copy to Clipboard Toggle word wrap 
    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
    Copy to Clipboard Toggle word wrap 
    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp, username=user, password=pass, tls=true)
    Copy to Clipboard Toggle word wrap

  2. Call the configured mail session within an application: 

    @Resource(lookup="java:jboss/mail/MySession")
private Session session;
    Copy to Clipboard Toggle word wrap

9.2. Configuring custom transports
Copy link

When you configure a standard mail server like SMTP, POP3 or IMAP in JBoss EAP, you need to define several attributes, with the most crucial being the outbound-socket-binding-ref attribute. This attribute links your mail session to a specific host and port. However, if your setup involves multiple hosts for load balancing, standard Jakarta Mail configurations might fall short, as they don’t support multiple hosts. In such cases, you should set up custom mail transports through the management CLI. These custom transports allow for more flexible configurations and don’t require the outbound-socket-binding-ref attribute.

Prerequisites

  • JBoss EAP installed and running.

Procedure

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

    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap
    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)
    Copy to Clipboard Toggle word wrap
    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)
    Copy to Clipboard Toggle word wrap

    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"})
Copy to Clipboard Toggle word wrap

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:4.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>
Copy to Clipboard Toggle word wrap

9.3. Using a credential store for passwords
Copy link

In addition to using clear-text passwords, you can enhance security in the JBoss EAP mail subsystem by using a credential store. The elytron subsystem allows you to create and manage credential stores to securely store and access passwords. For detailed steps on how to set up and use these credential stores, you can refer to the Credential Store section of How to Configure Server Security.

Prerequisites

  • JBoss EAP installed and running.

Procedure

  • Use a credential store for passwords 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)
    Copy to Clipboard Toggle word wrap
    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"}
    Copy to Clipboard Toggle word wrap

  • Use a credential store for passwords 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.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

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

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.

Theme

© 2025 Red Hat