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

Migrating to Simple Java Mail 6.0.0


A modular library

Impact: You shouldn't include 3rd party dependencies anymore in maven, but use the various modules instead. Also, most packages have been renamed or classes have been moved around.

Simple Java Mail is growing. In 5.0.0 the builder api was introduced to deal with ambiguous telescoping constructors, scattered documentation and immutability.

But as new features was supported, it wasn't enough. Code was getting difficult to understand and the burden to include the right optional 3rd party dependencies was on the end users. Something had to happen to ensure a healthy growth into the future. Enter the module system.

The project was divided into modules: a core module, containing the builder API and also interfaces for the optional modules to be invoked from the main module. Internally the core module uses a "Module Loader" to help invoke optional extra functionality.

Furthermore the individual optional modules each manage their own 3rd party dependencies. Users don't need to think about this anymore.

The decision which modules to create was straight forward: each function that had its own 3rd party dependencies became a module.

Simple Java Mail module overview

No 3rd party library is shaded into the main jar anymore


Until 6.0.0, a couple of 3rd party libraries were 'shaded' into the main jar and made part of the library that way. This practice has been removed and not only is the dependency managed externally now, it has been made optional.

This means that if you relied on this functionality, or even used these renamed classes you will have to inlcude the relevant module now instead and no longer use the renamed classes but the actual classes from the 3rd party library.


The Builder API and the CLI

Impact: To suit CLI usage better, Some email / mailer builder Java methods have been merged into one or have been renamed.

The CLI support works by directly translating the Builder API into CLI commands and options. However, not all methods were suitable for CLI because of the many variations or simply because of java types that don't translate well from CLI input.

So to provide a concise CLI api, some java methods were merged into a single one with more options while others remained untouched, but were excluded from CLI altogether in favor of the merged one (the merged one being a superset).


MimeMessage structure: not a one-size-fits-all anymore

Impact: If you operate on a MimeMessage object that was the result of an Email conversion, then the structure is not always the same anymore

Until now, Simple Java Mail operated under the assumption that as long as the generated email was properly structure conform the RFC, the most accommodating variant would always work in every email client. This was mostly true.

Until it wasn't. With 6.0.0 Simple Java Mail takes the perfect-fit approach and uses the exact mime message structural fit that matches the use case. Play around with the various possibilities below:

Configure your email:

Structure used for email:


Outlook support is not included by default anymore

As part of the modularisation, all 3rd party dependencies have been made optional through a module. This includes Outlook support, which was previously included by default. In fact it used to be 'shaded' into the main jar as if it was part of the source code. This has been removed.


Simple Java Mail now reverts to default server ports if omitted by the user

When not provided through the builder API, then the following default ports will now be applied:

default SMTP server port:25
default SMTPS server port:465
default TLS server port:587
default proxy server port:1080
default local proxy bridge:1081