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 javax.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 javax.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 |
---|---|---|
host |
The hostname or ip address of the SMTP server to use. |
|
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 |
E.g. "TLSv1.1 TLSv1.2" |
additionalSessionProperties |
Can be used to specify any other property for the |
"mail.smtp.socketFactory.class": "com.example.net.SocketFactory" |
poolSize |
Allows to specify the size of the connection pool for this |
4 |
maxMessagesPerConnection |
Allows to specify the max number of messages to be sent per connection when using connection pooling ( |
20 |
Listing 1 demonstrates how to use the SmtpServerConfig class.
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 |
---|---|
|
Encapsulates all the information about a single mail message (sender, recipient, carbon-copy recipients, subject, body, attachments, etc.). |
|
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. |
|
Contains information about an email attachment. |
|
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.
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 javax.mail.Session
object as demonstrated in Listing 3 and Listing 4.
org.eclipse.scout.rt.mail.smtp.SmtpServerConfig
object.BEANS.get(SmtpHelper.class).sendMessage(smtpServerConfig, mimeMessage);
javax.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 |
---|---|---|
scout.smtp.debugReceiverEmail |
If this property is set, the |
|
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 javax.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 toSmtpServerConfig.equals()
) belong to the same pool -
For each different
SmtpServerConfig
object (again usingSmtpServerConfig.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 |