Debian Codegraph @

doc/html/_sources/imap/developer/jmap.rst.txt

raw
1 .. _developer-jmap:
2
3 ============
4 JMAP support
5 ============
6
7 `JMAP <http://jmap.io/>`_ 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.
8
9 Cyrus administration
10 ====================
11
12 Compile JMAP support into Cyrus
13 -------------------------------
14
15 1. Enable JMAP (and DAV) in Cyrus:
16
17 * ``./configure --enable-http --enable-jmap --enable-xapian`` along with your other configuration options.
18
19 2. Enable :ref:`conversation support <imap-concepts-deployment-db-conversations>`
20
21 * In :cyrusman:`imapd.conf(5)`, set ``conversations: 1``, ``conversations_db: twoskip``
22 * Create a conversations.db for each user: ``ctl_conversationsdb -b -r``
23
24 3. JMAP depends on Xapian. For full support (to gain full word boundary
25 distinctions in CJK languages - Chinese, Japanese and Korean), this needs to be
26 manually compiled due to extra patches needing to be applied.
27 Our :ref:`Xapian install guide <imapinstall-xapian>` shows how.
28
29 4. Once installed, the ``jmap`` module must be enabled in
30 :cyrusman:`imapd.conf(5)`: ``httpmodules: jmap``
31
32 JMAP client
33 ===========
34
35 Test JMAP support
36 -----------------
37
38 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.
39
40 To obtain the JMAP mailbox folders for user ``test``, issue the following request:
41
42 .. code-block:: bash
43
44 curl -X POST \
45 -H "Content-Type: application/json" \
46 -H "Accept: application/json" \
47 --user test:test \
48 -d '{
49 "using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail" ],
50 "methodCalls": [[ "Mailbox/get", {}, "c1" ]]
51 }' \
52 http://localhost/jmap/
53
54 you should get a response which looks similar to
55
56 .. code-block:: none
57
58 {
59 "methodResponses": [
60 ["Mailbox/get", {
61 "state": "0",
62 "list": [{
63 "id": "7c76ec2b-9bd8-4091-a665-640e232e3877",
64 "name": "Inbox",
65 "parentId": null,
66 "myRights": {
67 "mayReadItems": true,
68 "mayAddItems": true,
69 "mayRemoveItems": true,
70 "mayCreateChild": true,
71 "mayDelete": false,
72 "maySubmit": true,
73 "maySetSeen": true,
74 "maySetKeywords": true,
75 "mayAdmin": true,
76 "mayRename": false
77 },
78 "role": "inbox",
79 "totalEmails": 0,
80 "unreadEmails": 0,
81 "totalThreads": 0,
82 "unreadThreads": 0,
83 "sortOrder": 1,
84 "isSubscribed": false
85 }, {
86 "id": "5d9e4f44-7df9-4489-b8b3-32625b552aa1",
87 "name": "Trash",
88 "parentId": null,
89 "myRights": {
90 "mayReadItems": true,
91 "mayAddItems": true,
92 "mayRemoveItems": true,
93 "mayCreateChild": true,
94 "mayDelete": true,
95 "maySubmit": true,
96 "maySetSeen": true,
97 "maySetKeywords": true,
98 "mayAdmin": true,
99 "mayRename": true
100 },
101 "role": null,
102 "totalEmails": 0,
103 "unreadEmails": 0,
104 "totalThreads": 0,
105 "unreadThreads": 0,
106 "sortOrder": 10,
107 "isSubscribed": true
108 }],
109 "notFound": [],
110 "accountId": "test"
111 }, "c1"]
112 ],
113 "sessionState": "0"
114 }
115
116 Similar requests exist to obtain contacts and calendars. For details, see the
117 JMAP specification.
118
119 Optional: Install sample JMAP client
120 ------------------------------------
121
122 .. note::
123
124 Cyrus does not yet implement JMAP authentication. Instead, it requires for
125 each request the HTTP Basic Auth header set with the account's username and
126 password. If you intend to use the JMAP perl or web clients, make sure to add
127 the required authentication headers for each request.
128
129 You can set up the `JMAP Proxy (perl) <https://github.com/jmapio/jmap-perl>`_ to sit in front of a standard IMAP server and query that over a custom JMAP client.
130
131 Or you can install a sample `JMAP web client <https://github.com/jmapio/jmap-demo-webmail>`_ which requires the `Overture.js library <https://github.com/fastmail/overture>`_ and `JMAP JS library <https://github.com/jmapio/jmap-js>`_ to talk to a JMAP-enabled Cyrus server and build from there (subject to the `MIT license <https://tldrlegal.com/license/mit-license>`_).
132
133 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.
134
135 Developing the client further
136 -----------------------------
137
138 You'll want to become deeply familiar with the `JMAP developer documentation <http://jmap.io/#i-want-to-get-involved-with-jmap.-what-do-i-need-to-know?>`_
139
140
141 .. note::
142
143 JMAP implementation in Cyrus is a work in progress. Current status can be
144 viewed on the main :ref:`JMAP configuration page <jmap-implementation>`.