Capabilities

Simply build an Email, populate it with your data, build a Mailer and send the Email instance. The mailer can be created with your own Session instance as well.

A Mailer instance is reusable.

Multiple Mailer instances can also be combined into a cluster.

You can preconfigure a Mailer and use it many times. It is thread-safe.

If a recipient needs to be assembled outside an email builder call, use the dedicated recipient builders. This keeps address parsing, recipient type and optional recipient metadata in one small object before it is added to an email. When several recipients belong together, RecipientsBuilder lets you apply their shared names and certificates before adding the group to an email.

RecipientBuilder always creates exactly one recipient: pass one RFC 2822 address to withAddress(...), optionally with a display name. For multiple recipients, use RecipientsBuilder. Its String inputs may be separate addresses or comma- and semicolon-delimited lists, and every parsed address becomes its own recipient. Set the recipient type explicitly to TO, CC or BCC in either builder.

Default names and default certificates only fill missing values. Fixed names and fixed certificates override source data for the whole group. clearingSmimeCertificates() removes certificate state from reused recipients when the current email should use its own S/MIME fallback instead.

Recipient-level S/MIME certificates are described in the S/MIME security section.

The default mode is to send emails synchronously, blocking execution until the email was processed completely and the SMTP server sent a successful result.

You can also send asynchronously in parallel or batches, or simply send in a fire-and-forget way. If an authenticated proxy is used, the proxy bridging server is kept alive until the last email has been sent.

Depending on the SMTP server (and proxy server if used) this can greatly influence how fast emails are sent.

Passing true to sendMail(...) or testConnection(...) runs the operation asynchronously. The returned CompletableFuture covers the whole operation: applying defaults and overrides, validation, scheduling, conversion, connection and transport. A failure at any of those stages completes the future exceptionally.

Preparation and validation still happen on the calling thread before the transport work is scheduled. In asynchronous mode, their failures are placed on the future instead of escaping from the method call. Clear call errors, such as a null email argument, can still be thrown immediately.

With false, the work runs on the calling thread. A successful call returns an already-completed future; a failure is thrown directly.

If you prefer to use your own preconfigured Session instance and still benefit from Simple Java Mail, you can!

By default content is encoded in the target MimeMessage or EML using quoted-printable, so the EML is nicely and safely readable. You can also use other encoders. Base64, for example, turns the content into ASCII text for reliable MIME transport. It is encoding, not encryption; the original content remains directly decodable.

The email header that governs this feature is Content-Transfer-Encoding and Simple Java Mail takes care of inserting this header in the right places, which varies depending on the necessary email structure.

Encoding attachments

You can control encoding separately for attachments, so your text files for examples can be encoded differently too.

Encoding body parts separately

The global content-transfer encoding is still the fallback, but plain text, HTML and calendar body parts can override it individually. The same defaults can be supplied through properties.

Message id's are normally generated by the underlying Jakarta Mail framework, but you can provide your own if required.

Just make sure your own id's conform to the rfc5322 msg-id format standard

Message sent date is normally filled with the current date, but you can provide your own date if required.

Sometimes you need the actual ID used in the MimeMessage that went out to the SMTP server. Luckily, it's very easy to retrieve it.

When a log, trace, or background job needs the SMTP server's response for a submitted message, use sendMailAndGetReceipt(...). It follows the same send path as sendMail(...), but returns a MailSubmissionReceipt.

With the built-in Angus SMTP transport, the receipt contains the return code and final SMTP response, such as a 250 ... queued as ... response. Logging-only transport mode and custom mailers still return a receipt after successful processing, but without an SMTP response.

This confirms submission acceptance by the SMTP server, not final recipient mailbox delivery. Use Delivery Status Notification, bounces, read receipts or provider-specific tracking when you need final delivery signals.

The open-connection example uses the Mailer's built-in SMTP transport. It cannot be combined with a CustomMailer, which owns its own connection lifecycle.

Activating SSL or TLS is super easy. Just use the appropriate TransportStrategy enum.

Customizing SSL connections further
For maximum control, you can provide your own SSLSocketFactory too:

Here's an example of SSL and TLS using gMail.

If you have two-factor login turned on, you need to generate an application specific password from your Google account.

You can add attachments very easily, but you'll have to provide the data yourself. Simple Java Mail accepts byte[] and DataSource objects.

If for some reason you need the Content-Description header set as well, you can provide a content description on any attachment.

If attachment data is already encoded, use a pre-encoded attachment method. This tells Simple Java Mail to preserve the payload and use the provided ContentTransferEncoding value instead of encoding the data again.

Attachment resource names and MIME Content-ID values can also be set separately.

Embedding images dead simple with two options:

1. manual embedding: add cid: placeholders in the HTML yourself
2. auto resolution: enable auto-resolving image sources to files, class path resources or URL's

Pre-encoded embedded images work the same way as pre-encoded attachments: provide the already-encoded data and the encoding that is already present.

Auto resolution is opt-in. It can read image sources from files, classpath resources and URLs, then embed what it finds. If someone else can edit the HTML, enable only the resolver you need, configure its base, and leave outside-base access disabled. Since 9.2, each configured base is an actual boundary rather than just a lookup hint.

Without a base, resolution is unrestricted. Turning on an allowingEmbeddedImageOutsideBase... option deliberately removes that boundary. Use embeddedImageAutoResolutionMustBeSuccesful(true) when a missing or blocked image should fail the build instead of remaining in the HTML.

Sometimes you need extra headers in your email because your email server, recipient server or your email client needs it. Or perhaps you have a proxy or monitoring setup in between mail servers. Whatever the case, adding headers is easy.

In case you need to modify the internal Session object itself, because you need a tailored configuration that is supported by the underlying Jakarta Mail, that too is very easy.

You can also set some default properties to automatically be added.

Every property prepended with simplejavamail.extraproperties will be loaded directly on the internal Session object.

Jakarta Mail can produce low-level protocol debug output. Simple Java Mail can keep the old console behavior, route it to stderr, or send it to the org.simplejavamail.javamail.debug SLF4J logger.

On machines with multiple local IP addresses, the outgoing SMTP socket can be bound to a specific local/source address. Simple Java Mail applies this to the right Jakarta Mail property for the configured transport strategy.

Leave the local port empty unless you specifically need it. Binding a fixed local port can conflict with another connection.

Corporate SMTP relays sometimes expect a stable, recognizable client hostname in the SMTP EHLO or HELO command. Even when the relay does not enforce it, this makes application traffic recognizable in mail-server logs, tracing, audit trails and SMTP diagnostics.

This is the SMTP protocol identity and maps to mail.smtp.localhost or mail.smtps.localhost depending on the transport strategy. It is not the same as binding the local/source socket address, and it does not change the SMTP envelope sender.

You want to send a nice Calendar event (.ics) that a client such as Outlook processes nicely?

Easy!

Produce a Calendar event String (manually or by using a library such as ical4j) and pass it to the EmailBuilder.

See the test demo app included in the Simple Java Mail source for a working example.

For emergencies, you can also get a hold of the internal Session instance itself. You should never need this however and if you do it means Simple Java Mail failed to simplify the configuration process for you. Please let us know how we can help alleviate this need.

Simple Java Mail can add two receipt-request headers. Disposition-Notification-To asks supporting mail clients for a read receipt. Return-Receipt-To asks supporting servers or clients for a delivery or read notification, depending on their implementation.

Simple Java Mail writes the requested headers; the receiving server, mail client or user controls whether a receipt is returned. Delivery Status Notification, covered in the next section, is the separate SMTP-level mechanism for delivery status.

You can provide the receipt address explicitly. The no-argument methods use the first Reply-To recipient when present, or the From recipient otherwise.

Delivery Status Notification (DSN) asks the SMTP server for delivery-status reports such as failure, delay or success notifications. This is separate from read receipts: DSN is about delivery status at SMTP/server level.

DSN can be configured per email, through mailer defaults or through properties.

Simple Java Mail validates email addresses with JMail, which performs standards-aware checks rather than relying on a single regular expression. See RFC 2822 for one of the relevant specifications.

When sending, the mailer applies its defaults and overrides before checking the resulting email. Calling mailer.validate(email) directly runs the required sender and recipient checks, configured address validation, encoded-word protection and CRLF-injection scan against the supplied Email as it stands. MIME conversion and the final encoded-size check happen during sending.

See JMail for more examples and configurations.

clearEmailValidator() clears only the configurable JMail address policy. Required sender and recipient checks, encoded-word protection and CRLF injection scanning remain active.

disablingAllClientValidation(true) changes client-side validation findings into warnings so SMTP handling can continue. Use this mode when the application deliberately assigns the acceptance decision to the SMTP server.

With Simple Java Mail you can easily convert between email types. This includes reading S/MIME protected emails from file.

For example, if you need a MimeMessage, you can convert Email objects, EML data and even Outlook .msg files.

If you already have a MimeMessage, you can convert it into an Email instance with its addresses, content, embedded images, attachments, and non-structural custom headers preserved where possible. You can also parse just the metadata without fetching attachment data.

Conversion does not copy the original header block verbatim. Addressing, date, subject, reply, message ID, and MIME content headers are represented by Email fields or rebuilt when another MimeMessage is produced. Transport-history headers such as Received and Resent-*, along with obsolete structural metadata, are omitted. See the complete filtered-header list.

You can even build a mass Outlook .msg to EML converter if you like!

For Outlook .msg input, the String overload takes a file path. Use the File or InputStream overload for those source types.

When converting Outlook .msg files, use the result API if you need to inspect source-specific Outlook data. The converted email keeps only meaningful email headers; structural Outlook source headers stay available through OutlookMessageData.

withBounceTo(...) sets the SMTP envelope sender (MAIL FROM) for that email. Delivery failures are normally returned to this address. The setting is applied per message, so emails sent through the same Mailer can use different bounce addresses without changing its shared Session.

This is different from Reply-To, which is a message header used by mail clients when a recipient replies. The bounce address is used by mail servers during delivery and is not written into the outgoing message headers. A receiving mail system may record it in a Return-Path header. Only the address is used; a display name has no role in the SMTP envelope.

If you just want to do a connection test using your current configuration, including transport strategy and (authenticated) proxy, Simple Java Mail got you covered.

The connection test can also be done asynchronously and the result can be handled asynchronously as well. Take a look at Handling asynchronous mailing result.

If the mailer was configured with async(), no-arg testConnection() uses that async default. Use testConnection(false) when you need a blocking test.