JMAP configuration

JMAP is intended to be a new standard for email clients to connect to mail stores. It therefore intends to primarily replace IMAP + SMTP submission. It is also designed to be more generic. It does not replace MTA-to-MTA SMTP transmission.

Cassandra Guice proposes a JMAP implementation.

jmap.properties

Consult jmap.properties in GIT to get some examples and hints.


enabled
true/false. Governs whether JMAP should be enabled
jmap.port
Optional. Defaults to 80. The port this server will be listening on. This value must be a valid port, ranging between 1 and 65535 (inclusive)
tls.keystoreURL
Keystore to be used for generating authentication tokens for password authentication mechanism. This should not be the same keystore than the ones used by TLS based protocols.
tls.secret
Password used to read the keystore
jwt.publickeypem.url
Optional. JWT tokens allows request to bypass authentication
url.prefix
Optional. Configuration urlPrefix for JMAP routes.
Default value: http://localhost.
websocket.url.prefix
Optional. URL for JMAP WebSocket route
Default value: ws://localhost
upload.max.size
Optional. Configuration max size Upload in new JMAP-RFC-8621.
Default value: 30M. Supported units are B (bytes) K (KB) M (MB) G (GB).
email.send.max.size
Optional. Configuration max size for message created in both JMAP Draft amd RFC-8621.
Default value: None. Supported units are B (bytes) K (KB) M (MB) G (GB).
view.email.query.enabled
Optional boolean. Defaults to false.
Should simple Email/query be resolved against a Cassandra projection, or should we resolve them against ElasticSearch? This enables a higher resilience, but the projection needs to be correctly populated.
jmap.version.default
Optional string. Defaults to draft. Allowed values: draft, rfc-8621.
Which version of the JMAP protocol should be served when none supplied in the Accept header. Defaults to draft for legacy reasons (avoid breaking changes) but setting the value to rfc-8621 allow compatibility with other third party apps.

Wire tapping

Enabling TRACE on org.apache.james.jmap.wire enables reactor-netty wiretap, logging of all incoming and outgoing requests, outgoing requests. This will log also potentially sensible information like authentication credentials.

JMAP-draft vs JMAP-RFC-8621

James had been supporting an implementation based on an early specification of JMAP, what we call here JMAP-draft version. But the protocol went under a lot of changes until its finalization as an official RFC.

The finalized version of JMAP regarding the core specifications [RFC-8620] and the mail specifications [RFC-8621] are being currently implemented in James (JMAP-RFC-8621 version). It's supposed to replace at term the JMAP-draft version.

Meanwhile, both versions will be available. The version by default will be JMAP-draft during the time it takes to implement the new version. If you want to use a specific version for a request, you will need to add an extra jmapVersion field in your Accept header of your JMAP request:

  • JMAP-draft: Accept: application/json; jmapVersion=draft
  • JMAP-RFC-8621: Accept: application/json; jmapVersion=rfc-8621

Annotated specification

The annotated documentation presents the limits of the JMAP RFC-8621 implementation part of the Apache James project. We furthermore implement JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket.

Some methods / types are not yet implemented, some implementations are naive, and the PUSH is not supported yet.

Users are invited to read these limitations before using actively the JMAP RFC-8621 implementation, and should ensure their client applications only uses supported operations.

Contributions enhancing support are furthermore welcomed.

    The list of tested JMAP clients are:
  • OpenPaaS is actively using the draft version of the JMAP implementation. Migration to RFC-8621 is planned.
  • Experiments had been run on top of LTT.RS. Version in the Accept headers needs to be explicitly set to `rfc-8621`. Read more.