Installing and Configuring Apache James Email Server on Linux

This post is related to my instructional series on setting up Apache James as part of building baseline IT infrastructure for a startup or small business. The original post on installing Apache James used LDAP as the authentication back end in order to leverage common insfrastructure in a small business. This tutorial will use the default James backend using JPA with a Derby database, but the original instructions using LDAP as an authentication backend remain valid. Future posts may offer instruction on alternatives such as LDAP for auth and databases such as MySQL for the system backend.


You will need to have a current Java JDK installed on your system in order to run James. I think JDK 11 is the current suggested JDK release.

Getting James

As before, the easiest way to get James running is to download the binary archive from the Apache James project website. The current release is 3.6.0. Since it is built in Java, the download is the same for all platforms.

Apache James 3.6.0


Use the SHA-512 link to download hash verification so you can verify the authenticity of the binary archive.

Initial Startup

Unzip the archive into a working folder. In Linux I like to use ~/opt or ~/Applications, just put it somewhere you can access it easily. You can run an initial test right there from the bin folder inside the application folder.

$ cd ~/opt/james-server-app-3.6.0/bin
$ sudo ./james console

Because it outputs all debug info to the console, I like to use the console option starting James when I am first getting the server setup. You should see a scrolling list of debug info go by as the server starts. If you see errors and the server shuts off, you know there is a bug in the configuration.

Once you have the application running, you can use the CLI to add domains and users.

$ ./ -h localhost -p 9999 adddomain
$ ./ -h localhost -p 9999 adduser <password>

Make sure to put your password in the spot.

You can test your account access using the CLI, but I find the easiest way to check if an account is working is to set up the account in Thunderbird, Evolution, or some other desktop email client. That way I can easily check connectivity, message relaying, etc. again and again as I am updating my configuration. Before you add the account, add a DNS entry to /etc/hosts for the domain you are configuring to point to If you have a name for a mail server, go ahead and add an entry for it as well. Unless you are configuring the system on a live server, you want the email domain and the mail server to be directed to localhost while you are testing the configuration.

Note that James uses standard ports for services, so your incoming (IMAP) and outgoing (SMTP) server settings will look something like this:

IMAP server:
IMAP port: 143

SMTP server:
SMTP port: 25

James does not requires SMTP authentication by default, so you can leave that unchecked.

Configuring Apache James

Putting together a production-ready James email server involves, at a minimum, configuring a couple of things:

  1. DKIM - a system that uses DNS and public/private key cryptography to ensure that the email server sending a message is the actual email server for the domain in question. DKIM (mostly) solved an early weakness of email that made it easy for spammers to fake where emails originated.
  2. SSL encryption for connections - As with the Web, in the early days, email was not encrypted. That is no longer a sustainable model, and traffic should be encrypted on your server. Fortunately, Let’s Encrypt has made it a quick, easy, and free thing to obtain a public SSL certificate.

And optionally:

  1. SPF - Sender Policy Framework defines, again using DNS, what servers may send email for a given domain.


James does not currently have a DMARC implementation, though this feature has been discussed and is listed in the issues list for James Server. DMARC combines DKIM and SPF to further reduce message spoofing and phishing attacks.

I will cover the details of SSL, DKIM, and SPF in a followup post.