simple-java-mail

Simple Java Mail

Simple to use. Built for the real world.

Simple Java Mail builds well-formed MIME through a streamlined Java API. That same API covers reusable message rules, transport security, DKIM, S/MIME, diagnostics, conversion, authenticated SOCKS, and advanced SMTP delivery.

Jakarta Mail provides the standard mail API, and Angus Mail provides its transport implementation. You can still supply a Session, access the generated MimeMessage, set raw Jakarta Mail properties, or provide the final send operation.

Get started · Capabilities · Modules · Javadocs · 9.2 migration guide · Compare libraries

Send a first email

Simple Java Mail is published to Maven Central. Start with simple-java-mail, the core dependency. Add a feature module only when you need it, using the same version as the core dependency. Java 8 is the source, target, and minimum supported runtime.

Maven

<dependency>
    <groupId>org.simplejavamail</groupId>
    <artifactId>simple-java-mail</artifactId>
    <version>9.3.10</version>
</dependency>

Gradle

implementation 'org.simplejavamail:simple-java-mail:9.3.10'

Build and send

Email email = EmailBuilder.startingBlank()
    .from("Sender", "[email protected]")
    .withRecipients(new RecipientBuilder()
        .withName("Recipient")
        .withAddress("[email protected]")
        .withType(Message.RecipientType.TO)
        .build())
    .withSubject("It works")
    .withPlainText("Your first Simple Java Mail message.")
    .buildEmail();

Mailer mailer = MailerBuilder.withSMTPServer(
        System.getenv("SMTP_HOST"),
        587,
        System.getenv("SMTP_USER"),
        System.getenv("SMTP_PASSWORD"))
    .withTransportStrategy(TransportStrategy.SMTP_TLS)
    .buildMailer();

mailer.sendMail(email);

The port and transport strategy must match your SMTP server. Build the Mailer once, reuse it, and close it during application shutdown. Before sending, mailer.testConnection() checks the SMTP path and mailer.validate(email) checks the message. The complete getting-started guide explains each step.

What the API handles

Job	Support
Messages and MIME	Plain text and HTML alternatives, embedded images, attachments, calendar content, headers, encodings, and the corresponding multipart structure.
Shared message rules	Recipient builders, address validation, defaults, enforced overrides, bounce addresses, receipts, and maximum message size.
Security	TLS and SMTPS, server identity and certificate checks, fixed or refresh-aware OAuth2 tokens, header-injection protection, DKIM, and S/MIME.
Delivery	Synchronous and asynchronous sends, a scoped open connection, simple batches, connection pools, and independently configured SMTP clusters.
Diagnostics	Connection tests, message validation, configuration inspection, Jakarta Mail debug routing, logging integrations, and SMTP submission replies.
Conversion and interoperability	Conversion between Email, MimeMessage, and EML, send-ready serialization, Outlook .msg conversion, and custom sending logic.

Configure once, reuse everywhere

A Mailer keeps SMTP settings, transport policy, defaults, overrides, validation, signing, proxy configuration, and delivery behavior out of individual call sites. Configure it with the Java builder API, property files, system properties, or environment variables, or let the Spring module create and inject it.

This leaves application code to describe each email while shared rules stay in one reusable place.

Add only what you need

Optional modules extend the same API and add their dependencies only when selected. Use the same Simple Java Mail version for every module. Some integration artifacts already depend on simple-java-mail; the modules guide notes when you do not need to declare it separately.

Requirement	Artifact
DKIM domain signing	dkim-module
S/MIME signing, encryption, and reading	smime-module
Pooled and clustered delivery	batch-module
Authenticated SOCKS proxies	authenticated-socks-module
Outlook .msg parsing and conversion	outlook-module
Spring-managed configuration	spring-module
Command-line sending and validation	cli-module
OSGi and Apache Karaf	karaf-module

The modules guide lists each coordinate, its main transitive dependencies, and the capabilities it enables.

Jakarta Mail remains available

Simple Java Mail handles the higher-level work involved in outbound email while keeping Jakarta Mail within reach. When needed, you can:

• build a mailer around your own Session;
• add raw Jakarta Mail properties;
• access the effective Session;
• convert an Email to a MimeMessage for inspection or integration;
• provide the final sending implementation.

Documentation by task

If you want to…	Start here
Send the first message	Get started
Build rich content and recipients	Capabilities
Configure an application	Configuration
Protect transport and message content	Security
Test, inspect, or diagnose a send	Diagnostics
Understand multipart structures	MIME and interoperability
Choose an optional artifact	Modules
Compare Java mail libraries	Comparison
Upgrade existing code	9.2 migration guide
Ask a question or contribute	Help and contribute

Current release

The current release is 9.3.10.

GitHub release · Maven Central artifacts · Migration guide · Complete release history

Read the migration guide before upgrading from an older release when source compatibility, defaults, security behavior, or configuration precedence matters to your application.

Develop and contribute

Simple Java Mail is open source under the Apache License 2.0. It was first published in 2009 and is maintained by Benny Bottema with contributions from its users and the surrounding open-source projects.

• Use the issue tracker for reproducible bugs and concrete feature ideas.
• Read DEVELOPMENT.md for the supported JDKs and local build setup.
• Read the project mechanisms catalogue before changing module loading, CLI metadata, MIME selection, proxy bridging, concurrency, or non-null instrumentation.
• Follow the API expansion workflow when adding a public field or builder method.
• Use Help and contribute to choose the right public channel or arrange private follow-up for a sensitive report.

License

Simple Java Mail is licensed under the Apache License 2.0.