Java Virtual Machine

James requires a Java Runtime Environment. Java version 1.6 or higher is required to run the James application. The exact JREs available depends on the platform. In addition, the environment variable JAVA_HOME should be set to the JRE home directory before running James.

If you run JDK7, James will not start due to a bug in JAXB. As temporary workaround, you can download the latest 2.1 version of JAXB from and copy the extracted jaxb-impl.jar into conf/lib.

James 3.0 has been successfully tested on OpenJDK, Sun JDK and IBM JDK

User Privileges

On Linux/Unix platforms, root access will be required to run James (access to ports below 1024 is generally restricted to the root user). As SMTP, POP3, and IMAP4 need to open server sockets on such ports in standard configurations, James requires root access.

On Windows platforms, you also need to run James as Administrator privilege.


On Linux, to run the startup/shutdown script via the 'james' command, you also need libc6 (on Ubuntu for example: sudo apt-get install libc6-i386 libc6-dev-i386).

System Resources

Obviously James also requires sufficient disk space, processor power, and network bandwidth. But, other than what's been discussed here, it has no additional special requirements.

James is configured to run with 512 MB RAM (-Xmx512M in the bat/sh) available, but may need more or less depending on the load. With the default configuration, JVM can use until 512M (It does not mean it will do). It really depends on your traffic, and also which mailbox you will use (you can save much memory if you don't use the default embedded derby database but an external database of your choice). Work is still done to minimize the needed memory.

Build instructions

Checkout code from the chosen version on GitHub. Follow README instructions about compilation.

    Using these instructions, you can build the following images:
  • Guice + JPA + Lucene
  • Guice + Cassandra + ElasticSearch
  • Guice + Cassandra + ElasticSearch + LDAP
  • Spring

Alternatively, if you don't want your build to be handled via Docker, you can follow Guice Cassandra quick-start

A docker-compose is available for Guice + Cassandra + ElasticSearch

Install Step by Step

This guide documents how to install a Spring flavoured JAMES server.

Step 1: Download James

Obtain the full James binary (or source) distribution from the James release mirrors.

If you have downloaded a binary distribution, you do not need to build James. Proceed directly to Step 2.

If you have downloaded a source package, process first to the build and come back to Step 2.

Step 2: Deploy James

Unpack the archive into your James installation directory.

Step 3: Configure James

After unpacking the binary, the next step is to adjust the initial configuration. All configuration files are embedded in jars. We ship in the conf folder template configuration files.

You can override the default configuration : copy the conf folder any ...-template... you need and update according to your needs.

Additional system files reside under the./conf/META-INF folder.

The out of the box configuration makes certain assumptions and has some default values that are unlikely to be appropriate for real-world servers. There are a few issues that should be addressed immediately upon installation:

  • Postmaster Address - Change according to your need - read more.
  • Most UNIX systems require superuser privileges to open sockets below 1024, which includes the IANA-standard SMTP (on port 25), POP3 (on port 110) and IMAP4 (on port 143). These default ports can be changed in the conf file (read for pop3, smtp and imap4. Obviously, you would then need to reconfigure your clients. This may not be an option if you want to receive mail from external mail servers.

In addition to adjusting these parameters, you may wish to consult the documentation for a discussion of all other configurations. A list of such configurations, as well as the steps necessary to configure them, can be found here.

Step 4: Start James

Go to the bin subdirectory of the installation directory and run $ ./james start.

Running $ ./james help help will provide the list of commands you can invoke.

Once started, you'll see in the log file (./logs/james-server.log) that James is running. This means that Spring has loaded James and is now waiting for a request.

Step 5: Create Domains and Users

Finally, after launch, it will be necessary to create domain and user accounts before the James server will be fully operational. Read instructions on creating domains and user accounts.

Since at the beginning James is empty, it will not have any domain (except the default one)nor local users registered.

To register a local domain and user, cd bin and type Follow the given instructions

Invoke " adddomain <mydomain.tls> <mydomain.tls> is the domain name of the domain you wish to create.

Invoke " adduser <user> <password>" where <user> is the user name and <password> is the password of the account you wish to create.

Please note that the user name MUST be a complete email address of the form <user>@<domain> (where <domain> is any of the values specified in the <servernames> block of XMLDomainList or a domain defined via the domain management).

Step 6: Test James

Once you have some local users registered, try sending mail to one of them with SMTP (port 25).

$ telnet 25
Connected to localhost.
Escape character is '^]'.
220 SMTP Server (JAMES SMTP Server 3.0.0) ready Wed, 20 Jul 2017 17:31:33 +0100 (CET)
ehlo test
250- Hello test ( [])
250 2.1.0 Sender <YOUR_NAME@YOUR_DOMAIN> OK
250 2.1.5 Recipient <YOUR_NAME@YOUR_DOMAIN> OK
354 Ok Send data ending with <CRLF>.<CRLF>
subject: test

this is a test
250 2.6.0 Message received
Connection closed by foreign host.

Try now to retrieve that mail using POP3 (port 110) or IMAP (port 143).

Trace out James actions in ./logs/james-server.log.

Actions that will be taken by James on incoming mail are configured in the mailet pipe line (./conf/mailetcontainer.xml). Look at it if you want to understand what's happening.