forked from jmapio/jmap
-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathspec.html
More file actions
1776 lines (1278 loc) · 125 KB
/
spec.html
File metadata and controls
1776 lines (1278 loc) · 125 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:400italic,400,700' rel='stylesheet' type='text/css'>
<link href="main.css" rel="stylesheet" type="text/css">
<title>JSON Mail Access Protocol Specification (JMAP)</title>
</head>
<body>
<header>
<div id="logo">JMAP</div>
<ul id="nav">
<li class="nav-item"><a class="nav-link" href="index.html">Intro</a></li>
<li class="nav-item"><a class="nav-link" href="spec.html">The Spec</a> </li>
<li class="nav-item"><a class="nav-link" href="client.html">Using JMAP</a></li>
<li class="nav-item"><a class="nav-link" href="server.html">Implementing JMAP</a></li>
</ul>
<a id="github" href="https://github.com/neilj/jmap"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
</header>
<article>
<h1>JMAP: The Spec</h1>
<div id="last-update">Last updated 2014-10-15</div>
<p>This is a specification. It is meant to be readable but it also has to be comprehensive, so it can be dense in places. If you want to get a quick idea of how JMAP works, you should probably read the <a href="client.html">guide for client developers</a> first. This has lots of example exchanges and should give you a good feel for what JMAP is all about. The spec is heavier going; it attempts to document exactly what each method should do, and what should happen in a myriad of edge cases.</p>
<p>There are undoubtably edge cases that are not yet covered. If you find one, please email <a href="mailto:editor@jmap.io">editor@jmap.io</a> or make a pull request on GitHub if you have a proposed fix.</p>
<p>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in <a href="https://tools.ietf.org/html/rfc2119">RFC2119</a>.</p>
<h2>The JSON API model</h2>
<p>JSON is a text-based data interchange format as specified in <a href="https://tools.ietf.org/html/rfc4627">RFC4627</a>. All data sent from the client to the server or from the server to the client MUST be valid JSON according to the RFC, encoded in UTF-8.</p>
<h3>The structure of an exchange</h3>
<p>The client initiates an API request by sending the server a JSON array. Each element in this array is another array and constitutes passing a <strong>message</strong> to the server. The server will process this and return a response consisting of an array of messages in the same format. A message array always contains three elements:</p>
<ol>
<li>The <strong>name</strong> of the message, a <code>String</code> specifiying the method to be called on the server, or the type of response being sent to the client.</li>
<li>An <code>Object</code> containing <em>named</em> <strong>arguments</strong> for that method or response.</li>
<li>A <strong>client id</strong>, an arbitrary <code>String</code> to be echoed back with the responses emitted by that method call (as we’ll see lower down, a method may return 1 or more responses, especially as some methods make implicit calls to other ones).</li>
</ol>
<p>Example query:</p>
<pre><code>[
["method1", {"arg1": "arg1data", "arg2": "arg2data"}, "#1"],
["method2", {"arg1": "arg1data"}, "#2"],
["method3", {}, "#3"]
]
</code></pre>
<p>The method calls MUST be processed sequentially, in order. Each API request
(which, as shown, may contain multiple method calls) receives a JSON
response in exactly the same format. The output of the methods MUST be added
to the array in the same order in which the methods are processed.</p>
<p>Example response:</p>
<pre><code>[
["responseFromMethod1", {"arg1": 3, "arg2": "foo"}, "#1"],
["responseFromMethod2", {"isBlah": true}, "#2"],
["anotherResponseFromMethod2", {"data": 10, "yetmoredata": "Hello"}, "#2"],
["aResponseFromMethod3", {}, "#3"]
]
</code></pre>
<h3>Errors</h3>
<p>If the data sent as an API request is not valid JSON or does not match the structure above, an error will be returned at the transport level. For example, when using JMAP over HTTP, a <code>400 Bad Request</code> error will be returned at the HTTP level.</p>
<p>Possible errors for each method are specified in the method descriptions. If a method encounters an error, an <code>error</code> message must be inserted at the current point in the response and, unless otherwise specified, no further processing must happen within that method.</p>
<p>Any further method calls in the request MUST then be processed as normal.</p>
<p>An <code>error</code> message looks like this:</p>
<pre><code>["error", {
type: "unknownMethod"
}, "client-id"]
</code></pre>
<p>The response name is <code>error</code>, and it has a type property as specified in the method description. Other properties may be present with further information; these are detailed in the method descriptions where appropriate.</p>
<p>If an unknown method is called, an <code>unknownMethod</code> error (this is the type shown in the example above) must be inserted and then the next method call processed as normal.</p>
<h3>Security</h3>
<p>As always, the server must be strict about data received from the client. Arguments need to be checked for validity; a malicious user could attempt to find an exploit through the API. In case of invalid arguments (unknown/insufficient/wrong type for data etc.) the method should return an <code>invalidArguments</code> error and terminate.</p>
<h3>Concurrency</h3>
<p>To ensure the client always sees a consistent view of the data, the state accessed by a method call must not change during the execution of the method, except due to actions by the method call itself. The state may change in-between method calls (even within a single API request).</p>
<h3>The Number datatype</h3>
<p>The JSON datatypes are limited to those found in JavaScript. A <code>Number</code> in JavaScript is represented as a signed double (64-bit floating point). However, except where explicitly specified, all numbers used in this API are integers and MAY be represented in a 64-bit integer.</p>
<h3>The Date datatype</h3>
<p>Where the API specifies <code>Date</code> as a type, it means a string in the following format: <code>YYYY-MM-DDThh:mm:ssZ</code>, e.g. <code>"2013-10-30T14:12:00Z"</code>. All dates MUST be in UTC time.</p>
<h3>CRUD methods</h3>
<p>JMAP defines various types of objects and provides a uniform interface for creating, retrieving, updating and deleting them. A <strong>data type</strong> is a collection of named, typed properties, just like the schema for a database table. Each row of the table is a <strong>record</strong>. For a <code>Foo</code> data type, records of that type would be fetched via a <code>getFoos</code> call and modified via a <code>setFoos</code> call. Delta updates may be fetched via a <code>getFooUpdates</code> call. These methods all follow a standard format as described below.</p>
<h3>getFoos</h3>
<p>Objects of type <strong>Foo</strong> are fetched via a call to <em>getFoos</em>. Methods starting with <code>get</code> MUST NOT alter state on the server.</p>
<p>This method may take some or all of the following arguments. The getter for a particular data type may not implement all of the arguments (for example if the data type only has two properties, there is little point in being able to just return one of them etc.); see the docs of the type in question. However, if one of the following arguments is available, it will behave exactly as specified below.</p>
<ul>
<li><p><strong>ids</strong>: <code>String[]</code></p>
<p>The ids of the Foo objects to return. For data types where there will never be that many records this may be optional, in which case <strong>all</strong> records of the data type are returned if it is omitted.</p></li>
<li><p><strong>properties</strong>: <code>String[]|null</code></p>
<p>If supplied, only the properties listed in the array are returned for each Foo object. If <code>null</code>, all properties of the object are returned. The id of the object is <strong>always</strong> returned, even if not explicitly requested. For compatibility with possible future extensions, the server MUST simply ignore any unknown properties in the list.</p></li>
<li><p><strong>sinceState</strong>: <code>String</code> (optional)</p>
<p>The <em>state</em> argument from a <em>foos</em> response may be passed back to future <em>getFoos</em> calls as the <em>sinceState</em> argument. If the current state is the same, the server SHOULD skip fetching the records and return a result indicating there is no change (this is essentially like an ETag). Most types support the more sophisticated <em>getFooUpdates</em> call instead to allow for delta updates. However, for small collections of data that change infrequently, this might be used. If available, this argument is always optional.</p></li>
</ul>
<p>The response to <code>getFoos</code> is called <code>foos</code>. It has the following arguments:</p>
<ul>
<li><p><strong>state</strong>: <code>String</code></p>
<p>A string representing the state on the server for <strong>all</strong> the data of this type. If the data changes, this string will change. It is used to get delta updates, if supported for the type.</p></li>
<li><p><strong>list</strong>: <code>Foo[]|null</code></p>
<p>An array of the Foo objects requested. This is the <strong>empty array</strong> if no objects were requested, or none were found. If <em>sinceState</em> was supplied and it is identical to the current state, this property is <code>null</code>.</p></li>
<li><p><strong>notFound</strong>: <code>String[]|null</code></p>
<p>This array contains the ids passed to the method for records that do not exist.</p></li>
</ul>
<h3>getFooUpdates</h3>
<p>When the state of the set of Foo records changes on the server (whether due to creation, updates or deletion), the <em>state</em> property of the <em>foos</em> response will change. The server may also be able to push a notification to the client that the state has changed for this type; see the separate JMAP push notification spec (TODO) for details on this.</p>
<p>The <em>getFooUpdates</em> call allows a client to efficiently update the state of any its Foo cache to match the new state on the server. It takes the following arguments:</p>
<ul>
<li><p><strong>sinceState</strong>: <code>String</code></p>
<p>The current state of the client. This is the string that was returned as the <em>state</em> argument in the <em>foos</em> response. The server will return the changes made since this state.</p></li>
<li><p><strong>maxChanges</strong>: <code>Number</code> (optional)</p>
<p>The maximum number of changed Foos to return in the response. See below for a more detailed description.</p></li>
<li><p><strong>fetchFoos</strong>: <code>Boolean</code></p>
<p>If <code>true</code>, after outputting the <em>fooUpdates</em> response, the server will make an implicit call to <em>getFoos</em> with the <em>changed</em> property of the response as the <em>ids</em> argument.</p></li>
<li><p><strong>fetchFooProperties</strong>: <code>String[]|null</code></p>
<p>If the <em>getFoos</em> method takes a <em>properties</em> argument, this argument is passed through on implicit calls (see the <em>fetchFoos</em> argument).</p></li>
</ul>
<p>If there are too many changes on the server and the client is only keeping a partial cache, it may be more efficient for the client to just invalidate its entire cache and fetch what it needs on demand. The <em>maxChanges</em> argument allows the client to tell the server the maximum number of changes to send back. If the server has the capability to return just the updates to an intermediate state, it should return a standard <em>fooUpdates</em> response, but set the <em>hasMoreUpdates</em> argument to <code>true</code> to indicate that <em>newState</em> is not the current server state, and so the client may call <em>getFooUpdates</em> again to get further changes. In this instance, the client MUST be able to get the full set of changes by repeatedly calling <em>getFooUpdates</em> until <code>hasMoreUpdates == false</code>. The same Foo id MAY appear in more than one of these partial updates. If the server is not able to support this, it may instead return a <code>tooManyChanges</code> error if the number of changes exceeds the <em>maxChanges</em> argument. The client can treat this like a <code>cannotCalculateUpdates</code> error and invalidate its entire Foo cache.</p>
<p>The response to <em>getFooUpdates</em> is called <em>fooUpdates</em>. It has the following arguments:</p>
<ul>
<li><p><strong>oldState</strong>: <code>String</code></p>
<p>This is the <em>sinceState</em> argument echoed back; the state from which the server is returning changes.</p></li>
<li><p><strong>newState</strong>: <code>String</code></p>
<p>This is the state the client will be in after applying the set of changes to the old state.</p></li>
<li><p><strong>changed</strong>: <code>String[]</code></p>
<p>An array of Foo ids for records which have been created or changed but not destroyed since the oldState.</p></li>
<li><p><strong>removed</strong>: <code>String[]</code></p>
<p>An array of Foo ids for records which have been destroyed since the old state.</p></li>
<li><p><strong>hasMoreUpdates</strong>: <code>Boolean</code></p>
<p>Indicates that <em>newState</em> is not the current server state and the client may fetch more changes by calling <em>getFooUpdates</em> again.</p></li>
</ul>
<p>If a Foo record has been modified AND deleted since the oldState, the server should just return the id in the <em>removed</em> response, but MAY return it in the changed response as well. If a Foo record has been created AND deleted since the oldState, the server should remove the Foo id from the response entirely, but MAY include it in the <em>removed</em> response, and optionally the <em>changed</em> response as well.</p>
<p>The following errors may be returned instead of the <em>fooUpdates</em> response:</p>
<p><code>invalidArguments</code>: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A <em>description</em> property MAY be present on the response object to help debug with an explanation of what the problem was.</p>
<p><code>tooManyChanges</code>: Returned if there are more changes the the client’s <em>maxChanges</em> argument, and the server is unable to return an update to an intermediate state. The client MAY retry with a higher max changes, (but with <code>fetchFoos:false</code> perhaps to limit the data transfer). Alternatively, the client can invalidate its Foo cache.</p>
<p><code>cannotCalculateChanges</code>: Returned if the server cannot calculate the changes from the state string given by the client. Usually due to the client’s state being too old. The client MUST invalidate its Foo cache.</p>
<h3>setFoos</h3>
<p>Modifying the state of Foo objects on the server is done via the <em>setFoos</em> method. This encompasses creating, updating and destroying Foo records. This has two benefits:</p>
<ol>
<li>It allows the server to sort out ordering and dependencies that may exist if doing multiple operations at once (for example to ensure there is always a minimum number of a certain record type).</li>
<li>Only a single call is required to make all changes to a particuar type, so the <em>ifInState</em> requirement will not be invalidated by a previous method call in the same request.</li>
</ol>
<p>The <em>setFoos</em> method takes the following arguments:</p>
<ul>
<li><p><strong>ifInState</strong>: <code>String</code> (optional)</p>
<p>This is a state string as returned by the <em>getFoos</em> method. It is always optional to supply this argument. If supplied, the string must match the current state, otherwise the method will be aborted and a <code>stateMismatch</code> error returned.</p></li>
<li><p><strong>create</strong>: <code>String[Foo]</code> (optional)</p>
<p>A map of <em>creation id</em> (an arbitrary string set by the client) to Foo objects (containing all properties except the id, unless otherwise stated in the specific documentation of the data type).</p></li>
<li><p><strong>update</strong>: <code>String[Foo]</code> (optional)</p>
<p>A map of id to a Foo object. The object may omit any property; only properties that have changed need be included.</p></li>
<li><p><strong>destroy</strong>: <code>String[]</code> (optional)</p>
<p>A list of ids for Foo objects to permanently delete.</p></li>
</ul>
<p>Each create, update or destroy is considered an atomic unit. It is permissible for the server to commit some of the changes but not others, however it is not permissible to only commit part of an update to a single record (e.g. update a <em>name</em> property but not a <em>count</em> property, if both are supplied in the update object).</p>
<p>If a create, update or destroy is rejected, the appropriate error should be added to the notCreated/notUpdated/notDestroyed property of the response and the server MUST continue to the next create/update/destroy. It does not terminate the method.</p>
<p>Some record objects may hold references to others (foreign keys). When records are created or modified, they may reference other records being created <em>in the same API request</em> by using the creation id prefixed with a <code>#</code>. The order of the method calls in the request by the client MUST be such that the record being referenced is created in the same or an earlier call. The server thus never has to look ahead. Instead, while processing a request (a series of method calls), the server MUST keep a simple map for the duration of the request of creation id to record id for each newly created record, so it can substitute in the correct value if necessary in later method calls.</p>
<p>The response to <em>setFoos</em> is called <em>foosSet</em>. It has the following arguments:</p>
<ul>
<li><p><strong>oldState</strong>: <code>String</code></p>
<p>The state string that would have been returned by <em>getFoos</em> before making the requested changes.</p></li>
<li><p><strong>newState</strong>: <code>String</code></p>
<p>The state string that will now be returned by <em>getFoos</em>.</p></li>
<li><p><strong>created</strong>: <code>String[Foo]</code> (optional)</p>
<p>A map of the creation id to an object containing any <strong>server-assigned</strong> properties of the Foo object (including the id) for all successfully created records, omitted if none.</p></li>
<li><p><strong>updated</strong>: <code>String[]</code> (optional)</p>
<p>A list of Foo ids for records that were successfully updated, omitted if none.</p></li>
<li><p><strong>destroyed</strong>: <code>String[]</code> (optional)</p>
<p>A list of Foo ids for records that were successfully destroyed, omitted if none.</p></li>
<li><p><strong>notCreated</strong>: <code>String[SetError]</code> (optional)</p>
<p>A map of creation id to a SetError object for each record that failed to be created, omitted if none. The possible errors are defined in the description of the method for specific data types.</p></li>
<li><p><strong>notUpdated</strong>: <code>String[SetError]</code> (optional)</p>
<p>A map of Foo id to a SetError object for each record that failed to be updated, omitted if none. The possible errors are defined in the description of the method for specific data types.</p></li>
<li><p><strong>notDestroyed</strong>: <code>String[SetError]</code> (optional)</p>
<p>A map of Foo id to a SetError object for each record that failed to be destroyed, omitted if none. The possible errors are defined in the description of the method for specific data types.</p></li>
</ul>
<p>A <strong>SetError</strong> object has the following properties:</p>
<ul>
<li><strong>type</strong>: <code>String</code>
The type of error.</li>
<li><strong>description</strong>: <code>String</code> (optional)
A description of the error to display to the user.</li>
</ul>
<p>Other properties may also be present on the object, as described in the relevant methods.</p>
<p>The following errors may be returned instead of the <code>foosSet</code> response:</p>
<p><code>invalidArguments</code>: Returned if one of the arguments is of the wrong type, or otherwise invalid. A <code>description</code> property MAY be present on the response object to help debug with an explanation of what the problem was.</p>
<p><code>stateMismatch</code>: Returned if an <code>ifInState</code> argument was supplied and it does not match the current state.</p>
<h2>Data model overview</h2>
<h3>Accounts</h3>
<p>All data belongs to an account. An account may provide access to mail, contacts and/or calendars. Most operations are isolated to a single account; there are a few explicit operations to copy data between them. A single login may provide access to multiple accounts, for example if another user is sharing data with the user.</p>
<p>All ids are only unique within their account. Ids may clash across accounts.</p>
<h3>Mail</h3>
<p>Each message must have a unique, immutable id. This id does not change if the message changes mailboxes. A mailbox is a named, arbitrary set of emails. For compatibility with IMAP, a message MUST always belong to at least one mailbox at any time.</p>
<p>Each message has 4 mutable boolean “flags” stored with it, each with a direct
equivalent in IMAP. In JMAP these flags are called:</p>
<ul>
<li><strong>isUnread</strong>: Has the email not yet been read?</li>
<li><strong>isFlagged</strong>: Has the email been flagged (starred, or pinned)?</li>
<li><strong>isDraft</strong>: Is the email a draft?</li>
<li><strong>isAnswered</strong>: Has the email been answered (replied to)?</li>
</ul>
<p>Messages are immutable other than these 4 flags and the set of mailboxes to which it belongs. To change anything else, the message must be deleted and a new one created (which will get a different id).</p>
<p>Related messages are grouped into threads. When getting a message list, you can collapse threads; that is the thread is only returned <strong>once</strong>, at the position of the first message in the thread to found in the non-collapsed list (given the sort order).</p>
<h3>Contacts</h3>
<p>The contacts spec is yet to come. Excited?!</p>
<h3>Calendars</h3>
<p>The calendars spec is yet to come. Excited?!</p>
<h2>Accounts</h2>
<p>A single login may provide access to multiple accounts, for example if another user is sharing their mail with the logged in user.</p>
<p>All data belongs to an account. With the exception of a few explicit operations to copy data between accounts, all methods take an <em>accountId</em> argument that specifies on which account the operations are to take place. This argument is always optional; if not specified, the primary account is used. All ids (other than Account ids of course) are only unique within their account.</p>
<p>An <strong>Account</strong> object has the following properties:</p>
<ul>
<li><strong>id</strong>: <code>String</code>
The id of the account.</li>
<li><strong>name</strong>: <code>String</code>
A user-friendly string to show when presenting content from this account. e.g. the email address of the account.</li>
<li><strong>isPrimary</strong>: <code>Boolean</code>
This MUST be true for exactly one of the accounts returned.</li>
<li><strong>isReadOnly</strong>: <code>Boolean</code>
True if the user has read-only access to this account. The user may not use the <code>set</code> methods with this account.</li>
<li><strong>hasMail</strong>: <code>Boolean</code>
This account contains mail data. Clients may use the Mail methods with this account.</li>
<li><strong>mailCapabilities</strong>: <code>MailCapabilities|null</code>
An object describing various capabilities of this server with relation to mail, or <code>null</code> if <code>hasMail == false</code>.</li>
<li><strong>hasContacts</strong>: <code>Boolean</code>
This account contains contact data. Clients may use the Contacts methods with this account.</li>
<li><strong>hasCalendars</strong>: <code>Boolean</code>
This account contains calendar data. Clients may use the Calendar methods with this account.</li>
</ul>
<p>A <strong>MailCapabilities</strong> object has the following properties</p>
<p>TODO:</p>
<ul>
<li>delayedSend?</li>
<li>maxSendSize?</li>
<li>supportsMultiMailbox?</li>
<li>supportsThreads?</li>
</ul>
<h3>getAccounts</h3>
<p>To fetch the complete list of accounts to which the user has access, make a call to <code>getAccounts</code>. It takes a sole, optional argument:</p>
<ul>
<li><strong>sinceState</strong>: <code>String</code> (optional)
This is the <code>state</code> string from a previous call to <em>getAccounts</em>.</li>
</ul>
<p>The response to <em>getAccounts</em> is called <em>accounts</em>. It has the following arguments:</p>
<ul>
<li><strong>state</strong>: <code>String</code>
A string representing the state on the server for <strong>all</strong> the data contained within the Account objects. If the data changes, this string will change.</li>
<li><strong>list</strong>: <code>Account[]</code>
An array of all Account objects.</li>
</ul>
<p>The following errors may be returned instead of the <code>accounts</code> response:</p>
<p><code>invalidArguments</code>: Returned if the <code>sinceState</code> argument is included and has the wrong type.</p>
<p>Example of a successful request:</p>
<pre><code>["getAccounts", {}, "#0"]
</code></pre>
<p>and response:</p>
<pre><code>[ "accounts", {
"state": "f6a7e214",
"list": [
{
"id": "6asf5",
"name": "user@example.com",
"isPrimary": true,
"isReadOnly": false,
"hasMail": true,
"hasContacts": true,
"hasCalendars": true
},
{
"id": "e12e1a",
"name": "shared.user@example.com",
"isPrimary": false,
"isReadOnly": true,
"hasMail": true,
"hasContacts": false,
"hasCalendars": false
}
]
}, "#0" ]
</code></pre>
<h2>Mailbox</h2>
<p>A mailbox represents a named set of emails. This is the primary mechanism for organising messages within an account. It is analogous to a folder in IMAP or a label in other systems. A mailbox may perform a certain role in the system.</p>
<p>A <strong>Mailbox</strong> object has the following properties:</p>
<ul>
<li><strong>id</strong>: <code>String</code>
The id of the mailbox. This property is immutable.</li>
<li><strong>name</strong>: <code>String</code>
User-visible name for the mailbox, e.g. “Inbox”. This may be any UTF-8 string of at least 1 character in length and maximum 256 bytes in size. Mailboxes MAY have the same name as a sibling Mailbox.</li>
<li><strong>parentId</strong>: <code>String|null</code>
The mailbox id for the parent of this mailbox, or <code>null</code> if this mailbox is at the top level. Mailboxes form acyclic graphs (trees); there MUST NOT be a loop.</li>
<li><p><strong>role</strong>: <code>String|null</code>
Identifies system mailboxes. This property is immutable.</p>
<p>The following values SHOULD be used for the relevant mailboxes.</p>
<ul>
<li><code>inbox</code> – the mailbox to which new mail is delivered by default, unless diverted by a rule or spam filter etc.</li>
<li><code>archive</code> – messages the user does not need right now, but does not wish to delete.</li>
<li><code>drafts</code> – messages the user is currently writing and are not yet sent.</li>
<li><code>outbox</code> – messages the user has finished writing and wishes to send (see the <code>setMessages</code> method description for more information). A mailbox with this role MUST be present if the user is allowed to send mail through an account. If not present, the user MAY NOT send mail with that account.</li>
<li><code>sent</code> – messages the user has sent.</li>
<li><code>trash</code> – messages the user has deleted.</li>
<li><code>spam</code> – messages considered spam by the server.</li>
<li><code>templates</code> – drafts which should be used as templates (i.e. used as the basis for creating new drafts).</li>
</ul>
<p>No two mailboxes may have the same role. Mailboxes without a known purpose MUST have a role of <code>null</code>.</p>
<p>An account is not required to have mailboxes with any of the above roles. A client MAY create new mailboxes with a role property to help them keep track of a use-case not covered by the above list. To avoid potential conflict with any special behaviour a server might apply to mailboxes with certain roles in the future, any roles not in the above list created by the client must begin with <code>"x-"</code>. The client MAY attempt to create mailboxes with the standard roles if not already present, but the server MAY reject these.</p></li>
<li><strong>mustBeOnlyMailbox</strong>: <code>Boolean</code>
If true, messages in this mailbox may not also be in any other mailbox.</li>
<li><strong>mayAddMessages</strong>: <code>Boolean</code>
The user may add messages to this mailbox (by either creating a new message or modifying an existing one).</li>
<li><strong>mayRemoveMessages</strong>: <code>Boolean</code>
The user may remove messages from this mailbox (by either changing the mailboxes of a message or deleting it).</li>
<li><strong>mayCreateChild</strong>: <code>Boolean</code>
The user may create a mailbox with this mailbox as its parent.</li>
<li><strong>mayRenameMailbox</strong>: <code>Boolean</code>
The user may rename the mailbox or make it a child of another mailbox.</li>
<li><strong>mayDeleteMailbox</strong>: <code>Boolean</code>
The user may delete the mailbox itself.</li>
<li><strong>totalMessages</strong>: <code>Number</code>
The number of messages in this mailbox.</li>
<li><strong>unreadMessages</strong>: <code>Number</code>
The number of messages in this mailbox where the <em>isUnread</em> property of the message is <code>true</code> and the <em>isDraft</em> property is <code>false</code>.</li>
<li><strong>totalThreads</strong>: <code>Number</code>
The number of threads where at least one message in the thread is in this mailbox (but see below for special case handling of Trash).</li>
<li><strong>unreadThreads</strong>: <code>Number</code>
The number of threads where at least one message in the thread has <code>isUnread == true</code> and <code>isDraft == false</code> AND at least one message in the thread is in this mailbox (but see below for special case handling of Trash). Note, the unread message does not need to be the one in this mailbox.</li>
</ul>
<p>The Trash mailbox (that is a mailbox with <code>role == "trash"</code>) MUST be treated specially:</p>
<ul>
<li>Messages in the Trash are ignored when calculating the <code>unreadThreads</code> and <code>totalThreads</code> count of other mailboxes.</li>
<li>Messages not in the Trash are ignored when calculating the <code>unreadThreads</code> and <code>totalThreads</code> count for the Trash folder.</li>
</ul>
<p>The result of this is that messages in the Trash are treated as though they are in a separate thread for the purposes of mailbox counts. It is expected that clients will hide messages in the Trash when viewing a thread in another mailbox and vice versa. This allows you to delete a single message to the Trash out of a thread.</p>
<p>For example, suppose you have an account where the entire contents is a single conversation with 2 messages: an unread message in the Trash and a read message in the Inbox. The <code>unreadThreads</code> count would be <code>1</code> for the Trash and <code>0</code> for the Inbox.</p>
<p>The server MAY support extra properties on the Message object. To avoid conflict with any future standardised properties, custom property names MUST begin with <code>"x-"</code>. Custom properties MAY be mutable. If so, changes to these properties SHOULD, cause the mailbox id to appear in the <em>changed</em> response of a call to <em>getMailboxUpdates</em>.</p>
<h3>getMailboxes</h3>
<p>Mailboxes can either be fetched explicitly by id, or you can fetch all of them at once. To fetch mailboxes, make a call to <code>getMailboxes</code>. It takes the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code> (optional)
The Account to fetch the mailboxes for. If omitted, the primary account is used.</li>
<li><strong>ids</strong>: <code>String</code> (optional)
The ids of the mailboxes to fetch. If omitted, all mailboxes in the account are be fetched.</li>
<li><strong>properties</strong>: <code>String[]|null</code>
If supplied, only the properties listed in the array will be returned for each mailbox. If <code>null</code>, all properties are returned. The id of the mailbox will <strong>always</strong> be returned, even if not explicitly requested. For compatibility with possible future extensions, the server MUST simply ignore any unknown properties in the list.</li>
</ul>
<p>The response to <em>getMailboxes</em> is called <em>mailboxes</em>. It has the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code>
The id of the account used for the call.</li>
<li><strong>state</strong>: <code>String</code>
A string representing the state on the server for <strong>all</strong> mailboxes. If the state of a mailbox changes, or a new mailbox is created, or a mailbox is destroyed, this string will change. It is used to get delta updates.</li>
<li><strong>list</strong>: <code>Mailbox[]</code>
An array of the Mailbox objects requested. This will be the <strong>empty array</strong> if none were requested, or none were found.</li>
<li><strong>notFound</strong>: <code>String[]|null</code>
This array contains the ids passed to the method for mailboxes that do not exist, or <code>null</code> if all requested ids were found. It will always be <code>null</code> if the <em>ids</em> argument was omitted from the call.</li>
</ul>
<p>The following errors may be returned instead of the <em>mailboxes</em> response:</p>
<p><code>accountNotFound</code>: Returned if an <em>accountId</em> was explicitly included with the request, but it does not correspond to a valid account.</p>
<p><code>accountNoMail</code>: Returned if the <em>accountId</em> given corresponds to a valid account, but does not contain any mail data.</p>
<p><code>invalidArguments</code>: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A <code>description</code> property MAY be present on the response object to help debug with an explanation of what the problem was.</p>
<h3>getMailboxUpdates</h3>
<p>The <em>getMailboxUpdates</em> call allows a client to efficiently update the state of its cached mailboxes to match the new state on the server. It takes the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code> (optional)
The id of the account to use for this call. If omitted, the primary account will be used.</li>
<li><strong>sinceState</strong>: <code>String</code>
The current state of the client. This is the string that was returned as the <em>state</em> argument in the <em>mailboxes</em> response. The server will return the changes made since this state.</li>
<li><strong>fetchMailboxes</strong>: <code>Boolean</code>
If <code>true</code>, after outputting a <em>mailboxUpdates</em> response, an implicit call will be made to <em>getMailboxes</em> with the <em>changed</em> property of the response as the <em>ids</em> argument, and the <em>fetchMailboxProperties</em> argument as the <em>properties</em> argument.</li>
<li><strong>fetchMailboxProperties</strong>: <code>String[]|null</code>
If <code>null</code>, all Mailbox properties will be fetched unless <em>onlyCountsChanged</em> in the <em>mailboxUpdates</em> response is <code>true</code>, in which case only the 4 counts properties will be returned (<em>totalMessages</em>, <em>unreadMessages</em>, <em>totalThreads</em> and <em>unreadThreads</em>). If not <code>null</code>, this value will be passed through to the <em>getMailboxes</em> call regardless of the <em>onlyCountsChanged</em> value in the <em>mailboxUpdates</em> response.</li>
</ul>
<p>The response to <em>getMailboxUpdates</em> is called <em>mailboxUpdates</em>. It has the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code>
The id of the account used for the call.</li>
<li><strong>oldState</strong>: <code>String</code>
This is the <em>sinceState</em> argument echoed back; the state from which the server is returning changes.</li>
<li><strong>newState</strong>: <code>String</code>
This is the state the client will be in after applying the set of changes to the old state.</li>
<li><strong>changed</strong>: <code>String[]</code>
An array of Mailbox ids where a property of the mailbox has changed between the old state and the new state, or the mailbox has been created, and the mailbox has not been destroyed.</li>
<li><strong>removed</strong>: <code>String[]</code>
An array of Mailbox ids for mailboxes which have been destroyed since the old state.</li>
<li><strong>onlyCountsChanged</strong>: <code>Boolean</code>
Indicates that only the folder counts (unread/total messages/threads) have changed since the old state. The client can then use this to optimise its data transfer and only fetch the counts. If the server is unable to tell if only counts have changed, it should just always return <code>false</code>.</li>
</ul>
<p>If a mailbox has been modified AND deleted since the oldState, the server should just return the id in the <em>removed</em> array, but MAY return it in the <em>changed</em> array as well. If a mailbox has been created AND deleted since the oldState, the server SHOULD remove the mailbox id from the response entirely, but MAY include it in the <em>removed</em> array, and optionally the <em>changed</em> array as well.</p>
<p>The following errors may be returned instead of the <code>mailboxUpdates</code> response:</p>
<p><code>accountNotFound</code>: Returned if an <em>accountId</em> was explicitly included with the request, but it does not correspond to a valid account.</p>
<p><code>accountNoMail</code>: Returned if the <em>accountId</em> given corresponds to a valid account, but does not contain any mail data.</p>
<p><code>invalidArguments</code>: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A <code>description</code> property MAY be present on the response object to help debug with an explanation of what the problem was.</p>
<p><code>cannotCalculateChanges</code>: Returned if the server cannot calculate the changes from the state string given by the client. Usually due to the client’s state being too old. The client MUST invalidate its Mailbox cache.</p>
<h3>setMailboxes</h3>
<p>Mailboxes can be created, updated and destroyed using the <em>setMailboxes</em> method. The method takes the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code> (optional)
The id of the account to use for this call. If not given, defaults to the primary account.</li>
<li><strong>ifInState</strong>: <code>String</code> (optional)
This is a state string as returned by the <em>getMailboxes</em> method. If supplied, the string must match the current state, otherwise the method will be aborted and a <code>stateMismatch</code> error returned.</li>
<li><strong>create</strong>: <code>String[Mailbox]</code> (optional)
A map of <em>creation id</em> (an arbitrary string set by the client) to Mailbox objects.</li>
<li><strong>update</strong>: <code>String[Mailbox]</code> (optional)
A map of id to a an object containing the properties to update for that Mailbox.</li>
<li><strong>destroy</strong>: <code>String[]</code> (optional)
A list of ids for Mailboxes to permanently delete.</li>
</ul>
<p>Each create, update or destroy is considered an atomic unit. The server MAY commit some of the changes but not others, however MAY NOT only commit part of an update to a single record (e.g. update the <em>name</em> field but not the <em>parentId</em> field, if both are supplied in the update object).</p>
<p>If a create, update or destroy is rejected, the appropriate error should be added to the notCreated/notUpdated/notDestroyed property of the response and the server MUST continue to the next create/update/destroy. It does not terminate the method.</p>
<h4>Creating mailboxes</h4>
<p>For compatibility with possible future extensions, the server MUST ignore any unknown properties in the object.</p>
<p>The properties of the Mailbox object submitted for creation MUST conform to the following conditions:</p>
<ul>
<li>The <em>id</em> property MUST NOT be present.</li>
<li>The <em>parentId</em> property MUST be either <code>null</code> or be a valid id for a mailbox for which the <code>mayCreateSub</code> property is <code>true</code>.</li>
<li>The <em>role</em> property is optional. If not present, it defaults to <code>null</code>. If present it MUST be either <code>null</code>, a valid role as listed in the Mailbox object specification, or prefixed by <code>"x-"</code>.</li>
<li>The <em>mustBeOnlyMailbox</em> property MUST NOT be present. This is server dependent and will be set by the server.</li>
<li>The <em>mayXXX</em> properties are optional. All default to <code>true</code>. If present, they MUST all be set to <code>true</code>. Restrictions may only be set by the server for system mailboxes, or when sharing mailboxes with other users (setting sharing is not defined yet in this spec).</li>
<li>The <em>totalMessages</em>, <em>unreadMessages</em>, <em>totalThreads</em> and <em>unreadThreads</em> properties are optional. If present they MUST all have a value of 0.</li>
</ul>
<p>If any of the properties are invalid, the server MUST reject the create with an <code>invalidProperties</code> error. The Error object SHOULD contain a property called <em>properties</em> of type <code>String[]</code> that lists <strong>all</strong> the properties that were invalid. The object MAY also contain a <em>description</em> property of type <code>String</code> with a user-friendly description of the problems.</p>
<p>There may be a maximum number of mailboxes allowed on the server. If this is reached, any attempt at creation will be rejected with a <code>maxQuotaReached</code> error.</p>
<h4>Updating mailboxes</h4>
<p>If the <em>id</em> given does not correspond to a Mailbox in the given account, the update MUST be rejected with a <code>notFound</code> error.</p>
<p>For compatibility with possible future extensions, the server MUST ignore any unknown properties in the object.</p>
<p>All properties being updated must be of the correct type, not immutable or server-set-only, and the new value must obey all conditions of the property. In particular, note the following conditions:</p>
<ul>
<li>The <em>name</em> property MUST be valid UTF-8, between 1 and 256 bytes in size.</li>
<li>The <em>parentId</em> property MUST be either <code>null</code> or be a valid id for <em>another</em> mailbox that is <strong>not a descendant</strong> of this mailbox, and for which the <code>mayCreateSub</code> property is <code>true</code>.</li>
<li>These properties are immutable or may only be set by the server:
<ul>
<li>id</li>
<li>role</li>
<li>mustBeOnlyMailbox</li>
<li>mayAddMessages</li>
<li>mayRemoveMessages</li>
<li>mayCreateChild</li>
<li>mayRenameMailbox</li>
<li>mayDeleteMailbox</li>
<li>totalMessages</li>
<li>unreadMessages</li>
<li>totalThreads</li>
<li>unreadThreads</li>
</ul>
</li>
</ul>
<p>If any of the properties are invalid, the server MUST reject the update with an <code>invalidProperties</code> error. The Error object SHOULD contain a property called <em>properties</em> of type <code>String[]</code> that lists <strong>all</strong> the properties that were invalid. The object MAY also contain a <em>description</em> property of type <code>String</code> with a user-friendly description of the problems.</p>
<h4>Destroying mailboxes</h4>
<p>If the <em>id</em> given does not correspond to a Mailbox in the given account, the destruction MUST be rejected with a <code>notFound</code> error.</p>
<p>If the mailbox has <code>mayDeleteMailbox == false</code>, the destruction MUST be rejected with a <code>forbidden</code> error.</p>
<p>A mailbox MAY NOT be destroyed if it still has any child mailboxes. Attempting to do so will result in the destruction being rejected with a <code>mailboxHasChild</code> error.</p>
<p>Destroying a mailbox MUST NOT delete any messages still contained within it. It only removes them from the mailbox. Since messages MUST always be in at least one mailbox, if the last mailbox they are in is deleted the messages must be added to the mailbox with <code>role == "inbox"</code>. If no Inbox exists, the messages must be moved to any other mailbox; this is server dependent.</p>
<p>There MUST always be <strong>at least one</strong> mailbox. It is expected that the server will enforce this by setting <code>mayDeleteMailbox == false</code> on at least the Inbox, if not all system mailboxes. However, if this is not the case, an attempt to destroy the last mailbox MUST still be rejected with a <code>mailboxRequired</code> error.</p>
<h4>Ordering of changes</h4>
<p>Each individual create, update or destroy MUST take the server from one valid state to another valid state, so the changes can be processed linearly without need to undo or backtrack. However the order of the changes may affect the validity of the change. The server MUST process the changes in a manner which is indistinguishable from an order following these rules:</p>
<ol>
<li>Creates comes before any other changes.</li>
<li>Creates with a parentId that is not a <em>creation id</em> reference come before those that reference another newly created mailbox.</li>
<li>Creation of a mailbox X comes before creation of a mailbox Y if Y will be a descendent of X.</li>
<li>Updates come before destroying mailboxes.</li>
<li>Update/Destroy X comes before update/destroy Y if X is a descendent of Y.</li>
</ol>
<h4>Response</h4>
<p>The response to <code>setMailboxes</code> is called <code>mailboxesSet</code>. It has the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code>
The id of the account used for the call.</li>
<li><strong>oldState</strong>: <code>String</code>
The state string that would have been returned by <code>getMailboxes</code> before making the requested changes.</li>
<li><strong>newState</strong>: <code>String</code>
The state string that will now be returned by <code>getMailboxes</code>.</li>
<li><strong>created</strong>: <code>String[Mailbox]</code> (optional)
A map of the creation id to an object containing the <strong>id</strong> and <strong>mustBeOnlyMailbox</strong> properties for each successfully created Mailbox, omitted if none.</li>
<li><strong>updated</strong>: <code>String[]</code> (optional)
A list of ids for Mailboxes that were successfully updated, omitted if none.</li>
<li><strong>destroyed</strong>: <code>String[]</code> (optional)
A list of ids for Mailboxes that were successfully destroyed, omitted if none.</li>
<li><strong>notCreated</strong>: <code>String[SetError]</code> (optional)
A map of creation id to a SetError object for each Mailbox that failed to be created, omitted if none. The possible errors are defined above.</li>
<li><strong>notUpdated</strong>: <code>String[SetError]</code> (optional)
A map of Mailbox id to a SetError object for each Mailbox that failed to be updated, omitted if none. The possible errors are defined above.</li>
<li><strong>notDestroyed</strong>: <code>String[SetError]</code> (optional)
A map of Mailbox id to a SetError object for each Mailbox that failed to be destroyed, omitted if none. The possible errors are defined above.</li>
</ul>
<p>The following errors may be returned instead of the <em>mailboxesSet</em> response:</p>
<p><code>accountNotFound</code>: Returned if an <em>accountId</em> was explicitly included with the request, but it does not correspond to a valid account.</p>
<p><code>accountNoMail</code>: Returned if the <em>accountId</em> given corresponds to a valid account, but does not contain any mail data.</p>
<p><code>accountReadOnly</code>: Returned if the account has <code>isReadOnly == true</code>.</p>
<p><code>invalidArguments</code>: Returned if one of the arguments is of the wrong type, or otherwise invalid. A <em>description</em> property MAY be present on the response object to help debug with an explanation of what the problem was.</p>
<p><code>stateMismatch</code>: Returned if an <code>ifInState</code> argument was supplied and it does not match the current state.</p>
<p>Example request:</p>
<pre><code>[ "setMailboxes", {
"ifInState": "ms4123",
"update": {
"f3": {
"name": "The new name"
}
},
"destroy": [ "f5" ]
}, "#0" ]
</code></pre>
<h2>MessageLists</h2>
<p>A <strong>MessageList</strong> is a sorted query on the set of messages in a user’s mailbox. Since it can be very long, the client must specify what section of the list to return. The client can optionally also fetch the threads and/or messages for this part of the list.</p>
<p>The same message may appear in multiple messages lists. For example, it may belong to multiple mailboxes, and of course it can appear in searches. Since messages have an immutable id, a client can easily tell if it already has a message cached and only fetch the ones it needs.</p>
<p>When the state changes on the server, a delta update can be requested to efficiently update the client’s cache of this list to the new state. If the server doesn’t support this, the client still only needs to fetch the message list again, not the messages themselves.</p>
<h3>getMessageList</h3>
<p>To fetch a message list, make a call to <em>getMessageList</em>. It takes the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code> (optional)
The id of the account to use for this call. If omitted, the primary account will be used.</li>
<li><strong>filter</strong>: <code>FilterOperator</code>
Determines the set of messages returned in the results. See the “Filtering” section below for allowed values and semantics.</li>
<li><strong>sort</strong>: <code>String[]</code>
A list of Message property names to sort by. See the “Sorting” section below for allowed values and semantics.</li>
<li><strong>collapseThreads</strong>: <code>Boolean</code>
If true, each thread will only be returned once in the resulting list, at the position of the first message in the list (given the filter and sort order) belonging to the thread.</li>
<li><strong>position</strong>: <code>Number</code> (optional)
The 0-based index of the first result in the list to return. If a negative value is given, the call MUST be rejected with an <code>invalidArguments</code> error.</li>
<li><strong>anchor</strong>: <code>String</code> (optional)
A Message id. The index of this message id will be used in combination with the <code>anchorOffset</code> argument to determine the index of the first result to return (see the “Windowing” section below for more details).</li>
<li><strong>anchorOffset</strong>: <code>Number</code> (optional)
The index of the anchor message relative to the index of the first result to return. This MAY be negative. For example, <code>-1</code> means the first message after the anchor message should be the first result in the results returned (see the “Windowing” section below for more details).</li>
<li><strong>limit</strong>: <code>Number</code>
The maximum number of results to return. The server MAY choose to enforce a maximum <code>limit</code> argument. In this case, if a greater value is given, the limit should be clamped to the maximum; since the total number of results in the list is returned, the client should not be relying on how many results are returned to determine if it has reached the end of the list. If a negative value is given, the call MUST be rejected with an <code>invalidArguments</code> error.</li>
<li><strong>fetchThreads</strong>: <code>Boolean</code>
If <code>true</code>, after outputting a <em>messageList</em> response, an implicit call will be made to <em>getThreads</em> with the <em>threadIds</em> array in the reponse as the <em>ids</em> argument, and the <em>fetchMessage</em> and <em>fetchMessageProperties</em> arguments passed straight through from the call to <em>getMessageList</em>.</li>
<li><strong>fetchMessages</strong>: <code>Boolean</code>
If <code>true</code> and <code>fetchThreads == false</code>, then after outputting a <em>messageList</em> response, an implicit call will be made to <em>getMessages</em> with the <code>messageIds</code> array in the response as the <em>ids</em> argument, and the <em>fetchMessageProperties</em> argument as the <em>properties</em> argument.</li>
<li><strong>fetchMessageProperties</strong>: <code>String[]|null</code>
The list of properties to fetch on any fetched messages. See <em>getMessages</em> for a full description.</li>
<li><strong>fetchSearchSnippets</strong>: <code>Boolean</code>
If <code>true</code>, then after outputting a <em>messageList</em> and making any other implicit calls, an implicit call will be made to <em>getSearchSnippets</em>. The <em>messageIds</em> array from the response will be used as the <em>messageIds</em> argument, and the <em>filter</em> argument will be passed straight through.</li>
</ul>
<h4>Filtering</h4>
<p>A <strong>FilterOperator</strong> object has the following properties:</p>
<ul>
<li><strong>operator</strong>: <code>String</code>
This MUST be one of the following strings: “AND”/“OR”/“NOT”:
<ul>
<li><strong>AND</strong>: all of the conditions must match for the filter to match.</li>
<li><strong>OR</strong>: at least one of the conditions must match for the filter to match.</li>
<li><strong>NOT</strong>: none of the conditions must match for the filter to match.</li>
</ul>
</li>
<li><strong>conditions</strong>: <code>(FilterCondition|FilterOperator)[]</code>
The conditions to evaluate against each message.</li>
</ul>
<p>A <strong>FilterCondition</strong> object has the following properties:</p>
<ul>
<li><strong>inMailboxes</strong>: <code>String[]</code> (optional)
A list of mailbox ids. A message must be in ALL of these mailboxes to match the condition.</li>
<li><strong>notInMailboxes</strong>: <code>String[]</code> (optional)
A list of mailbox ids. A message must NOT be in ANY of these mailboxes to match the condition.</li>
<li><strong>before</strong>: <code>Date</code> (optional)
The date of the message (as returned on the Message object) must be before this date to match the condition.</li>
<li><strong>after</strong>: <code>Date</code> (optional)
The date of the message (as returned on the Message object) must be on or after this date to match the condition.</li>
<li><strong>isFlagged</strong>: <code>Boolean</code> (optional)
The <code>isFlagged</code> property of the message must be identical to the value given to match the condition.</li>
<li><strong>isUnread</strong>: <code>Boolean</code> (optional)
The <code>isUnread</code> property of the message must be identical to the value given to match the condition.</li>
<li><strong>isAnswered</strong>: <code>Boolean</code> (optional)
The <code>isAnswered</code> property of the message must be identical to the value given to match the condition.</li>
<li><strong>isDraft</strong>: <code>Boolean</code> (optional)
The <code>isDraft</code> property of the message must be identical to the value given to match the condition.</li>
<li><strong>hasAttachment</strong>: <code>Boolean</code> (optional)
The <code>hasAttachment</code> property of the message must be identical to the value given to match the condition.</li>
<li><strong>text</strong>: <code>String</code> (optional)
Looks for the text in the <em>from</em>, <em>to</em>, <em>cc</em>, <em>bcc</em>, <em>subject</em>, <em>textBody</em> or <em>htmlBody</em> properties of the message.</li>
<li><strong>from</strong>: <code>String</code> (optional)
Looks for the text in the <em>from</em> property of the message.</li>
<li><strong>to</strong>: <code>String</code> (optional)
Looks for the text in the <em>to</em> property of the message.</li>
<li><strong>cc</strong>: <code>String</code> (optional)
Looks for the text in the <em>cc</em> property of the message.</li>
<li><strong>bcc</strong>: <code>String</code> (optional)
Looks for the text in the <em>bcc</em> property of the message.</li>
<li><strong>subject</strong>: <code>String</code> (optional)
Looks for the text in the <em>subject</em> property of the message.</li>
<li><strong>body</strong>: <code>String</code> (optional)
Looks for the text in the <em>textBody</em> or <em>htmlBody</em> property of the message.</li>
<li><strong>header</strong>: <code>String[]</code> (optional)
The array MUST contain either one or two elements. The first element is the name of the header to match against. The second (optional) element is the text to look for in the header. If not supplied, the message matches simply if it <em>has</em> a header of the given name.</li>
</ul>
<p>The exact semantics for matching <code>String</code> fields is <strong>deliberately not defined</strong> to allow for flexibility in indexing implementation, subject to the following:</p>
<ul>
<li>Text SHOULD be matched in a case-insensitive manner.</li>
<li>Text contained in either (but matched) single or double quotes SHOULD be treated as a <strong>phrase search</strong>, that is a match is required for that exact sequence of words, excluding the surrounding quotation marks. Use <code>\"</code>, <code>\'</code> and <code>\\</code> to match a literal <code>"</code>, <code>'</code> and <code>\</code> respectively in a phrase.</li>
<li>Outside of a phrase, white-space SHOULD be treated as dividing separate tokens that may be searched for separately in the message, but MUST all be present for the message to match the filter.</li>
<li>Tokens MAY be matched on a whole-word basis using stemming (so for example a text search for <code>bus</code> would match “buses” but not “business”).</li>
<li>When searching inside the <em>htmlBody</em> property, HTML tags and attributes SHOULD be ignored.</li>
</ul>
<h4>Sorting</h4>
<p>The <code>sort</code> argument lists the properties to compare between two messages to determine which comes first in the sort. If two messages have an identical value for the first property, the next property will be considered and so on. If all properties are the same (this includes the case where an empty array is given as the argument), the sort order is server-dependent, but MUST be stable between calls to <code>getMessageList</code>.</p>
<p>Optionally, following the property name there can be a space and then either the string <code>asc</code> or <code>desc</code> to specify ascending or descending sort for that property. If not specified, it MUST default to <strong>descending</strong>.</p>
<p>The following properties MUST be supported for sorting:</p>
<ul>
<li><strong>id</strong> - The id as returned in the Message object.</li>
<li><strong>date</strong> - The date as returned in the Message object.</li>
</ul>
<p>The following properties SHOULD be supported for sorting:</p>
<ul>
<li><strong>size</strong> - The size as returned in the Message object.</li>
<li><strong>from</strong> – This is taken to be either the “name” part of the Emailer object, or if none then the “email” part of the Emailer object (see the definition of the from property in the Message object). If still none, consider the value to be the empty string.</li>
<li><strong>to</strong> - This is taken to be either the “name” part of the <strong>first</strong> Emailer object, or if none then the “email” part of the <strong>first</strong> Emailer object (see the definition of the to property in the Message object). If still none, consider the value to be the empty string.</li>
<li><strong>subject</strong> - This is taken to be the subject of the Message with any ignoring any leading “Fwd:"s or "Re:"s (case-insensitive match).</li>
<li><strong>isFlagged</strong> - If <code>collapseThreads == true</code>, this value MUST be considered <code>true</code> for the message if it is <code>true</code> for <strong>any</strong> of the messages in the thread.</li>
<li><strong>isUnread</strong> - If <code>collapseThreads == true</code>, this value MUST be considered <code>true</code> for the message if it is <code>true</code> for <strong>any</strong> of the messages in the thread.</li>
</ul>
<p>The server MAY support sorting based on other properties as well.</p>
<p>The method of comparison depends on the type of the property:</p>
<ul>
<li><code>String</code>: Comparison function is server-dependent. It SHOULD be case-insensitive and SHOULD take into account locale-specific conventions if known for the user. However, the server MAY choose to just sort based on unicode code point, after best-effort translation to lower-case.</li>
<li><code>Date</code>: If sorting in ascending order, the earlier date MUST come first.</li>
<li><code>Boolean</code>: If sorting in ascending order, a <code>false</code> value MUST come before a <code>true</code> value.</li>
</ul>
<h4>Thread collapsing</h4>
<p>When <code>collapseThreads == true</code>, then after filtering and sorting the message list, the list is further winnowed by removing any messages for a thread id that has already been seen (when passing through the list sequentially). A thread will therefore only appear <strong>once</strong> in the <code>threadIds</code> list of the result, at the position of the first message in the list that belongs to the thread.</p>
<h4>Windowing</h4>
<p>To paginate the results the client MUST <strong>either</strong> specify a <em>position</em> argument OR an <em>anchor</em> argument. If both, or neither are supplied, the call MUST be rejected with an <code>invalidArguments</code> error. The <em>anchorOffset</em> argument MUST be supplied <strong>if and only</strong> if the <em>anchor</em> argument is supplied. Any other case MUST be rejected with an <code>invalidArguments</code> error.</p>
<p>If a <em>position</em> offset is supplied, then this is the 0-based index of the first result to return in the list of messages after filtering, sorting and collapsing threads. If the index is greater than or equal to the total number of messages in the list, then there are no results to return, but this DOES NOT generate an error.</p>
<p>Alternatively, a message id, called the <strong>anchor</strong> may be given. In this case, after filtering, sorting and collapsing threads, the anchor is searched for in the message list. If found, the <strong>anchor offset</strong> is then subtracted from this index. If the resulting index is now negative, it is clamped to 0. This index is now used exactly as though it were supplied as the <code>position</code> argument. If the anchor is not found, the call is rejected with an <code>anchorNotFound</code> error.</p>
<h4>Response</h4>
<p>The response to a call to <em>getMessageList</em> is called <em>messageList</em>. It has the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code>
The id of the account used for the call.</li>
<li><strong>filter</strong>: <code>FilterCriterion[]</code>
The filter of the message list. Echoed back from the call.</li>
<li><strong>sort</strong>: <code>String[]</code>
A list of Message property names used to sort by. Echoed back from the call.</li>
<li><strong>collapseThreads</strong>: <code>Boolean</code>
Echoed back from the call.</li>
<li><p><strong>state</strong>: <code>String</code>
A string encoding the current state on the server. This string will change
if the results of the message list MAY have changed (for example, there has been a change to the state of the set of Messages; it does not guarantee that anything in the list has changed). It may be passed to <em>getMessageListUpdates</em> to efficiently get the set of changes from the previous state.</p>
<p>Should a client receive back a response with a different state string to a previous call, it MUST either throw away the currently cached list and fetch it again (note, this does not require fetching the messages again, just the list of ids) or, if the server supports it, call <em>getMessageListUpdates</em> to get the delta difference.</p></li>
<li><strong>canCalculateUpdates</strong>: <code>Boolean</code>
This is <code>true</code> if the server supports calling <code>getMessageListUpdates</code> with these <code>filter</code>/<code>sort</code>/<code>collapseThreads</code> parameters. Note, this does not guarantee that the getMessageListUpdates call will succeed, as it may only be possible for a limited time afterwards due to server internal implementation details.</li>
<li><strong>position</strong>: <code>Number</code>
The 0-based index of the first result in the <code>threadIds</code> array within the complete list.</li>
<li><strong>total</strong>: <code>Number</code>
The total number of messages in the message list (given the <em>filter</em> and <em>collapseThreads</em> arguments).</li>
<li><strong>threadIds</strong>: <code>String[]</code>
The list of Thread ids for each message in the list after filtering, sorting and collapsing threads, starting at the index given by the <em>position</em> argument of this response, and continuing until it hits the end of the list or reaches the <code>limit</code> number of ids.</li>
<li><strong>messageIds</strong>: <code>String[]</code>
The list of Message ids for each message in the list after filtering, sorting and collapsing threads, starting at the index given by the <em>position</em> argument of this response, and continuing until it hits the end of the list or reaches the <code>limit</code> number of ids.</li>
</ul>
<p>The following errors may be returned instead of the <code>messageList</code> response:</p>
<p><code>accountNotFound</code>: Returned if an <em>accountId</em> was explicitly included with the request, but it does not correspond to a valid account.</p>
<p><code>accountNoMail</code>: Returned if the <em>accountId</em> given corresponds to a valid account, but does not contain any mail data.</p>
<p><code>unsupportedSort</code>: Returned if the <em>sort</em> includes a property the server does not support sorting on.</p>
<p><code>invalidArguments</code>: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A <code>description</code> property MAY be present on the response object to help debug with an explanation of what the problem was.</p>
<p><code>anchorNotFound</code>: Returned if an anchor argument was supplied, but it cannot be found in the message list.</p>
<h3>getMessageListUpdates</h3>
<p>The <code>getMessageListUpdates</code> call allows a client to efficiently update the state of any cached message list to match the new state on the server. It takes the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code> (optional)
The id of the account to use for this call. If omitted, the primary account will be used.</li>
<li><strong>filter</strong>: <code>FilterCriterion[]</code>
The filter argument that was used with <em>getMessageList</em>.</li>
<li><strong>sort</strong>: <code>String[]</code>
The sort argument that was used with <em>getMessageList</em>.</li>
<li><strong>collapseThreads</strong>: <code>Boolean</code>
The <em>collapseThreads</em> argument that was used with <em>getMessageList</em>.</li>
<li><strong>sinceState</strong>: <code>String</code>
The current state of the client. This is the string that was returned as the <em>state</em> argument in the <em>messageList</em> response. The server will return the changes made since this state.</li>
<li><strong>uptoMessageId</strong>: <code>String</code> (optional)
The message id of the last message in the list that the client knows about. In the common case of the client only having the first X ids cached, this allows the server to ignore changes further down the list the client doesn’t care about.</li>
<li><strong>maxChanges</strong>: <code>Number</code> (optional)
The maximum number of changes to return in the response. See below for a more detailed description.</li>
</ul>
<p>The response to <em>getMessageListUpdates</em> is called <em>messageListUpdates</em> It has the following arguments:</p>
<ul>
<li><strong>accountId</strong>: <code>String</code>
The id of the account used for the call.</li>
<li><strong>filter</strong>: <code>FilterCriterion[]</code>
The filter of the message list. Echoed back from the call.</li>
<li><strong>sort</strong>: <code>String[]</code>
A list of Message property names used to sort by. Echoed back from the call.</li>
<li><strong>collapseThreads</strong>: <code>Boolean</code>
Echoed back from the call.</li>
<li><strong>oldState</strong>: <code>String</code>
This is the <code>sinceState</code> argument echoed back; the state from which the server is returning changes.</li>
<li><strong>newState</strong>: <code>String</code>
This is the state the client will be in after applying the set of changes to the old state.</li>
<li><strong>total</strong>: <code>Number</code>
The total number of messages in the message list (given the filter and collapseThreads arguments).</li>
<li><p><strong>removed</strong>: <code>RemovedItem[]</code>
The <em>messageId</em> and <em>threadId</em> for every message that was in the list in the old state and is not in the list in the new state. If the server cannot calculate this exactly, the server MAY return extra messages in addition that MAY have been in the old list but are not in the new list.</p>
<p>If an <em>uptoMessageId</em> was given AND this id was found in the list, only messages positioned before this message that were removed need be returned.</p>
<p>In addition, if the sort includes the property <em>isUnread</em> or <em>isFlagged</em>, the server MUST include all messages in the current list for which this property MAY have changed. If <code>collapseThreads == true</code>, then the server MUST include all messages in the current list for which this property MAY have changed <strong>on any of the messages in the thread</strong>.</p></li>
<li><p><strong>added</strong>: <code>AddedItem[]</code>
The messageId and threadId and index in the list (in the new state) for every message that has been added to the list since the old state AND every message in the current list that was included in the <em>removed</em> array (due to a filter or sort based upon a mutable property). The array MUST be sorted in order of index, lowest index first.</p>
<p>If an <em>uptoMessageId</em> was given AND this id was found in the list, only messages positioned before this message that have been added need be returned.</p></li>
</ul>
<p>A <strong>RemovedItem</strong> object has the following properties:</p>
<ul>
<li><strong>messageId</strong>: <code>String</code></li>
<li><strong>threadId</strong>: <code>String</code></li>
</ul>
<p>An <strong>AddedItem</strong> object has the following properties:</p>
<ul>
<li><strong>messageId</strong>: <code>String</code></li>
<li><strong>threadId</strong>: <code>String</code></li>
<li><strong>index</strong>: <code>Number</code></li>
</ul>
<p>The result of this should be that if the client has a cached sparse array of message ids in the list in the old state:</p>
<pre><code>messageIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ]
</code></pre>
<p>then if it <strong>splices out</strong> all messages in the removed array:</p>
<pre><code>removed = [{ messageId: "id2", … }];
messageIds => [ "id1", null, null, "id3", "id4", null, null, null ]
</code></pre>
<p>and <strong>splices in</strong> (in order) all of the messages in the added array:</p>
<pre><code>added = [{ messageId: "id5", index: 0, … }];
messageIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ]
</code></pre>
<p>then the message list will now be in the new state.</p>