SmtpHelper

This document is referring to a past Scout release. Please click here for the recent version.

The org.eclipse.scout.rt.mail.smtp.SmtpHelper is an @ApplicationScoped Bean that provides means of sending emails described by jakarta.mail.internet.MimeMessage objects via SMTP. The SMTP connection can either be provided as a org.eclipse.scout.rt.mail.smtp.SmtpServerConfig object containing all the required connection parameters or as an already created jakarta.mail.Session object. The SmtpHelper also supports pooling of SMTP connections as described in the section Connection Pooling.

SmtpServerConfig

The org.eclipse.scout.rt.mail.smtp.SmtpServerConfig class allows to specify details of an SMTP connection to be made. It supports the following properties:

Property Description Example

Property	Description	Example
host	The hostname or ip address of the SMTP server to use.	`localhost` or `192.168.10.199`.
port	The TCP port the SMTP server listens on.	E.g. 25 or 465.
username	The username to use for authentication.	-
password	The password to use for authentication.	-
useAuthentication	Whether to use authentication or not. This setting is only effective, if a username has been provided.	-
useSmtps	If true, the protocol will be 'smtps', else the protocol will be 'smtp'.	-
useStartTls	If true, STARTTLS will be used to create the connection to the SMTP server.	-
sslProtocols	Limits the SSL protocols to support when connecting to the SMTP server. The value is a space separated list of protocol names returned by the `javax.net.ssl.SSLSocket.getSupportedProtocols()` method.	E.g. "TLSv1.1 TLSv1.2"
additionalSessionProperties	Can be used to specify any other property for the `jakarta.mail.Session` that is created from `org.eclipse.scout.rt.mail.smtp.SmtpServerConfig`. These additional properties are applied after all the other properties, thus may override already specified properties.	"mail.smtp.socketFactory.class": "com.example.net.SocketFactory"
poolSize	Allows to specify the size of the connection pool for this `SmtpServerConfig`. The Default value is 0 which effectively deactives connection pooling.	4
maxMessagesPerConnection	Allows to specify the max number of messages to be sent per connection when using connection pooling (`poolSize` > 0). The default value is 0 which effectively disables limiting the maximum number of messages sent per connection. You should consult with the operator of the SMTP server you are using to define this value. Local mail servers probably allow less than 20 messages per connection, bigger white mailers may allow up to 100 or even more.	20

host

The hostname or ip address of the SMTP server to use.

localhost or 192.168.10.199.

port

The TCP port the SMTP server listens on.

E.g. 25 or 465.

username

The username to use for authentication.

password

The password to use for authentication.

useAuthentication

Whether to use authentication or not. This setting is only effective, if a username has been provided.

useSmtps

If true, the protocol will be 'smtps', else the protocol will be 'smtp'.

useStartTls

If true, STARTTLS will be used to create the connection to the SMTP server.

sslProtocols

Limits the SSL protocols to support when connecting to the SMTP server. The value is a space separated list of protocol names returned by the javax.net.ssl.SSLSocket.getSupportedProtocols() method.

E.g. "TLSv1.1 TLSv1.2"

additionalSessionProperties

Can be used to specify any other property for the jakarta.mail.Session that is created from org.eclipse.scout.rt.mail.smtp.SmtpServerConfig. These additional properties are applied after all the other properties, thus may override already specified properties.

"mail.smtp.socketFactory.class": "com.example.net.SocketFactory"

poolSize

Allows to specify the size of the connection pool for this SmtpServerConfig. The Default value is 0 which effectively deactives connection pooling.

maxMessagesPerConnection

Allows to specify the max number of messages to be sent per connection when using connection pooling (poolSize > 0). The default value is 0 which effectively disables limiting the maximum number of messages sent per connection. You should consult with the operator of the SMTP server you are using to define this value. Local mail servers probably allow less than 20 messages per connection, bigger white mailers may allow up to 100 or even more.

Listing 1 demonstrates how to use the SmtpServerConfig class.

Listing 1. Create and configure an instance of org.eclipse.scout.rt.mail.smtp.SmtpServerConfig

@SuppressWarnings("unused")
SmtpServerConfig smtpServerConfig = BEANS.get(SmtpServerConfig.class)
    .withHost("mail.example.com")
    .withPort(465)
    .withUsername("smtpuser")
    .withPassword("smtpuserpwd")
    .withUseAuthentication(true)
    .withUseSmtps(true)
    .withUseStartTls(true);

Sending messages

Messages can be sent using the sendMessage Methods of the SmtpHelper class. In Order to prepare the message to be sent, Scout provides a number of classes and helpers:

Class Description

Class	Description
`org.eclipse.scout.rt.mail.MailMessage`	Encapsulates all the information about a single mail message (sender, recipient, carbon-copy recipients, subject, body, attachments, etc.).
`org.eclipse.scout.rt.mail.MailParticipant`	Defines email address and name of a mail participant. A participant can be a recipient, a carbon-copy recipient, a blind-carbon-copy recipient, the sender and a replyTo contact.
`org.eclipse.scout.rt.mail.MailAttachment`	Contains information about an email attachment.
`org.eclipse.scout.rt.mail.MailHelper`	Provides various helper methods around email bodies, attachments, etc.

org.eclipse.scout.rt.mail.MailMessage

Encapsulates all the information about a single mail message (sender, recipient, carbon-copy recipients, subject, body, attachments, etc.).

org.eclipse.scout.rt.mail.MailParticipant

Defines email address and name of a mail participant. A participant can be a recipient, a carbon-copy recipient, a blind-carbon-copy recipient, the sender and a replyTo contact.

org.eclipse.scout.rt.mail.MailAttachment

Contains information about an email attachment.

org.eclipse.scout.rt.mail.MailHelper

Provides various helper methods around email bodies, attachments, etc.

Listing 2 shows the usage of the mentioned classes Scout provides in order to create a MimeMessage object.

Listing 2. Create org.eclipse.scout.rt.mail.CharsetSafeMimeMessage object

// create BinaryResource for an attachment.
BinaryResource screenshotResource = BinaryResources.create()
    .withFilename("screenshot.jpg")
    .withContentType("image/jpeg")
    .withContent(bytes)
    .build();

// wrap BinaryResource in MailAttachment
MailAttachment screenshotAttachment = new MailAttachment(screenshotResource);

// prepare Scout MailMessage
MailMessage mailMessage = BEANS.get(MailMessage.class)
    .withSender(BEANS.get(MailParticipant.class).withName("sender").withEmail("me@example.com"))
    .addToRecipient(BEANS.get(MailParticipant.class).withName("recipient").withEmail("somebody@example.com"))
    .withAttachment(screenshotAttachment)
    .withSubject("Screenshot")
    .withBodyPlainText("Dear recipient,\n\nPlease have a look at my screenshot!\n\nRegards,\nsender");

// convert MailMessage to MimeMessage
CharsetSafeMimeMessage mimeMessage = BEANS.get(MailHelper.class).createMimeMessage(mailMessage);

In order to send the message you can either use a org.eclipse.scout.rt.mail.smtp.SmtpServerConfig object or an existing jakarta.mail.Session object as demonstrated in Listing 3 and Listing 4.

Listing 3. Send email using an org.eclipse.scout.rt.mail.smtp.SmtpServerConfig object.

BEANS.get(SmtpHelper.class).sendMessage(smtpServerConfig, mimeMessage);

Listing 4. Send email using an existing jakarta.mail.Session object.

// The password has to be provided additionally as it is not stored in the session object.
BEANS.get(SmtpHelper.class).sendMessage(session, password, mimeMessage);

SmtpHelper Configuration

The SmtpHelper provides some config properties that allow to modify certain behaviour.

Key Description Example

Key	Description	Example
scout.smtp.debugReceiverEmail	If this property is set, the `SmtpHelper` sends all emails to the specified email address instead of the recipients specified in the `MimeMessage` object. This is useful for development and testing environments.	debug-receiver@example.com
scout.smtp.connectionTimeout	Specifies the connection timeout for SMTP connections in milliseconds. Default is 60 seconds.	30000
scout.smtp.readTimeout	Specifies the read timeout for SMTP connections in milliseconds. Default is 60 seconds.	30000

scout.smtp.debugReceiverEmail

If this property is set, the SmtpHelper sends all emails to the specified email address instead of the recipients specified in the MimeMessage object. This is useful for development and testing environments.

debug-receiver@example.com

scout.smtp.connectionTimeout

Specifies the connection timeout for SMTP connections in milliseconds. Default is 60 seconds.

30000

scout.smtp.readTimeout

Specifies the read timeout for SMTP connections in milliseconds. Default is 60 seconds.

30000

Connection Pooling

Normally, the SmtpHelper opens a new connection for every email which is then closed after the email has been sent. If you want to send a lot of emails, this behaviour is rather inefficient as opening a new SMTP connection takes a long time compared to sending the email especially when using encrypted connections. To mitigate this overhead, the SmtpHelper supports pooling of SMTP connections which is activated using the poolSize property of SmtpServerConfig objects. If you set the pool size property to a value > 0, the SmtpHelper will create parallel connections up to the specified number. This means, that connection pooling is not possible when you use the sendMessage method accepting an already prepared jakarta.mail.Session object.

Pooling in this context means the following:

All SMTP server connections sharing the same SmtpServerConfig object (by same meaning being equal according to SmtpServerConfig.equals()) belong to the same pool
For each different SmtpServerConfig object (again using SmtpServerConfig.equals()) up to the specified pool size connections are created
Connections are not immediately closed after an email has been sent, instead they are returned to the pool as idle connections.
Before creating new connections, idle connections are reused.
When trying to send an email while all the SMTP connections are currently in use and the pool size has already been reached, the calling thread is blocked until a connection is returned as idle to the pool or as soon as the wait-for-connection-timeout has exceeded.
As long as connections are open, a background job monitors their state and closes idle and old connections.

SmtpConnectionPool Configuration

The following config properties allow to modify the behavior of the connection pool implementation at the global level:

key	Description	Example
scout.smtp.pool.maxIdleTime	Specifies how long in seconds a connection can be idle before it is closed by the background cleanup job. Default is 60 seconds.	30
scout.smtp.pool.maxConnectionLifetime	Specifies how long in seconds a connection can be open before it is closed. This is to prevent connections from being open forever when sending emails on a regular basis. Default is 1h.	7200
scout.smtp.pool.waitForConnectionTimeout	Max. wait time for SMTP connection in seconds. If the value is 0, callers will wait infinitely long for SMTP connections. Default is 300 seconds.	100

key

Description

Example

scout.smtp.pool.maxIdleTime

Specifies how long in seconds a connection can be idle before it is closed by the background cleanup job. Default is 60 seconds.

scout.smtp.pool.maxConnectionLifetime

Specifies how long in seconds a connection can be open before it is closed. This is to prevent connections from being open forever when sending emails on a regular basis. Default is 1h.

7200

scout.smtp.pool.waitForConnectionTimeout

Max. wait time for SMTP connection in seconds. If the value is 0, callers will wait infinitely long for SMTP connections. Default is 300 seconds.

100