Apache James: A Modular, JVM-Based Mail Server with JMAP Support

What James solves and who it is for

Apache James targets organizations and developers who need a mail server they can wire into custom business logic rather than a packaged product that treats email as an isolated system. The project description in its own repository states the goal: create your own solution for email treatment by assembling the components you need through an Inversion of Control platform, and customize filtering and routing rules using the Mailet Container.

This framing positions James differently from Postfix or Exim. Those are mail transfer agents optimized for reliable delivery. James is designed for teams who need to intercept, transform, route, and act on email inside a Java or Scala codebase. A developer who needs to trigger a workflow when a specific message arrives, filter attachments, or apply custom anti-spam logic has a programming API to do it.

Supported protocols are IMAP, SMTP, JMAP (the modern JSON-based mail protocol standardized at jmap.io), and POP3. JMAP support is a differentiator because most self-hosted mail servers have added it slowly or not at all. The distributed server variant focuses on easy-to-operate scalable mail processing on Cassandra, S3-compatible object storage, OpenSearch, and RabbitMQ.

Trying James with Docker in one command

The README offers a quick start that requires only Docker. It pulls a demo image with a default JPA-backed configuration (hsqldb and Lucene) and starts an IMAPS and SMTPS server with three default users:

docker run -p "465:465" -p "993:993" apache/james:demo-{latest_james_version}

The demo image ships with a default domain named james.local and users [email protected], [email protected], and [email protected], all with the password 1234. IMAPS listens on port 993 and SMTPS on port 465. The README uses the AsciiDoc variable {latest_james_version}, which resolves to the current release, as part of the image tag.

After running the container, connecting with a mail client such as Thunderbird demonstrates IMAP access. The README links to a tutorial that covers user and domain creation and Thunderbird setup in more detail.

This demo deployment is not suitable for production. It uses hsqldb as the database and stores mail in memory-backed storage. It is a way to verify that the protocols work and explore the command-line interface before committing to a deployment.

Deployment flavors: JPA versus distributed

James ships four supported deployment configurations, each as a Guice-based application.

The JPA plus Lucene setup is the simplest: a single-node mail server using Java Persistence API for storage, compatible with most relational databases. This is what the demo Docker image uses. It is suitable for moderate load where horizontal scaling is not needed.

The Cassandra plus OpenSearch setup adds distributed storage without requiring RabbitMQ. The distributed server, which combines Cassandra, RabbitMQ, S3-compatible object storage, and OpenSearch, is the most operationally complex and designed for scalable deployments. Documentation for the distributed server has its own dedicated site at james.staged.apache.org.

A memory-backed setup exists for testing only: it loses all state when stopped.

Choosing between these flavors is a meaningful architectural decision because the distributed flavor requires operating four separate backing services, each with their own operational characteristics. A team that picks it for a small deployment will pay ongoing maintenance costs disproportionate to the load.

Compiling from source and extending the server

Building James from source requires JDK 11 or higher and Maven version 3.6.1 or higher. Some parts are written in Scala, so an IDE Scala plugin may be needed for development.

Clone the repository:

git clone [email protected]:apache/james-project.git

Then run the Maven build from inside the cloned directory:

mvn clean install

Useful build options include -DskipTests to skip the long test suite (which requires a Docker daemon), -T 4 to parallelize across CPUs, and -Dmaven.javadoc.skip=true to skip Javadoc generation.

The examples/ directory holds code samples for common extension points: custom healthchecks, custom IMAP commands, custom Mailets for filtering and routing, custom SMTP commands and hooks, custom WebAdmin routes, OpenID Connect configuration, metrics export to Graphite, and an SMTP proxy. These examples are the practical entry point for anyone writing James extensions rather than reading through the full architecture documentation first.

The Mailet Container: where custom logic lives

The Mailet Container is the primary API for customizing mail processing in James. A Mailet is a Java component that receives a mail message and can inspect, modify, forward, store, or discard it. Mailets are composed into a processing pipeline, and the pipeline is defined through configuration rather than code changes.

This is the feature that separates James from a conventional MTA. A team that needs to parse incoming invoices, trigger a payment workflow, and archive the original message can do all of that in a Mailet without forking the mail server code.

The repository's examples/custom-mailets/ directory illustrates how to write and wire a Mailet. The pattern is similar to a Java servlet filter: implement an interface, register the Mailet in the configuration file, and deploy. The WebAdmin REST API provides runtime management without server restarts.

A competing approach for teams who only need SMTP relay and basic filtering is Postfix combined with a scripting layer like Sieve. Postfix is faster and simpler to operate for that use case; James trades simplicity for programmability in a JVM environment.

Project maintenance and license

Apache James is part of the Apache Software Foundation and licensed under Apache-2.0. The last push to the repository was on 2026-09-25. The project uses Apache JIRA for issue tracking, with labels for newbie, easyfix, and feature issues suitable for first-time contributors.

The project recommends Maven 3.6.1 as a minimum. Earlier James versions required upgrading through intermediate releases rather than jumping directly to the current version; the upgrade-instructions.md file at the repository root addresses this.

Jira issue labels and a Gitter channel are the primary contribution channels. The README asks for articles and blog posts about James experiences and provides a contact address for community engagement.

There are no GitHub releases listed in the repository's releases section. The README defines a version attribute at the top of the file, which is referenced in the Docker image tag and the documentation links. Docker images are maintained at hub.docker.com/r/apache/james.

Editorial conclusion

Apache James is the right choice for teams who need a JVM-based mail server they can extend programmatically through the Mailet API, or who need a distributed mail backend that scales on Cassandra without adopting a commercial product. It is the wrong choice for teams who want a simple SMTP relay or a mail server with a bundled graphical administration console; the management interface is CLI and WebAdmin REST API. Before deploying, confirm you need JDK 11 or higher in your environment, choose between the JPA and distributed deployment flavors based on your operational complexity budget, and read the upgrade-instructions.md file if you are migrating from an earlier version.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository