Chapter 20. Mail subsystem
20.1. Use custom transports in mail subsystem
When using a standard mail server (POP3, IMAP) the server has a set of attributes that can be defined, some of which are required.
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 the host address and port number.
This is not the most effective solution for some users as their host configuration used multiple hosts for load balancing purposes. This configuration, however, is not supported by standard JavaMail requiring some users to implement custom mail transports.
These custom transports do not require the
outbound-socket-binding-ref and allow custom host property formats.
A custom transport can be configured through the CLI using the following commands:
Procedure 20.1.
- Add new mail session. The command below creates new session called mySession and sets JNDI to
java:jboss/mail/MySession:/subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
- Add an outbound socket binding. The command below adds a socket binding named
my-smtp-bindingwhich points tolocalhost:25./socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp-binding:add(host=localhost, port=25)
- Add an SMTP server with
outbind-socket-binding-ref. The command below adds an SMTP calledmy-smtp-bindingand defines a username, password and TLS configuration./subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref= my-smtp-binding, username=user, password=pass, tls=true)
- Repeat this process for POP3 and IMAP:
/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 new custom mail server without an outbound socket binding (as it is optional) and instead provide the host information as part of properties.
/subsystem=mail/mail-session=mySession/custom=myCustomServer:add(username=user,password=pass, properties={"host" => "myhost", "my-property" =>"value"})When defining custom protocols, any property name that contains a dot (.) is considered to be a fully-qualified name and passed as it is supplied. Any other format (my-property, for example) will be translated into the following format:mail.server-name.my-property.
Below is an example complete configuration XML configuration that highlights a custom format in the custom-server attribute:
<subsystem xmlns="urn:jboss:domain:mail:1.1">
<mail-session jndi-name="java:/Mail" from="user.name@domain.org">
<smtp-server outbound-socket-binding-ref="mail-smtp" tls="true">
<login name="user" password="password"/>
</smtp-server>
<pop3-server outbound-socket-binding-ref="mail-pop3"/>
<imap-server outbound-socket-binding-ref="mail-imap">
<login name="nobody" password="password"/>
</imap-server>
</mail-session>
<mail-session debug="true" jndi-name="java:jboss/mail/Default">
<smtp-server outbound-socket-binding-ref="mail-smtp"/>
</mail-session>
<mail-session debug="true" jndi-name="java:jboss/mail/Custom">
<custom-server name="smtp">
<login name="username" password="password"/>
<property name="host" value="mail.example.com"/>
</custom-server>
<custom-server name="pop3" outbound-socket-binding-ref="mail-pop3">
<property name="custom_prop" value="some-custom-prop-value"/>
<property name="some.fully.qualified.property" value="fully-qualified-prop-name"/>
</custom-server>
</mail-session>
<mail-session debug="true" jndi-name="java:jboss/mail/Custom2">
<custom-server name="pop3" outbound-socket-binding-ref="mail-pop3">
<property name="custom_prop" value="some-custom-prop-value"/>
</custom-server>
</mail-session>
</subsystem>