JMAP support

JMAP is an alternate mechanism for synchronising a mail client with a mail server, intended as a replacement for IMAP. It is a transport-agnostic, stateless JSON-based API, aiming to be compatible with the IMAP data model, but with reduced data usage and more efficient synchronisation.

Cyrus administration

Compile JMAP support into Cyrus

  1. Enable JMAP (and DAV) in Cyrus:

    • ./configure --enable-http --enable-jmap along with your other configuration options.
  2. Enable conversation support

    • In imapd.conf(5), set conversations: 1, conversations_db: twoskip
    • Create a conversations.db for each user: ctl_conversationsdb -b -r
  3. JMAP depends on Xapian. This needs to be manually compiled due to extra patches needing to be applied. Our Xapian install guide shows how.

  4. Once installed, the jmap module must be enabled in imapd.conf(5): httpmodules: caldav jmap tzdist

JMAP client

Test JMAP support

Once Cyrus is running, you can test JMAP on the command line for any existing Cyrus user. The user must at least have an INBOX provisioned but is not required to have any calendars, contacts or messages.

To obtain the JMAP calendars for user test, issue the following request:

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --user test:test \
     -d '[["getCalendars", {}, "#1"]]' \
     http://localhost/jmap

you should get a response which looks similar to

[
    [
        "calendars",
        {
            "accountId": "test@localhost",
            "list": [
                {
                    "color": "#FD8208FF",
                    "id": "Default",
                    "mayAddItems": true,
                    "mayDelete": true,
                    "mayModifyItems": true,
                    "mayReadFreeBusy": true,
                    "mayReadItems": true,
                    "mayRemoveItems": true,
                    "mayRename": true,
                    "name": "Default",
                    "sortOrder": 1,
                    "x-href": "/dav/calendars/user/test@localhost/Default"
                }
            ],
            "notFound": null,
            "state": "184"
        },
        "#1"
    ]
]

Similar requests exist to obtain contacts and messages. For details, see the JMAP specification.

Optional: Install sample JMAP client

Note

Cyrus does not yet implement JMAP authentication. Instead, it requires for each request the HTTP Basic Auth header set with the account’s username and password. If you intend to use the JMAP perl or web clients, make sure to add the required authentication headers for each request.

You can set up the JMAP Proxy (perl) to sit in front of a standard IMAP server and query that over a custom JMAP client.

Or you can install a sample JMAP web client which requires the Overture.js library and JMAP JS library to talk to a JMAP-enabled Cyrus server and build from there (subject to the MIT license.

The web client is a simple example (no compose, contacts or calendars). When you create your account, the most recent 50 emails will be downloaded in their entirety, so the first page should be snappy immediately. After that, you are redirected to the landing page. A background task will continue to pull in batches of messages and add them to your account, so you will see older messages appear while you are using the interface.

Developing the client further

You’ll want to become deeply familiar with the JMAP developer documentation

JMAP implementation in Cyrus

The JMAP implementation in Cyrus is at various stages of maturity.

Working

  • Contacts
    • All JMAP methods are implemented. JMAP blobs are not supported.
  • Calendars
    • All JMAP methods are implemented. JMAP blobs are not supported.
  • Messages
    • Most JMAP methods are implemented. The following methods are not planned for implementation: * copyMessages * reportMessages * getVacationResponse * setVacationResponse * getIdentityUpdates * setIdentities

Not yet implemented

  • Authentication
    • Cyrus does not yet implement the JMAP authentication workflow. All the JMAP methods in httpd currently require an account logged in via Basic Authentication.
  • Multi-user accounts

    All the current JMAP method operate with the account currently authenticated to Cyrus httpd. That is, the ‘accountId` property in JMAP requests is not supported.

  • Remote mailboxes

  • Events
    • Changes on mailbox entries trigger notifications. However, the JMAP event service is not implemented.