Server Wide Configuration


There are a number of global configuration files that do not fall into any one component. They have effects that are global in scope across the server.

Some of these files are crucial, while others can be ignored by any but the most sophisticated server administrators.


In James distribution, the spring files are located under conf/context folder and splitted into a main file (james-server-context.xml) which imports 3 other files (1 per mailbox type): james-mailbox-jpa-context.xml, james-mailbox-memory-context.xml.

Consult spring-server.xml in GIT to get some examples and hints.

spring beans files are the place where the Apache James Server wiring is done. It should be modified only by expert-users.

In combination with and META-INF/persistence.xml, the datasource to access the database is defined in spring-server.xml

This configuration file is only relevant when using JPA, with Spring or Guice.

Consult in GIT to get some examples and hints.

The database connection in

James has the capacity to use a JDBC-compatible database for storage of both message and user data. This section explains how to configure James to utilize a database for storage.

To avoid vendor-specific issues, the JPA (Java Persistence Architecture) is used (using the Apache OpenJPA implementation).

There must be a database instance accessible from the James server. An account with appropriate privileges (select, insert, delete into tables, and on initial startup creation of tables) and with sufficient quota for the data to be inserted into the database must be available.

Also, since James will use JDBC to access the database, an appropriate JDBC driver must be available for installation. You can place the JDBC driver jar in the conf/lib folder, it will be automatically loaded.

Database configuration

The class name of the database driver to be used.
The JDBC connection URL for your database/driver.
The user id of the database account to be used by this connection.
The password of the database account to be used by this connection.
true or false - Use streaming for Blobs. This is only supported on a limited set of databases atm. You should check if its supported by your DB before enable it. See (#7.11. LOB Streaming).

The JPA datasource handling is delegated to commons-dbcp, some of dbcp properties can be configured through The corresponding definitions and default values can be found in the dbcp documentation

  • datasource.testOnBorrow
  • datasource.validationQueryTimeoutSec
  • datasource.validationQuery
  • datasource.maxTotal

Note for postgresql databases: Add standard_conforming_strings=off to your postgresql.xml, otherwise you will get ""Invalid escape string Hint: Escape string must be empty or one character. {prepstmnt 174928937 SELECT t0.mailbox_id, t0.mailbox_highest_modseq, t0.mailbox_last_uid, t0.mailbox_name, t0.mailbox_namespace, t0.mailbox_uid_validity, t0.user_name FROM public.james_mailbox t0 WHERE (t0.mailbox_name LIKE ? ESCAPE '\\' AND t0.user_name = ? AND t0.mailbox_namespace = ?) [params=?, ?, ?]} [code=0, state=22025]"


Consult META-INF/persistence.xml in GIT to get some examples and hints.

The JPA mapping and properties are defined in the in META-INF/persistence.xml.

You can override the definition in external file and importing the external file in the persistence.xml (see jpa-mappings.xml provided example in GIT)


Consult in GIT to get some examples and hints.

This is used to configure the JMX MBean server via which all management is achieved (also used by via the james-cli).

(Guice only). Boolean. Should the JMX server be enabled? Defaults to `true`.
The IP address (host name) the MBean Server will bind/listen to.
The port number the MBean Server will bind/listen to.

To access from a remote location, it has been reported that is needed in the startup script.

JMX Security

Guice only

In order to set up JMX authentication, we need to put jmxremote.password and jmxremote.access file to /conf directory.

jmxremote.password: define the username and password, that will be used by the client (here is james-cli)

File's content example:

                james-admin pass1

jmxremote.access: define the pair of username and access permission

File's content example:

                james-admin readwrite

When James runs with option -Djames.jmx.credential.generation=true, James will automatically generate jmxremote.password if the file does not exist. Then the default username is james-admin and a random password. This option defaults to true.


Consult sqlResources.xml in GIT to get some examples and hints.

This file is deprecated but some mailets... still need it. The standard way to access database is JPA, but some functionalities are not yet migrated and still need the sqlResources.xml resources.

The precise SQL statements used by Apache James Server to modify and view data stored in the database are specified in sqlResources.xml file.

If you are using a SQL database with unusual SQL commands or data types, you may need to add special entries to this file. The James team does try to keep sqlResources.xml updated, so if you do run into a special case, please let us know.

Also, if the database tables are not created a priori, but rather are to be created by James upon startup, special attention should be paid to the "create table" statements in this file. Such statements tend to be both very database and very database instance specific.

This configuration file is only relevant when using Guice.

It may contain any additional system properties for tweaking JVM execution. When you normally would add a command line option, you can put it in this file as instead. These properties will be added as system properties on server start.

Note that in some rare cases this might not work, when a property affects very early JVM start behaviour.

For testing purposes, you may specify a different file path via the command line option -Dextra.props=/some/other/

Some tuning can be done via system properties. This includes:

(Optional). String (size, integer + size units, example: `12 KIB`, supported units are bytes KIB MIB GIB TIB). Defaults to 100KIB.
This governs the threshold MimeMessageInputStreamSource relies on for storing MimeMessage content on disk.
Below, data is stored in memory. Above data is stored on disk. Lower values will lead to longer processing time but will minimize heap memory usage. Modern SSD hardware should however support a high throughput. Higher values will lead to faster single mail processing at the cost of higher heap usage.
Optional. Boolean. Defaults to false. Recommended value is false.
Should MimeMessageWrapper use a copy of the message in memory? Or should bigger message exceeding james.message.memory.threshold be copied to temporary files?
Optional. Allowed values are: none, simple, advanced, testing. Defaults to simple.
Mode level of resource leak detection. It is used to detect a resource not be disposed of before it's garbage-collected. Example `MimeMessageInputStreamSource`
- none: Disables resource leak detection.
- simple: Enables output a simplistic error log if a leak is encountered and would free the resources (default).
- advanced: Enables output an advanced error log implying the place of allocation of the underlying object and would free resources.
- testing: Enables output an advanced error log implying the place of allocation of the underlying object and rethrow an error, that action is being taken by the development team.
Optional. Boolean. Defaults to true.
Should we add the host in the MDC logging context for incoming IMAP, SMTP, POP3? Doing so, a DNS resolution is attempted for each incoming connection, which can be costly. Remote IP is always added to the logging context.