Configuration

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("smtp.host.com", 25, "username", "password");
// or
MailerBuilder
  .withSMTPServerHost("smtp.host.com")
  .withSMTPServerPort(25)
  .withSMTPServerUsername("username")
  .withSMTPServerPassword("password");

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

// adding the transport strategy...
currentMailerBuilder.withTransportStrategy(TransportStrategy.SMTP_TLS)

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

// or authenticated proxy
currentMailerBuilder
  .withProxy("proxy.host.com", 1080, "proxy username", "proxy password");
// or
currentMailerBuilder
  .withProxyHost("proxy.host.com")
  .withProxyPort(1080)
  .withProxyUsername("proxy username")
  .withProxyPassword("proxy password");

// anonymous smtp + anonymous proxy + default SMTP protocol strategy
currentMailerBuilder
        .withSMTPServerHost("smtp.host.com").withSMTPServerPort(25)
        .withProxyHost("proxy.host.com").withProxyPort(1080);

// configure everything!
MailerBuilder
        .withSMTPServer("smtp.host.com", 587, "user@host.com", "password")
        .withTransportStrategy(TransportStrategy.SMTP_TLS)
        .withProxy("socksproxy.host.com", 1080, "proxy user", "proxy password")
        .buildMailer()
        .sendMail(email);

// preconfigured Session?
MailerBuilder.usingSession(session);

// preconfigured but you need anonymous proxy?
MailerBuilder
        .usingSession(session)
        .withProxy("socksproxy.host.com", 1080);

// preconfigured but you need authenticated proxy?
MailerBuilder
        .usingSession(session)
        .withProxy("socksproxy.host.com", 1080, "proxy user", "proxy password");

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

Properties for the environments

#global default properties (simplejavamail.properties on classpath)

    # anonoymous SMTP inside 'safe' DMZ
    simplejavamail.smtp.host=dmz.smtp.candyshop.com
    simplejavamail.smtp.port=25

    # default sender and reply-to address
    simplejavamail.defaults.from.name=The Candy App
    simplejavamail.defaults.from.address=candyapp@candystore.com
    simplejavamail.defaults.replyto.name=Candystore Helpdesk
    simplejavamail.defaults.replyto.address=helpdesk@candystore.com

#overrides from TEST and UAT .../config/candystore/simplejavamail.properties

    # always send a copy to test archive
    simplejavamail.defaults.bcc.name=Archive TST UAT
    simplejavamail.defaults.bcc.address=test-archive@candyshop.com

#overrides from PRODUCTION .../config/candystore/simplejavamail.properties

    # always send a copy to production archive
    simplejavamail.defaults.bcc.name=Archive PRODUCTION
    simplejavamail.defaults.bcc.address=prod-archive@candyshop.com

    # smtp server in production is protected
    simplejavamail.smtp.username=creamcake
    simplejavamail.smtp.password=crusty_l0llyp0p

    # sending mails in production must go through proxy
    simplejavamail.proxy.host=proxy.candyshop.com
    simplejavamail.proxy.port=1080
    simplejavamail.proxy.username=candyman
    simplejavamail.proxy.password=I has the sugarcanes!!1!

Load the complete configuration for the selected environment first. Only then create its builder and Mailer.

// simplejavamail.properties is automatically loaded

// replace previously loaded defaults with this environment's property file;
// system properties and environment variables still take priority
Path environmentConfig = Path.of("config", "candystore", "simplejavamail.properties");
ConfigLoader.loadProperties(Files.newInputStream(environmentConfig), false);

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

// add values assembled by the application
Properties runtimeOverrides = new Properties();
runtimeOverrides.setProperty("simplejavamail.smtp.port", "2525");
ConfigLoader.loadProperties(runtimeOverrides, true);

Maybe we want to connect slightly different for some reason:

// start a fresh builder after every source for this environment has been loaded
// override only the port and connection type, leave everything else to config files
Mailer mailer = MailerBuilder
                  .withSMTPServerPort(587)
                  .withTransportStrategy(TransportStrategy.SMTP_TLS)
                  .buildMailer();

A Mailer is designed to be built once and reused. When your application is finished with it, call mailer.close() directly or let a try-with-resources block call it. Which resources need attention depends on how the Mailer is used and whether its executor came from Simple Java Mail or from your application.

Closing a Mailer releases the resources it owns: it stops an executor created by Simple Java Mail and, when pooled delivery is active, closes that Mailer's connection-pool registration. It does not wait for outstanding send futures or stop an executor supplied by your application.

Use close() for normal application shutdown. It shuts down an executor created by Simple Java Mail and, when pooled delivery is active, closes the connection pool registered for that Mailer. It never shuts down an executor supplied through withExecutorService(...).

The older shutdownConnectionPool() method starts the same cleanup and returns the connection-pool shutdown future. Despite its name, it also initiates shutdown of a Mailer-created executor when no connection pool is present. Neither method waits for your asynchronous send futures, so finish those first.

Simple Java Mail provides four ways of sending more than one email, each meant for a different level of control and throughput:

1. regular synchronous sending, one email at a time
2. asynchronous sending using the mailer's configured ExecutorService
3. simple sequential batch sending over one SMTP connection
4. pooled and clustered sending for sustained throughput

If your application creates its own Jakarta Mail messages or a framework already owns Transport, first use the SMTP connection pooling and batch orchestration guide to choose the delivery path and lifecycle boundary that match your code.

Direct asynchronous sending schedules send tasks on the mailer's configured ExecutorService. Each send still opens and closes its own Transport connection, managed independently of a connection pool. By default this direct executor is a single-thread executor; provide a custom ExecutorService if you want different concurrency. Every concurrent send still needs its own SMTP connection, which is less efficient in high-volume scenarios and can reach the SMTP server's connection limit more quickly.

Mailer regularMailer = mailerBuilder.(..).buildMailer();
regularMailer.sendMail(email); // blocks

Mailer defaultAsyncMailer = mailerBuilder.(..).async().buildMailer();
defaultAsyncMailer.sendMail(email); // doesn't block

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

currentMailerBuilder.withExecutorService(new MyAwesomeCustomThreadPoolExecutor())

See Mailer lifecycle and resource ownership for who shuts down the default and custom executors.

Pooled delivery reuses SMTP connections across worker threads. The default setup provides up to four pooled connections, which automatically close if inactive for five seconds following their last use. This mechanism is optimal for managing bursts of email traffic, keeping up to four connections active as long as needed.

The connection pool configuration is flexible, allowing adjustments to core connection pool size, maximum pool size, and connection expiry policy.

This section configures the Simple Java Mail Mailer path. Compare it with the standalone batch facade, direct leases, and provider-owned pooling in the pool orchestration guide.

Direct sending can use a custom thread pool, while pooled sending also lets those threads reuse Transport connections. This can improve performance even with fewer threads, as it eliminates the need to repeatedly open and close connections for each email.

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 about 24.9 days)
	   .withConnectionPoolExpireAfterMillis(TimeUnit.MINUTES.toMillis(30)) // keep connections spinning for half an hour (default 5 seconds)
	   .buildMailer();
	

simplejavamail.defaults.connectionpool.coresize=2
simplejavamail.defaults.connectionpool.maxsize=10
simplejavamail.defaults.connectionpool.claimtimeout.millis=60000
simplejavamail.defaults.connectionpool.expireafter.millis=1800000