Fork me on GitHub
Simple Java Mail
Simple API, Complex Emails

Configuring Simple Java Mail

Simple Java Mail provides full configuration through programmatic API as well as system variables, environment variables and properties files (including Spring).

The Java API and config files complement each other. If you provide the overlapping configuration, the programmatic API takes priority, overriding system and environment values, overriding property values.

Central to configuring Simple Java Mail is the MailerBuilder. As the library grew maintaining all the constructors and setters proved unwieldy and so it moved to a completely builder based fluent API which produces a largely immutable Mailer instance.

Second, there is the ConfigLoader, which contains all the preconfigured defaults read initially from .properties files. It contains programmatic API to clear, add or replace default values.


Programmatic API - common settings

Everything can be configured through the java API. Specifically the builders are the entry point to creating Mailers and Emails and everything can be configured through them.

// start with a builder
MailerBuilder.withSMTPServer("", 25, "username", "password");
// or

// you can even leave out some details for an anonymous SMTP server
MailerBuilder.withSMTPServer("", 25);
// or

// adding the transport strategy...

// or instead adding anonymous proxy configuration
currentMailerBuilder.withProxy("", 1080);
// or

// or authenticated proxy
  .withProxy("", 1080, "proxy username", "proxy password");
// or

// anonymous smtp + anonymous proxy + default SMTP protocol strategy

// configure everything!
        .withSMTPServer("", 587, "", "password")
        .withProxyHost("", 1080, "proxy user", "proxy password");

// preconfigured Session?

// preconfigured but you need anonymous proxy?
        .withProxyHost("", 1080);

// preconfigured but you need authenticated proxy?
        .withProxyHost("", 1080, "proxy user", "proxy password");

Programmatic API - other settings

Aside from transport strategy, SMTP and Proxy server details, there are a few other more generic settings.

// ignore invalid email addresses (if email validator was provided)
// and ignore CRLF injection suspicions
// useful in case you want to delegate all responsibility to the server
// make the underlying javax.mail produce more logging
// skip actually sending email, just log it
// custom SSL connection factory (note: breaks setups with authenticated proxy!)

// change email validation strategy
		.withRule(email -> email.localPart().startsWith("allowed"))

// reset to default RFC compliant checks:
// deactivate email validation completely:

// change SOCKS5 bridge port in case of authenticated proxy
currentMailerBuilder.withProxyBridgePort(1081); // always localhost

// set custom properties
currentMailerBuilder.withProperties(new Properties());
currentMailerBuilder.withProperties(new HashMap());
currentMailerBuilder.withProperty("mail.smtp.sendpartial", true);

// or directly modify the internal Session instance:
mailer.getSession().getProperties().setProperty("mail.smtp.sendpartial", true);

/* Regarding the following config on trusting hosts,
    the Javadoc has more detailed info (in the mailer builder api). */
// trust all hosts for SSL connections
// or white list hosts for SSL connections (identity key validation notwithstanding)
currentMailerBuilder.trustingSSLHosts("a", "b", "c", ...);

// or clearing these options

/* Regarding the following config on identifying hosts,
    the Javadoc has more detailed info (in the mailer builder api). */
// don't validate keys thus not verifying server hosts
// change the pool size (default 10) for concurrent threads, each sending an email
// change keepAliveTime for other behavior.
// 0: threads don't die, !0: threads die after delay (default 1)

// completely replace the thread pool executor with your own
// this negates all related properties such as pool size and keepAliveTime
currentMailerBuilder.withExecutorService(new MyAwesomeCustomThreadPoolExecutor())
// change the SMTP session timeout (affects socket connect-, read- and write timeouts)
currentMailerBuilder.withSessionTimeout(10 * 1000); // 10 seconds for quick disconnect
// change the default sending logic to your own approach
currentMailerBuilder.withCustomMailer(yourOwnCustomMailerImpl); // send emails, test connections

Properties files

With properties files you can define defaults and overrides. You can also provide overriding value by defining system variables.

Simple Java Mail will automatically load properties from, if available on the classpath. Alternatively, you can manually load additional properties files in a number of ways.

Properties are loaded in order of priority from high to low:

  1. Programmatic values
  2. System variables
  3. Environment variables
  4. Properties from config files
ConfigLoader.loadProperties("", /* addProperties = */ true);
ConfigLoader.loadProperties(new File("d:/"), /* addProperties = */ false);
ConfigLoader.loadProperties(usingMyOwnInputStream, addProperties);
ConfigLoader.loadProperties(usingMyOwnPropertiesObject, addProperties);
This clears everything:
ConfigLoader.loadProperties(new Properties(), /* addProperties = */ false);

Available properties

Almost everything can be set as a default property. This way you can easily configure environments without changing the code.

simplejavamail.proxy.username=username proxy
simplejavamail.proxy.password=password proxy
simplejavamail.defaults.subject=Sweet News Default Default Default Default Default;
# following property is ignored when trustallhosts is true:
# following properties are used as defaults on Mailer level
simplejavamail.dkim.signing.private_key_file_or_data=my_dkim_key.der # or key as base64

Then there are extra properties which will directly go on the internal Session object when building a Mailer instance.

Mailer level email defaults and overrides

With property files and system variables you can define global defaults. But sometimes that is not enough.

With Simple Java Mail, you can set both defaults and overrides on the Mailer level using Java code. This will override global defaults loaded from a property file for example. However, before using it as defaults Email reference, you can still have your defaults initialized with global defaults, by using emailBuilder.buildEmailCompletedWithDefaultsAndOverrides().

Email yourServerLevelDefaults = EmailBuilder.startingBlank()
	/* set your defaults here */
	.buildEmailCompletedWithDefaultsAndOverrides(); // complete the instance with global defaults

Mailer adminServer = mailerBuiler.

One use case for this is when you have multiple mailer instances, each for a separate SMTP server clustered together (see clustering), you may want to define defaults or overrides for a specific server. You can do that by defining a reference Email instance and set it as defaults or overrides parameter.

// for example: force FROM to be always the same for the
// specific SMTP adminServer from the previous example:
Email yourServerLevelOverrides = EmailBuilder.startingBlank()
    .from("Admin", "")

You can exclude specific emails completely from having defaults or overrides applied by using ignoreDefaults or ignoreOverrides.


You can even exclude specific fields from the defaults or overrides if you want to make very specific exceptions.

	.dontApplyDefaultValueFor(EmailProperty.FROM, EmailProperty.REPLY_TO)

Combining everything for multiple environments

Let's set up configuration for a test, acceptance and production environment.

Properties for the environments

#global default properties ( on classpath)

    # anonoymous SMTP inside 'safe' DMZ

    # default sender and reply-to address Candy App Helpdesk
#overrides from TEST and UAT .../config/candystore/

    # always send a copy to test archive TST UAT
#overrides from PRODUCTION .../config/candystore/

    # always send a copy to production archive PRODUCTION

    # smtp server in production is protected

    # sending mails in production must go through proxy
    simplejavamail.proxy.password=I has the sugarcanes!!1!

Now for the programmatic part

// is automatically loaded

// assume that every environment provides its own property file
ConfigLoader.loadProperties(new File(".../config/candystore/"));

// see if we need to do some specific override for some reason
if (someSpecialCondition) {
  ConfigLoader.loadProperties("", true);

// or maybe we want to ditch all defaults and trust someone else's config completely
if (ditchOwnAndTrustOtherSource) {
  ConfigLoader.loadProperties(someFileOrInputSource, false);

// maybe the config service has something?
ConfigLoader.loadProperties(socket.getInpuStream(), true);
// or you have your own Properties source?
ConfigLoader.loadProperties(myOwnProperties, true);

Maybe we want to connect slightly different for some reason:

// override only the port and connection type, leave everything else to config files
Mailer mailer = MailerBuilder

Spring support

Everything can be configured through Spring properties, allowing for robust profile-based configuration.

To enable this, include the spring-module on your classpath.

By importing the Spring support bean from Simple Java Mail, whatever properties are provided through Spring are then transferred to Simple Java Mail using the ConfigLoader. It will add or overwrite whatever properties have been loaded before that (including the regular

Here's a sample configuration using Java style configuration.

Loading Spring support and obtaining default Mailer instance:
public class YourEmailService {

    @Autowired // or roll your own, as long as SimpleJavaMailSpringSupport is processed first
    private Mailer mailer;

Or obtaining the intermediate builder and customize:
public class YourEmailService {

        private MailerGenericBuilder mailerGenericBuilder;

        public Mailer customMailer() {
            return mailerGenericBuilder
                            .withExecutorService(new MyAwesomeCustomThreadPoolExecutor())
Then when you have profile based configuration (for example default and production):

Batch and clustering support

Even without using the batch-module, you can send emails asynchronously, in which case a single Transport connection is used without pooling it. This does still mean that for each email the connection is opened and closed. Depending on your network and SMTP server's capacity though, sending async like this already provides a huge performance boost if you configure the thread pool accordingly with MailerBuilder.

/* regular mailer: */
Mailer mailer = mailerBuiler.(..).build();
mailer.send(email); // blocks

/* mailer that defaults to async sending: */
Mailer mailer = mailerBuiler.(..).async().build();
mailer.send(email); // doesn't block

/* or be explicit about it: */
mailer.sendEmail(email, /*async = */ true);

Reusing connections with a connection pool

You can really take performance to the next level by using the connection pooling introduced by the batch-module. To do this you simply include the module on the class path (add the maven dependency) which gives you a default of maximum four pooled connections, which auto-close 5 seconds after the last time they were utilized. What this means is if you have bursts of emails batches, the connections spin up to max four and stay alive until activity dies down.

You can modify this behavior by defining a core connection pool size, max pool size and a custom expiry policy.

Mailer pooledMailer = mailerBuilder
	   .withConnectionPoolCoreSize(2) // keep 2 connections up at all times, automatically refreshed after expiry policy closes it (default 0)
	   .withConnectionPoolMaxSize(10) // scale up to max 10 connections until expiry policy kicks in and cleans up (default 4)
	   .withConnectionPoolClaimTimeoutMillis(TimeUnit.MINUTES.toMillis(1)) // wait max 1 minute for available connection (default forever)
	   .withConnectionPoolExpireAfterMillis(TimeUnit.MINUTES.toMillis(30)) // keep connections spinning for half an hour (default 5 seconds)

Or using properties:

simplejavamail.defaults.connectionpool.coresize=2 (defaults to 0)
simplejavamail.defaults.connectionpool.maxsize=10 (defaults to 4)
simplejavamail.defaults.connectionpool.claimtimeout.millis=60000 (defaults to forever)
simplejavamail.defaults.connectionpool.expireafter.millis=1800000 (defaults to 5000)

Note that with the batch-module enabled, the JVM won't shut down by itself anymore, as the connection pool stays alive until shutdown manually. To do this, just call mailer.shutdownConnectionPool() (repeat with each mailer you might have in a cluster).


Clustering with multiple connection pools

To enable high-availability / fail-over or to really take performance to out-of-this world levels and handle truly enormous email batches, Simple Java Mail enables you to easily configure cluster(s) of SMTP servers.

For example, for a simple fail-over setup with three SMTP servers, You can define a cluster with low/default connection pool settings and have three Mailer instances use the same cluster key. Then sending an email with any of these Mailer instances will result in a send-action resolved using the cluster.

Global cluster config:
Mailer clusteredMailer = mailerBuilder
	   .(..) // normal settings
	   .(..) // connection pool settings
or using properties:
# valid values: ROUND_ROBIN, RANDOM

Mailer behavior in a cluster setup:

Mailer mailer1InFailoverCluster = mailerBuilderServer1.(..).withClusterKey(myClusterKey).build();
Mailer mailer2InFailoverCluster = mailerBuilderServer2.(..).withClusterKey(myClusterKey).build();
Mailer mailer3InFailoverCluster = mailerBuilderServer3.(..).withClusterKey(myClusterKey).build();

// or default cluster using property:
// simplejavamail.defaults.connectionpool.clusterkey.uuid=38400000-8cf0-11bd-b23e-10b96e4ef00d

mailer1InFailoverCluster.send(email); // 1 of 3 servers is selected (default Round Robin)
mailer2InFailoverCluster.send(email); // 1 of 3 servers is selected (default Round Robin)
mailer3InFailoverCluster.send(email); // 1 of 3 servers is selected (default Round Robin)

// now server 2 breaks down and becomes unreachable or produces errors
// server 2 is removed from the cluster, but all mailers still work:
mailer1InFailoverCluster.send(email); // 1 of 2 servers is selected (default Round Robin)
mailer2InFailoverCluster.send(email); // 1 of 2 servers is selected (default Round Robin)
mailer3InFailoverCluster.send(email); // 1 of 2 servers is selected (default Round Robin)

Note 1: The send-actions don't automatically recover from errors and are not retried automatically. This is because Simple Java Mail cannot determine how a send-action was botched and what the next course of action should be. You can monitor individual emails using the CompletableFuture async return value obtained from mailer.send() and determine followup-actions for errored-out results.

Note 2: The Connection Pool defaults (core size, max size etc.) are set and fixed by the first Mailer instance in the cluster. Subsequent Mailer instances cannot change these global settings. If they provide different global defaults, a warning will be logged.

Note 3: Using the Java API, you can define any number of clusters. Using the default cluster uuid property, you can define only one default cluster.

You set the limit
So really, there's no limit to the email performance you are looking for except maybe in the client which generates the emails. You can add as many servers as you like to a cluster, use multiple clusters for different purposes and have as many pooled connections as you want dormant or spinned up at all time!