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.0.
9.1. Configuring the mail subsystem
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
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)
Call the configured mail session within an application:
@Resource(lookup="java:jboss/mail/MySession") private Session session;
Additional resources
9.2. Configuring custom transports
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
Add a new mail session and specify the JNDI name.
/subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
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)
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: 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>
9.3. Using a credential store for passwords
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.
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)
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"}
Use a credential store for passwords using the management console:
- Access the management console. For more information, see the Management console.
-
Navigate to Configuration
Subsystems Mail. - Select the appropriate mail session and click View.
- 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.