Internet DRAFT - draft-jenkins-jmapmail
draft-jenkins-jmapmail
JMAP N. Jenkins
Internet-Draft FastMail
Intended status: Standards Track October 19, 2016
Expires: April 22, 2017
JMAP for Mail
draft-jenkins-jmapmail-00
Abstract
This document specifies a data model for synchronising email data
with a server using JMAP.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 22, 2017.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Jenkins Expires April 22, 2017 [Page 1]
Internet-Draft JMAP Mail October 2016
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Addition to the capabilities object . . . . . . . . . . . 4
2. Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. getMailboxes . . . . . . . . . . . . . . . . . . . . . . 7
2.2. getMailboxUpdates . . . . . . . . . . . . . . . . . . . . 8
2.3. setMailboxes . . . . . . . . . . . . . . . . . . . . . . 10
2.3.1. Ordering of changes . . . . . . . . . . . . . . . . . 11
2.3.2. Creating mailboxes . . . . . . . . . . . . . . . . . 11
2.3.3. Updating mailboxes . . . . . . . . . . . . . . . . . 12
2.3.4. Destroying mailboxes . . . . . . . . . . . . . . . . 13
2.3.5. Response . . . . . . . . . . . . . . . . . . . . . . 14
3. MessageLists . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1. getMessageList . . . . . . . . . . . . . . . . . . . . . 16
3.1.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 17
3.1.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 20
3.1.3. Thread collapsing . . . . . . . . . . . . . . . . . . 21
3.1.4. Windowing . . . . . . . . . . . . . . . . . . . . . . 22
3.1.5. Response . . . . . . . . . . . . . . . . . . . . . . 22
3.2. getMessageListUpdates . . . . . . . . . . . . . . . . . . 24
4. Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1. getThreads . . . . . . . . . . . . . . . . . . . . . . . 27
4.2. getThreadUpdates . . . . . . . . . . . . . . . . . . . . 29
5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.1. getMessages . . . . . . . . . . . . . . . . . . . . . . . 35
5.2. getMessageUpdates . . . . . . . . . . . . . . . . . . . . 37
5.3. setMessages . . . . . . . . . . . . . . . . . . . . . . . 39
5.3.1. Saving a draft . . . . . . . . . . . . . . . . . . . 40
5.3.2. Updating messages . . . . . . . . . . . . . . . . . . 43
5.3.3. Sending messages . . . . . . . . . . . . . . . . . . 44
5.3.4. Cancelling a send . . . . . . . . . . . . . . . . . . 44
5.3.5. Destroying messages . . . . . . . . . . . . . . . . . 44
5.3.6. Response . . . . . . . . . . . . . . . . . . . . . . 45
5.4. importMessages . . . . . . . . . . . . . . . . . . . . . 46
5.5. copyMessages . . . . . . . . . . . . . . . . . . . . . . 47
5.6. reportMessages . . . . . . . . . . . . . . . . . . . . . 49
6. Identities . . . . . . . . . . . . . . . . . . . . . . . . . 50
6.1. getIdentities . . . . . . . . . . . . . . . . . . . . . . 51
6.2. getIdentityUpdates . . . . . . . . . . . . . . . . . . . 52
6.3. setIdentities . . . . . . . . . . . . . . . . . . . . . . 54
7. SearchSnippets . . . . . . . . . . . . . . . . . . . . . . . 57
7.1. getSearchSnippets . . . . . . . . . . . . . . . . . . . . 57
8. Vacation Response . . . . . . . . . . . . . . . . . . . . . . 58
8.1. getVacationResponse . . . . . . . . . . . . . . . . . . . 59
8.2. setVacationResponse . . . . . . . . . . . . . . . . . . . 60
Jenkins Expires April 22, 2017 [Page 2]
Internet-Draft JMAP Mail October 2016
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.1. Normative References . . . . . . . . . . . . . . . . . . 61
9.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 62
1. Introduction
JMAP is a generic protocol for synchronising data, such as mail,
calendars or contacts, between a client and a server. It is
optimised for mobile and web environments, and aims to provide a
consistent interface to different data types.
This specification defines a data model for synchronising mail
between a client and a server using JMAP.
1.1. Notational Conventions
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 [RFC2119].
The underlying format used for this specification is JSON.
Consequently, the terms "object" and "array" as well as the four
primitive types (strings, numbers, booleans, and null) are to be
interpreted as described in Section 1 of [RFC7159].
Some examples in this document contain "partial" JSON documents used
for illustrative purposes. In these examples, three periods "..."
are used to indicate a portion of the document that has been removed
for compactness.
Types signatures are given for all JSON objects in this document.
The following conventions are used:
o "Boolean|String" - The value is either a JSON "Boolean" value, or
a JSON "String" value.
o "Foo" - Any name that is not a native JSON type means an object
for which the properties (and their types) are defined elsewhere
within this document.
o "Foo[]" - An array of objects of type "Foo".
o "String[Foo]" - A JSON "Object" being used as a map (associative
array), where all the values are of type "Foo".
Jenkins Expires April 22, 2017 [Page 3]
Internet-Draft JMAP Mail October 2016
1.2. Terminology
The same terminology is used in this document as in the core JMAP
specification.
1.3. Addition to the capabilities object
The capabilities object is returned as part of the standard JMAP
authentication response; see the JMAP spec. Servers supporting
_this_ specification MUST add a property called "{TODO: URI for this
spec}" to the capabilities object. The value of this property is an
object which SHOULD contain the following information on server
capabilities:
o *maxSizeMessageAttachments*: "Number" The maximum total size of
attachments, in bytes, allowed for messages. A server MAY still
reject messages with a lower attachment size total (for example,
if the body includes several megabytes of text, causing the size
of the encoded MIME structure to be over some server-defined
limit).
o *canDelaySend*: "Boolean" Does the server support inserting a
message into the outbox to be sent later at a user-specified time?
o *messageListSortOptions*: "String[]" A list of all the message
properties the server supports for sorting by. This MAY include
properties the client does not recognise (for example custom
properties specified in a vendor extension). Clients MUST ignore
any unknown properties in the list.
2. Mailboxes
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; see below for more details.
For compatibility with IMAP, a message MUST belong to one or more
mailboxes. The message id does not change if the message changes
mailboxes.
A *Mailbox* object has the following properties:
o *id*: "String" The id of the mailbox. This property is immutable.
o *name*: "String" User-visible name for the mailbox, e.g. "Inbox".
This may be any UTF-8 string of at least 1 character in length and
Jenkins Expires April 22, 2017 [Page 4]
Internet-Draft JMAP Mail October 2016
maximum 256 bytes in size. Servers SHOULD forbid sibling
Mailboxes with the same name.
o *parentId*: "String|null" The mailbox id for the parent of this
mailbox, or "null" if this mailbox is at the top level. Mailboxes
form acyclic graphs (forests) directed by the child-to-parent
relationship. There MUST NOT be a loop.
o *role*: "String|null" Identifies system mailboxes. This property
can only be set on create. After the record has been created,
this property is immutable. The following values MUST be used for
the relevant mailboxes:
* "inbox" - the mailbox to which new mail is delivered by
default, unless diverted by a rule or spam filter etc.
* "archive" - messages the user does not need right now, but does
not wish to delete.
* "drafts" - messages the user is currently writing and are not
yet sent.
* "outbox" - messages the user has finished writing and wishes to
send (see the "setMessages" 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.
* "sent" - messages the user has sent.
* "trash" - messages the user has deleted.
* "spam" - messages considered spam by the server.
* "templates" - drafts which should be used as templates (i.e.
used as the basis for creating new drafts).
No two mailboxes may have the same role. Mailboxes without a
known purpose MUST have a role of "null". 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 ""x-"". The
client MAY attempt to create mailboxes with the standard roles if
not already present, but the server MAY reject these.
Jenkins Expires April 22, 2017 [Page 5]
Internet-Draft JMAP Mail October 2016
o *sortOrder*: "Number" Defines the sort order of mailboxes when
presented in the client's UI, so it is consistent between devices.
The number MUST be an integer in the range 0 <= sortOrder < 2^31.
A mailbox with a lower order should be displayed before a mailbox
with a higher order (that has the same parent) in any mailbox
listing in the client's UI. Mailboxes with equal order SHOULD be
sorted in alphabetical order by name. The sorting SHOULD take
into account locale-specific character order convention.
o *mustBeOnlyMailbox*: "Boolean" If "true", messages in this mailbox
may not also be in any other mailbox that also has
"mustBeOnlyMailbox: true". If "false", messages may be added to
this mailbox in addition to any other mailbox (i.e. it's a label).
This property is immutable.
o *mayReadItems*: "Boolean" If true, may use this mailbox as part of
a filter in a _getMessageList_ call. If a submailbox is shared
but not the parent mailbox, this may be "false".
o *mayAddItems*: "Boolean" The user may add messages to this mailbox
(by either creating a new message or moving an existing one).
o *mayRemoveItems*: "Boolean" The user may remove messages from this
mailbox (by either changing the mailboxes of a message or deleting
it).
o *mayCreateChild*: "Boolean" The user may create a mailbox with
this mailbox as its parent.
o *mayRename*: "Boolean" The user may rename the mailbox or make it
a child of another mailbox.
o *mayDelete*: "Boolean" The user may delete the mailbox itself.
o *totalMessages*: "Number" The number of messages in this mailbox.
o *unreadMessages*: "Number" The number of messages in this mailbox
where the _isUnread_ property of the message is "true" and the
_isDraft_ property is "false".
o *totalThreads*: "Number" 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).
o *unreadThreads*: "Number" The number of threads where at least one
message in the thread has "isUnread == true" and "isDraft ==
false" AND at least one message in the thread is in this mailbox
Jenkins Expires April 22, 2017 [Page 6]
Internet-Draft JMAP Mail October 2016
(but see below for special case handling of Trash). Note, the
unread message does not need to be the one in this mailbox.
The Trash mailbox (that is a mailbox with "role == "trash"") MUST be
treated specially:
o Messages in the Trash are ignored when calculating the
"unreadThreads" and "totalThreads" count of other mailboxes.
o Messages not in the Trash are ignored when calculating the
"unreadThreads" and "totalThreads" count for the Trash mailbox.
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.
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 "unreadThreads" count would be
"1" for the Trash and "0" for the Inbox.
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 "role ==
"inbox"". If no Inbox exists, the messages must be moved to any
other mailbox; this is server dependent.
2.1. getMailboxes
Mailboxes can either be fetched explicitly by id, or all of them at
once. To fetch mailboxes, make a call to "getMailboxes". It takes
the following arguments:
o *accountId*: "String|null" The Account to fetch the mailboxes for.
If "null", the primary account is used.
o *ids*: "String[]|null" The ids of the mailboxes to fetch. If
"null", all mailboxes in the account are returned.
o *properties*: "String[]|null" The properties of each mailbox to
fetch. If "null", all properties are returned. The id of the
mailbox will *always* be returned, even if not explicitly
requested.
Jenkins Expires April 22, 2017 [Page 7]
Internet-Draft JMAP Mail October 2016
The response to _getMailboxes_ is called _mailboxes_. It has the
following arguments:
o *accountId*: "String" The id of the account used for the call.
o *state*: "String" A string representing the state on the server
for *all* 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.
o *list*: "Mailbox[]" An array of the Mailbox objects requested.
This will be the *empty array* if the _ids_ argument was the empty
array, or contained only ids for mailboxes that could not be
found.
o *notFound*: "String[]|null" This array contains the ids passed to
the method for mailboxes that do not exist, or "null" if all
requested ids were found. It MUST be "null" if the _ids_ argument
in the call was "null".
The following errors may be returned instead of the _mailboxes_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"requestTooLarge": Returned if the number of _ids_ requested by the
client exceeds the maximum number the server is willing to process in
a single method call.
"invalidArguments": 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 "description" property MAY be present on the
response object to help debug with an explanation of what the problem
was.
2.2. getMailboxUpdates
The _getMailboxUpdates_ 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:
o *accountId*: "String|null" The id of the account to use for this
call. If "null", the primary account will be used.
Jenkins Expires April 22, 2017 [Page 8]
Internet-Draft JMAP Mail October 2016
o *sinceState*: "String" The current state of the client. This is
the string that was returned as the _state_ argument in the
_mailboxes_ response. The server will return the changes made
since this state.
o *fetchRecords*: "Boolean|null" If "true", immediately after
outputting a _mailboxUpdates_ response, an implicit call will be
made to _getMailboxes_ with the _changed_ property of the response
as the _ids_ argument, and the _fetchRecordProperties_ argument as
the _properties_ argument. If "false" or "null", no implicit call
will be made.
o *fetchRecordProperties*: "String[]|null" If "null", all Mailbox
properties will be fetched unless _onlyCountsChanged_ in the
_mailboxUpdates_ response is "true", in which case only the 4
counts properties will be returned (_totalMessages_,
_unreadMessages_, _totalThreads_ and _unreadThreads_). If not
"null", this value will be passed through to the _getMailboxes_
call regardless of the _onlyCountsChanged_ value in the
_mailboxUpdates_ response.
The response to _getMailboxUpdates_ is called _mailboxUpdates_. It
has the following arguments:
o *accountId*: "String" The id of the account used for the call.
o *oldState*: "String" This is the _sinceState_ argument echoed
back; the state from which the server is returning changes.
o *newState*: "String" This is the state the client will be in after
applying the set of changes to the old state.
o *changed*: "String[]" 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.
o *removed*: "String[]" An array of Mailbox ids for mailboxes which
have been destroyed since the old state.
o *onlyCountsChanged*: "Boolean" Indicates that only the mailbox
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 "false".
If a mailbox has been modified AND deleted since the oldState, the
server should just return the id in the _removed_ array, but MAY
Jenkins Expires April 22, 2017 [Page 9]
Internet-Draft JMAP Mail October 2016
return it in the _changed_ 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
_removed_ array.
The following errors may be returned instead of the "mailboxUpdates"
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"invalidArguments": 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 "description" property MAY be present on the
response object to help debug with an explanation of what the problem
was.
"cannotCalculateChanges": 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.
2.3. setMailboxes
Mailboxes can be created, updated and destroyed using the
_setMailboxes_ method. The method takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If "null", defaults to the primary account.
o *ifInState*: "String|null" This is a state string as returned by
the _getMailboxes_ method. If supplied, the string must match the
current state, otherwise the method will be aborted and a
"stateMismatch" error returned. If "null", any changes will be
applied to the current state.
o *create*: "String[Mailbox]|null" A map of _creation id_ (an
arbitrary string set by the client) to Mailbox objects. If
"null", no objects will be created.
o *update*: "String[Mailbox]|null" A map of mailbox id to objects
containing the properties to update for that Mailbox. If "null",
no objects will be updated.
Jenkins Expires April 22, 2017 [Page 10]
Internet-Draft JMAP Mail October 2016
o *destroy*: "String[]|null" A list of ids for Mailboxes to
permanently delete. If "null", no objects will be deleted.
If a create, update or destroy is rejected, the appropriate error
MUST 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.
2.3.1. Ordering of changes
Each create, update or destroy is considered an atomic unit. The
server MAY commit some of the changes but not others, however MUST
NOT only commit part of an update to a single record (e.g. update the
_name_ field but not the _parentId_ field, if both are supplied in
the update object).
The final state MUST be valid after the setMailboxes is finished,
however the server MAY have to transition through invalid
intermediate states (not exposed to the client) while processing the
individual create/update/destroy requests. For example, a single
method call could rename Mailbox A => B, and simultaneously rename
Mailbox B => A. The final state is valid, so this is allowed,
however if processed sequentially there will be an internal state
where temporarily both mailboxes have the same name.
A Mailbox may reference another Mailbox object as a parent. When a
Mailbox is created or modified, it may reference another Mailbox
being created _in the same API request_ by using the creation id
prefixed with a "#". The order of the method calls in the request by
the client MUST be such that the mailbox being referenced is created
in *either the same or an earlier method call*. If within the same
method call, the server MUST process the parent create first, as if
this fails the create/update that references it will also fail.
Creation ids sent by the client SHOULD be unique within the single
API request for a particular data type. If a creation id is reused,
the server MUST map the creation id to the most recently created item
with that id.
2.3.2. Creating mailboxes
The properties of the Mailbox object submitted for creation MUST
conform to the following conditions:
o The _id_ property MUST NOT be present.
o The _parentId_ property MUST be either "null" or be a valid id for
a mailbox for which the "mayCreateChild" property is "true".
Jenkins Expires April 22, 2017 [Page 11]
Internet-Draft JMAP Mail October 2016
o The _role_ property MUST be either "null", a valid role as listed
in the Mailbox object specification, or prefixed by ""x-"".
o The _mustBeOnlyMailbox_ property MUST NOT be present. This is
server dependent and will be set by the server.
o The _mayXXX_ properties MUST NOT be present. 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).
o The _totalMessages_, _unreadMessages_, _totalThreads_ and
_unreadThreads_ properties MUST NOT be present.
If any of the properties are invalid, the server MUST reject the
create with an "invalidProperties" error. The Error object SHOULD
contain a property called _properties_ of type "String[]" that lists
*all* the properties that were invalid. The object MAY also contain
a _description_ property of type "String" with a user-friendly
description of the problems.
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
"maxQuotaReached" error.
2.3.3. Updating mailboxes
If the _id_ given does not correspond to a Mailbox in the given
account, the update MUST be rejected with a "notFound" error.
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:
o The _name_ property MUST be a valid UTF-8 string of at least 1
character in length and maximum 256 bytes in size.
o The _parentId_ property MUST be either "null" or be a valid id for
_another_ mailbox that is *not a descendant* of this mailbox, and
for which the "mayCreateChild" property is "true".
o These properties are immutable or may only be set by the server:
* id
* role
Jenkins Expires April 22, 2017 [Page 12]
Internet-Draft JMAP Mail October 2016
* mustBeOnlyMailbox
* mayReadItems
* mayAddItems
* mayRemoveItems
* mayCreateChild
* mayRename
* mayDelete
* totalMessages
* unreadMessages
* totalThreads
* unreadThreads
If any of the properties are invalid, the server MUST reject the
update with an "invalidProperties" error. The Error object SHOULD
contain a property called _properties_ of type "String[]" that lists
*all* the properties that were invalid. The object MAY also contain
a _description_ property of type "String" with a user-friendly
description of the problems.
2.3.4. Destroying mailboxes
If the _id_ given does not correspond to a Mailbox in the given
account, the destruction MUST be rejected with a "notFound" error.
If the mailbox has "mayDeleteMailbox == false", the destruction MUST
be rejected with a "forbidden" error.
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 "mailboxHasChild" error.
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 "role ==
"inbox"". If no Inbox exists, the messages must be moved to any
other mailbox; this is server dependent.
Jenkins Expires April 22, 2017 [Page 13]
Internet-Draft JMAP Mail October 2016
There MUST always be *at least one* mailbox. It is expected that the
server will enforce this by setting "mayDeleteMailbox == false" 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 "mailboxRequired" error.
2.3.5. Response
The response to _setMailboxes_ is called _mailboxesSet_. It has the
following arguments:
o *accountId*: "String" The id of the account used for the call.
o *oldState*: "String|null" The state string that would have been
returned by "getMailboxes" before making the requested changes, or
"null" if the server doesn't know what the previous state string
was.
o *newState*: "String" The state string that will now be returned by
"getMailboxes".
o *created*: "String[Mailbox]" A map of the creation id to an object
containing all server-set properties for each successfully created
Mailbox: _id_, _mustBeOnlyMailbox_, all _mayXXX_ properties,
_totalMessages_, _unreadMessages_, _totalThreads_ and
_unreadThreads_.
o *updated*: "String[]" A list of ids for Mailboxes that were
successfully updated.
o *destroyed*: "String[]" A list of ids for Mailboxes that were
successfully destroyed.
o *notCreated*: "String[SetError]" A map of creation id to a
SetError object for each Mailbox that failed to be created. The
possible errors are defined above.
o *notUpdated*: "String[SetError]" A map of Mailbox id to a SetError
object for each Mailbox that failed to be updated. The possible
errors are defined above.
o *notDestroyed*: "String[SetError]" A map of Mailbox id to a
SetError object for each Mailbox that failed to be destroyed. The
possible errors are defined above.
The following errors may be returned instead of the _mailboxesSet_
response:
Jenkins Expires April 22, 2017 [Page 14]
Internet-Draft JMAP Mail October 2016
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"accountReadOnly": Returned if the account has "isReadOnly == true".
"requestTooLarge": Returned if the total number of objects to create,
update or destroy exceeds the maximum number the server is willing to
process in a single method call.
"invalidArguments": Returned if one of the arguments is of the wrong
type, or otherwise invalid. A _description_ property MAY be present
on the response object to help debug with an explanation of what the
problem was.
"stateMismatch": Returned if an "ifInState" argument was supplied and
it does not match the current state.
Example request:
[ "setMailboxes", {
"ifInState": "ms4123",
"update": {
"f3": {
"name": "The new name"
}
},
"destroy": [ "f5" ]
}, "#0" ]
3. MessageLists
A *MessageList* is a sorted query on the set of messages in a user's
account. 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.
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.
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
Jenkins Expires April 22, 2017 [Page 15]
Internet-Draft JMAP Mail October 2016
state. If the server doesn't support this, the client still only
needs to fetch the message list again, not the messages themselves.
3.1. getMessageList
To fetch a message list, make a call to _getMessageList_. It takes
the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If "null", the primary account will be used.
o *filter*: "FilterCondition|FilterOperator|null" Determines the set
of messages returned in the results. See the "Filtering" section
below for allowed values and semantics.
o *sort*: "String[]|null" A list of Message property names to sort
by. See the "Sorting" section below for allowed values and
semantics.
o *collapseThreads*: "Boolean|null" 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. If "false" or "null", threads may be
returned multiple times.
o *position*: "Number|null" 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 "invalidArguments" error. If "null", 0 is
used.
o *anchor*: "String|null" A Message id. The index of this message
id will be used in combination with the "anchorOffset" argument to
determine the index of the first result to return (see the
"Windowing" section below for more details).
o *anchorOffset*: "Number|null" The index of the anchor message
relative to the index of the first result to return. This MAY be
negative. For example, "-1" 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).
o *limit*: "Number|null" The maximum number of results to return.
If "null", no limit is presumed. The server MAY choose to enforce
a maximum "limit" 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
Jenkins Expires April 22, 2017 [Page 16]
Internet-Draft JMAP Mail October 2016
reached the end of the list. If a negative value is given, the
call MUST be rejected with an "invalidArguments" error.
o *fetchThreads*: "Boolean|null" If "true", after outputting a
_messageList_ response, an implicit call will be made to
_getThreads_ with the _threadIds_ array in the response as the
_ids_ argument, and the _fetchMessages_ and
_fetchMessageProperties_ arguments passed straight through from
the call to _getMessageList_. If "false" or "null", no implicit
call will be made.
o *fetchMessages*: "Boolean|null" If "true" and "fetchThreads ==
false", then after outputting a _messageList_ response, an
implicit call will be made to _getMessages_ with the "messageIds"
array in the response as the _ids_ argument, and the
_fetchMessageProperties_ argument as the _properties_ argument.
If "false" or "null", no implicit call will be made.
o *fetchMessageProperties*: "String[]|null" The list of properties
to fetch on any fetched messages. See _getMessages_ for a full
description.
o *fetchSearchSnippets*: "Boolean|null" If "true", then after
outputting a _messageList_ and making any other implicit calls, an
implicit call will be made to _getSearchSnippets_. The
_messageIds_ array from the response will be used as the
_messageIds_ argument, and the _filter_ argument will be passed
straight through. If "false" or "null", no implicit call will be
made.
3.1.1. Filtering
A *FilterOperator* object has the following properties:
o *operator*: "String" This MUST be one of the following strings:
"AND"/"OR"/"NOT":
* *AND*: all of the conditions must match for the filter to
match.
* *OR*: at least one of the conditions must match for the filter
to match.
* *NOT*: none of the conditions must match for the filter to
match.
o *conditions*: "(FilterCondition|FilterOperator)[]" The conditions
to evaluate against each message.
Jenkins Expires April 22, 2017 [Page 17]
Internet-Draft JMAP Mail October 2016
A *FilterCondition* object has the following properties:
o *inMailboxes*: "String[]|null" A list of mailbox ids. A message
must be in ALL of these mailboxes to match the condition.
o *notInMailboxes*: "String[]|null" A list of mailbox ids. A
message must NOT be in ANY of these mailboxes to match the
condition.
o *before*: "Date|null" The date of the message (as returned on the
Message object) must be before this date to match the condition.
o *after*: "Date|null" The date of the message (as returned on the
Message object) must be on or after this date to match the
condition.
o *minSize*: "Number|null" The size of the message in bytes (as
returned on the Message object) must be equal to or greater than
this number to match the condition.
o *maxSize*: "Number|null" The size of the message in bytes (as
returned on the Message object) must be less than this number to
match the condition.
o *threadIsFlagged*: "Boolean|null" If "true", the condition is
matched if the "isFlagged" property of _any_ message in the same
thread as the message being examined is "true". If "false", the
"isFlagged" property of _every_ message in the same thread as the
message being examined must be "false" to match the condition.
o *threadIsUnread*: "Boolean|null" If "true", the condition is
matched if the "isUnread" property of _any_ message in the same
thread as the message being examined is "true". If "false", the
"isUnread" property of _every_ message in the same thread as the
message being examined must be "false" to match the condition.
o *isFlagged*: "Boolean|null" The "isFlagged" property of the
message must be identical to the value given to match the
condition.
o *isUnread*: "Boolean|null" The "isUnread" property of the message
must be identical to the value given to match the condition.
o *isAnswered*: "Boolean|null" The "isAnswered" property of the
message must be identical to the value given to match the
condition.
Jenkins Expires April 22, 2017 [Page 18]
Internet-Draft JMAP Mail October 2016
o *isDraft*: "Boolean|null" The "isDraft" property of the message
must be identical to the value given to match the condition.
o *hasAttachment*: "Boolean|null" The "hasAttachment" property of
the message must be identical to the value given to match the
condition.
o *text*: "String|null" Looks for the text in the _from_, _to_,
_cc_, _bcc_, _subject_, _textBody_ or _htmlBody_ properties of the
message.
o *from*: "String|null" Looks for the text in the _from_ property of
the message.
o *to*: "String|null" Looks for the text in the _to_ property of the
message.
o *cc*: "String|null" Looks for the text in the _cc_ property of the
message.
o *bcc*: "String|null" Looks for the text in the _bcc_ property of
the message.
o *subject*: "String|null" Looks for the text in the _subject_
property of the message.
o *body*: "String|null" Looks for the text in the _textBody_ or
_htmlBody_ property of the message.
o *header*: "String[]|null" 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
_has_ a header of the given name.
If zero properties are specified on the FilterCondition, the
condition MUST always evaluate to "true". If multiple properties are
specified, ALL must apply for the condition to be "true" (it is
equivalent to splitting the object into one-property conditions and
making them all the child of an AND filter operator).
The exact semantics for matching "String" fields is *deliberately not
defined* to allow for flexibility in indexing implementation, subject
to the following:
o Text SHOULD be matched in a case-insensitive manner.
Jenkins Expires April 22, 2017 [Page 19]
Internet-Draft JMAP Mail October 2016
o Text contained in either (but matched) single or double quotes
SHOULD be treated as a *phrase search*, that is a match is
required for that exact sequence of words, excluding the
surrounding quotation marks. Use "\"", "\'" and "\\" to match a
literal """, "'" and "\" respectively in a phrase.
o 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.
o Tokens MAY be matched on a whole-word basis using stemming (so for
example a text search for "bus" would match "buses" but not
"business").
o When searching inside the _htmlBody_ property, HTML tags and
attributes SHOULD be ignored.
3.1.2. Sorting
The "sort" 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 or "null" is given as the
argument), the sort order is server-dependent, but MUST be stable
between calls to "getMessageList".
Following the property name there MUST be a space and then either the
string "asc" or "desc" to specify ascending or descending sort for
that property.
The following properties MUST be supported for sorting:
o *id* - The id as returned in the Message object.
o *date* - The date as returned in the Message object.
The following properties SHOULD be supported for sorting:
o *size* - The size as returned in the Message object.
o *from* - 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.
Jenkins Expires April 22, 2017 [Page 20]
Internet-Draft JMAP Mail October 2016
o *to* - This is taken to be either the "name" part of the *first*
Emailer object, or if none then the "email" part of the *first*
Emailer object (see the definition of the to property in the
Message object). If still none, consider the value to be the
empty string.
o *subject* - This is taken to be the subject of the Message with
any ignoring any leading "Fwd:"s or "Re:"s (case-insensitive
match).
o *threadIsFlagged* - This value MUST be considered "true" for the
message if *any* of the messages in the same thread (regardless of
mailbox) have "isFlagged: true".
o *threadIsUnread* - This value MUST be considered "true" for the
message if *any* of the messages in the same thread (regardless of
mailbox) have "isUnread: true".
o *isFlagged* - The "isFlagged" state of the message (only).
o *isUnread* - The "isUnread" state of the message (only).
The server MAY support sorting based on other properties as well. A
client can discover which properties are supported by inspecting the
server's _capabilities_ object (see section 1).
The method of comparison depends on the type of the property:
o "String": 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.
o "Date": If sorting in ascending order, the earlier date MUST come
first.
o "Boolean": If sorting in ascending order, a "false" value MUST
come before a "true" value.
3.1.3. Thread collapsing
When "collapseThreads == true", 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 *once* in
the "threadIds" list of the result, at the position of the first
message in the list that belongs to the thread.
Jenkins Expires April 22, 2017 [Page 21]
Internet-Draft JMAP Mail October 2016
3.1.4. Windowing
If a _position_ 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. If
_position_ is "null" (or, equivalently, omitted) this MUST be
interpreted as "position: 0".
Alternatively, a message id, called the *anchor* may be given. In
this case, after filtering, sorting and collapsing threads, the
anchor is searched for in the message list. If found, the *anchor
offset* 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 "position" argument. If the anchor
is not found, the call is rejected with an "anchorNotFound" error.
If an _anchor_ is specified, any position argument supplied by the
client MUST be ignored. If _anchorOffset_ is "null", it defaults to
"0". If no _anchor_ is supplied, any anchor offset argument MUST be
ignored.
3.1.5. Response
The response to a call to _getMessageList_ is called _messageList_.
It has the following arguments:
o *accountId*: "String" The id of the account used for the call.
o *filter*: "FilterCondition|FilterOperator|null" The filter of the
message list. Echoed back from the call.
o *sort*: "String[]|null" A list of Message property names used to
sort by. Echoed back from the call.
o *collapseThreads*: "Boolean|null" Echoed back from the call.
o *state*: "String" 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
_getMessageListUpdates_ to efficiently get the set of changes from
the previous state. 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,
Jenkins Expires April 22, 2017 [Page 22]
Internet-Draft JMAP Mail October 2016
if the server supports it, call _getMessageListUpdates_ to get the
delta difference.
o *canCalculateUpdates*: "Boolean" This is "true" if the server
supports calling "getMessageListUpdates" with these
"filter"/"sort"/"collapseThreads" 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.
o *position*: "Number" The 0-based index of the first result in the
"threadIds" array within the complete list.
o *total*: "Number" The total number of messages in the message list
(given the _filter_ and _collapseThreads_ arguments).
o *threadIds*: "String[]" The list of Thread ids for each message in
the list after filtering, sorting and collapsing threads, starting
at the index given by the _position_ argument of this response,
and continuing until it hits the end of the list or reaches the
"limit" number of ids.
o *messageIds*: "String[]" The list of Message ids for each message
in the list after filtering, sorting and collapsing threads,
starting at the index given by the _position_ argument of this
response, and continuing until it hits the end of the list or
reaches the "limit" number of ids.
The following errors may be returned instead of the "messageList"
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"unsupportedSort": Returned if the _sort_ includes a property the
server does not support sorting on.
"cannotDoFilter": Returned if the server is unable to process the
given _filter_ for any reason.
"invalidArguments": 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 "description" property MAY be present on the
Jenkins Expires April 22, 2017 [Page 23]
Internet-Draft JMAP Mail October 2016
response object to help debug with an explanation of what the problem
was.
"anchorNotFound": Returned if an anchor argument was supplied, but it
cannot be found in the message list.
3.2. getMessageListUpdates
The "getMessageListUpdates" 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:
o *accountId*: "String|null" The id of the account to use for this
call. If "null", the primary account will be used.
o *filter*: "FilterCondition|FilterOperator|null" The filter
argument that was used with _getMessageList_.
o *sort*: "String[]|null" The sort argument that was used with
_getMessageList_.
o *collapseThreads*: "Boolean|null" The _collapseThreads_ argument
that was used with _getMessageList_.
o *sinceState*: "String" The current state of the client. This is
the string that was returned as the _state_ argument in the
_messageList_ response. The server will return the changes made
since this state.
o *uptoMessageId*: "String|null" 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.
o *maxChanges*: "Number|null" The maximum number of changes to
return in the response. See below for a more detailed
description.
The response to _getMessageListUpdates_ is called
_messageListUpdates_ It has the following arguments:
o *accountId*: "String" The id of the account used for the call.
o *filter*: "FilterCondition|FilterOperator|null" The filter of the
message list. Echoed back from the call.
Jenkins Expires April 22, 2017 [Page 24]
Internet-Draft JMAP Mail October 2016
o *sort*: "String[]|null" A list of Message property names used to
sort by. Echoed back from the call.
o *collapseThreads*: "Boolean|null" Echoed back from the call.
o *oldState*: "String" This is the "sinceState" argument echoed
back; the state from which the server is returning changes.
o *newState*: "String" This is the state the client will be in after
applying the set of changes to the old state.
o *uptoMessageId*: "String|null" Echoed back from the call.
o *total*: "Number" The total number of messages in the message list
(given the filter and collapseThreads arguments).
o *removed*: "RemovedItem[]" The _messageId_ and _threadId_ 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. If an
_uptoMessageId_ was given AND this id was found in the list, only
messages positioned before this message that were removed need be
returned. In addition, if the sort includes the property
_isUnread_ or _isFlagged_, the server MUST include all messages in
the current list for which this property MAY have changed. If
"collapseThreads == true", then the server MUST include all
messages in the current list for which this property MAY have
changed *on any of the messages in the thread*.
o *added*: "AddedItem[]" 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 _removed_ array (due to a filter or sort
based upon a mutable property). The array MUST be sorted in order
of index, lowest index first. If an _uptoMessageId_ was given AND
this id was found in the list, only messages positioned before
this message that have been added need be returned.
A *RemovedItem* object has the following properties:
o *messageId*: "String"
o *threadId*: "String"
An *AddedItem* object has the following properties:
o *messageId*: "String"
Jenkins Expires April 22, 2017 [Page 25]
Internet-Draft JMAP Mail October 2016
o *threadId*: "String"
o *index*: "Number"
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:
messageIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ]
then if it *splices out* all messages in the removed array:
removed = [{ messageId: "id2", ... }];
messageIds => [ "id1", null, null, "id3", "id4", null, null, null ]
and *splices in* (in order) all of the messages in the added array:
added = [{ messageId: "id5", index: 0, ... }];
messageIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ]
then the message list will now be in the new state.
The following errors may be returned instead of the
"messageListUpdates" response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"invalidArguments": 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 _description_ property MAY be present on the
response object to help debug with an explanation of what the problem
was.
"tooManyChanges": Returned if there are more changes the the client's
_maxChanges_ argument. Each item in the removed or added array is
considered as one change. The client may retry with a higher max
changes or invalidate its cache of the message list.
"cannotCalculateChanges": 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
cache of the message list.
Jenkins Expires April 22, 2017 [Page 26]
Internet-Draft JMAP Mail October 2016
4. Threads
Replies are grouped together with the original message to form a
thread. In JMAP, a thread is simply a flat list of messages, ordered
by date. Every message MUST belong to a thread, even if it is the
only message in the thread.
The JMAP spec does not require the server to use any particular
algorithm for determining whether two messages belong to the same
thread, however there is a recommended algorithm in the
implementation guide [1].
If messages are delivered out of order for some reason, a user may
receive two messages in the same thread but without headers that
associate them with each other. The arrival of a third message in
the thread may provide the missing references to join them all
together into a single thread. Since the "threadId" of a message is
immutable, if the server wishes to merge the threads, it MUST handle
this by deleting and reinserting (with a new message id) the messages
that change threadId.
A *Thread* object has the following properties:
o *id*: "String" The id of the thread. This property is immutable.
o *messageIds*: "String[]" The ids of the messages in the thread,
sorted such that:
* Any message with "isDraft == true" and an _inReplyToMessageId_
property that corresponds to another message in the thread
comes immediately after that message in the sort order.
* Other than that, everything is sorted in date order (the same
as the _date_ property on the Message object), oldest first.
4.1. getThreads
Threads can only be fetched explicitly by id. To fetch threads, make
a call to _getThreads_. It takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If not given, defaults to the primary account.
o *ids*: "String[]" An array of ids for the threads to fetch.
o *fetchMessages*: "Boolean|null" If true, after outputting a
_threads_ response, an implicit call will be made to _getMessages_
with a list of all message ids in the returned threads as the
Jenkins Expires April 22, 2017 [Page 27]
Internet-Draft JMAP Mail October 2016
_ids_ argument, and the _fetchMessageProperties_ argument as the
_properties_ argument. If "false" or "null", no implicit call
will be made.
o *fetchMessageProperties*: "String[]|null" The list of properties
to fetch on any fetched messages. See _getMessages_ for a full
description.
The response to _getThreads_ is called _threads_. It has the
following arguments:
o *accountId*: "String" The id of the account used for the call.
o *state*: "String" A string encoding the current state on the
server. This string will change if any threads change (that is,
new messages arrive, or messages are deleted, as these are the
only two events that change thread membership). It can be passed
to _getThreadUpdates_ to efficiently get the list of changes from
the previous state.
o *list*: "Thread[]" An array of Thread objects for the requested
thread ids. This may not be in the same order as the ids were in
the request.
o *notFound*: "String[]|null" An array of thread ids requested which
could not be found, or "null" if all ids were found.
The following errors may be returned instead of the "threads"
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"requestTooLarge": Returned if the number of _ids_ requested by the
client exceeds the maximum number the server is willing to process in
a single method call.
"invalidArguments": 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 _description_ property MAY be present on the
response object to help debug with an explanation of what the problem
was.
Example of a successful request:
Jenkins Expires April 22, 2017 [Page 28]
Internet-Draft JMAP Mail October 2016
[ "getThreads", {
"ids": ["f123u4", "f41u44"],
"fetchMessages": false,
"fetchMessageProperties": null
}, "#1" ]
and response:
[ "threads", {
"state": "f6a7e214",
"list": [
{
"id": "f123u4",
"messageIds": [ "eaa623", "f782cbb"]
},
{
"id": "f41u44",
"messageIds": [ "82cf7bb" ]
}
],
"notFound": null
}, "#1" ]
4.2. getThreadUpdates
When messages are created or deleted, new threads may be created, or
the set of messages belonging to an existing thread may change. If a
call to _getThreads_ returns with a different _state_ string in the
response to a previous call, the state of the threads has changed on
the server and the client needs to work out which part of its cache
is now invalid.
The _getThreadUpdates_ call allows a client to efficiently update the
state of any cached threads to match the new state on the server. It
takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If not given, defaults to the primary account.
o *sinceState*: "String" The current state of the client. This is
the string that was returned as the _state_ argument in the
_threads_ response. The server will return the changes made since
this state.
o *maxChanges*: "Number|null" The maximum number of Thread ids to
return in the response. The server MAY choose to clamp this value
to a particular maximum or set a maximum if none is given by the
client. If supplied by the client, the value MUST be a positive
Jenkins Expires April 22, 2017 [Page 29]
Internet-Draft JMAP Mail October 2016
integer greater than 0. If a value outside of this range is
given, the server MUST reject the call with an "invalidArguments"
error.
o *fetchRecords*: "Boolean|null" If "true", immediately after
outputting a _threadUpdates_ response, an implicit call will be
made to _getThreads_ with the _changed_ property of the response
as the _ids_ argument, and _fetchMessages_ equal to "false".
The response to _getThreadUpdates_ is called _threadUpdates_. It has
the following arguments:
o *accountId*: "String" The id of the account used for the call.
o *oldState*: "String" This is the _sinceState_ argument echoed
back; the state from which the server is returning changes.
o *newState*: "String" This is the state the client will be in after
applying the set of changes to the old state.
o *hasMoreUpdates*: "Boolean" If "true", the client may call
_getThreadUpdates_ again with the _newState_ returned to get
further updates. If "false", _newState_ is the current server
state.
o *changed*: "String[]" An array of thread ids where the list of
messages within the thread has changed between the old state and
the new state, and the thread currently has at least one message
in it.
o *removed*: "String[]" An array of thread ids where the list of
messages within the thread has changed since the old state, and
there are now no messages in the thread.
If a _maxChanges_ is supplied, or set automatically by the server,
the server MUST ensure the number of ids returned across _changed_
and _removed_ does not exceed this limit. If there are more changes
than this between the client's state and the current server state,
the update returned SHOULD generate an update to take the client to
an intermediate state, from which the client can continue to call
_getThreadUpdates_ until it is fully up to date. If it is unable to
calculat an intermediate state, it MUST return a
"cannotCalculateChanges" error response instead.
If a thread has been modified AND deleted since the oldState, the
server SHOULD just return the id in the _removed_ response, but MAY
return it in the changed response as well. If a thread has been
created AND deleted since the oldState, the server SHOULD remove the
Jenkins Expires April 22, 2017 [Page 30]
Internet-Draft JMAP Mail October 2016
thread id from the response entirely, but MAY include it in the
_removed_ response.
The following errors may be returned instead of the _threadUpdates_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"invalidArguments": 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 _description_ property MAY be present on the
response object to help debug with an explanation of what the problem
was.
"cannotCalculateChanges": 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, or the server being unable to
produce an update to an intermediate state when there are too many
updates. The client MUST invalidate its Thread cache.
5. Messages
Just like in IMAP, a message is *immutable* except for the boolean
"isXXX" status properties and the set of mailboxes it is in. This
allows for more efficient caching of messages, and gives easier
backwards compatibility for servers implementing an IMAP interface to
the same data.
JMAP completely hides the complexities of MIME. All special
encodings of either headers or the body, such as base64 [2], or RFC
2047 [3] encoding of non-ASCII characters, MUST be fully decoded into
standard UTF-8.
A *Message* object has the following properties:
o *id*: "String" The id of the message.
o *blobId*: "String" The id representing the raw [RFC5322] message.
This may be used to download the original message or to attach it
directly to another message etc.
o *threadId*: "String" The id of the thread to which this message
belongs.
Jenkins Expires April 22, 2017 [Page 31]
Internet-Draft JMAP Mail October 2016
o *mailboxIds*: "String[]" (Mutable) The ids of the mailboxes the
message is in. A message MUST belong to one or more mailboxes at
all times (until it is deleted).
o *inReplyToMessageId*: "String|null" The id of the Message this
message is a reply to. This is primarily for drafts, but the
server MAY support this for received messages as well by looking
up the [RFC5322] Message-Id referenced in the "In-Reply-To" header
and searching for this message in the user's mail.
o *isUnread*: "Boolean" (Mutable) Has the message not yet been read?
This corresponds to the *opposite* of the "\Seen" system flag in
IMAP.
o *isFlagged*: "Boolean" (Mutable) Is the message flagged? This
corresponds to the "\Flagged" system flag in IMAP.
o *isAnswered*: "Boolean" (Mutable) Has the message been replied to?
This corresponds to the "\Answered" system flag in IMAP.
o *isDraft*: "Boolean" (Mutable by the server only) Is the message a
draft? This corresponds to the "\Draft" system flag in IMAP.
o *hasAttachment*: "Boolean" Does the message have any attachments?
o *headers*: "String[String]" A map of lower-cased header name to
(decoded) header value for all headers in the message. For
headers that occur multiple times (e.g. "Received"), the values
are concatenated with a single new line ("\n") character in
between each one.
o *sender*: "Emailer|null" An Emailer object (see below) containing
the name/email from the parsed "Sender" header of the email. If
the email doesn't have a "Sender" header, this is "null".
o *from*: "Emailer[]|null" An array of name/email objects (see
below) representing the parsed "From" header of the email, in the
same order as they appear in the header. If the email doesn't
have a "From" header, this is "null". If the header exists but
does not have any content, the response is an array of zero
length.
o *to*: "Emailer[]|null" An array of name/email objects (see below)
representing the parsed "To" header of the email, in the same
order as they appear in the header. If the email doesn't have a
"To" header, this is "null". If the header exists but does not
have any content, the response is an array of zero length.
Jenkins Expires April 22, 2017 [Page 32]
Internet-Draft JMAP Mail October 2016
o *cc*: "Emailer[]|null" An array of name/email objects (see below)
representing the parsed "Cc" header of the email, in the same
order as they appear in the header. If the email doesn't have a
"Cc" header, this is "null". If the header exists but does not
have any content, the response is an array of zero length.
o *bcc*: "Emailer[]|null" An array of name/email objects (see below)
representing the parsed "Bcc" header of the email. If the email
doesn't have a "Bcc" header (which will be true for most emails
outside of the Sent mailbox), this is "null". If the header
exists but does not have any content, the response is an array of
zero length.
o *replyTo*: "Emailer[]|null" An array of name/email objects (see
below) representing the parsed "Reply-To" header of the email, in
the same order as they appear in the header. If the email doesn't
have a "Reply-To" header, this is "null". If the header exists
but does not have any content, the response is an array of zero
length.
o *subject*: "String" The subject of the message.
o *date*: "Date" The date the message was sent (or saved, if the
message is a draft).
o *size*: "Number" The size in bytes of the whole message as counted
by the server towards the user's quota.
o *preview*: "String" Up to 256 characters of the beginning of a
plain text version of the message body. This is intended to be
shown as a preview line on a mailbox listing, and the server may
choose to skip quoted sections or salutations to return a more
useful preview.
o *textBody*: "String" The plain text body part for the message. If
there is only an HTML version of the body, a plain text version
MUST be generated from this; the exact method of conversion in
this case is not defined and is server-specific.
o *htmlBody*: "String|null" The HTML body part for the message if
present.
o *attachments*: "Attachment[]|null" An array of attachment objects
(see below) detailing all the attachments to the message.
o *attachedMessages*: "String[Message]|null" An object mapping
attachment id (as found in the "attachments" property) to a
Jenkins Expires April 22, 2017 [Page 33]
Internet-Draft JMAP Mail October 2016
*Message* object with the following properties, for each [RFC5322]
message attached to this one:
* headers
* from
* to
* cc
* bcc
* replyTo
* subject
* date
* textBody
* htmlBody
* attachments
* attachedMessages
An *Emailer* object has the following properties:
o *name*: "String" The name of the sender/recipient. If a name
cannot be extracted for an email, this property SHOULD be the
empty string.
o *email*: "String" The email address of the sender/recipient. This
MUST be of the form ""<mailbox>@<host>"" If a "host" or even
"mailbox" cannot be extracted for an email, the empty string
SHOULD be used for this part (so the result MUST always still
contain an ""@"" character).
Group information and comments from the RFC 5322 header MUST be
discarded when converting into an Emailer object.
Example array of Emailer objects:
Jenkins Expires April 22, 2017 [Page 34]
Internet-Draft JMAP Mail October 2016
[
{name:"Joe Bloggs", email:"joeb@example.com"},
{name:"", email:"john@example.com"},
{name:"John Smith", email: "john@"}
]
An *Attachment* object has the following properties:
o *blobId*: "String" The id of the binary data.
o *type*: "String" The content-type of the attachment.
o *name*: "String|null" The full file name, e.g.
"myworddocument.doc", if available.
o *size*: "Number" The size, in bytes, of the attachment when fully
decoded (i.e. the number of bytes in the file the user would
download).
o *cid*: "String|null" The id used within the message body to
reference this attachment. This is only unique when paired with
the message id, and has no meaning without reference to that.
o *isInline*: "Boolean" True if the attachment is referenced by a
"cid:" link from within the HTML body of the message.
o *width*: "Number|null" The width (in px) of the image, if the
attachment is an image.
o *height*: "Number|null" The height (in px) of the image, if the
attachment is an image.
5.1. getMessages
Messages can only be fetched explicitly by id. To fetch messages,
make a call to "getMessages". It takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If not given, defaults to the primary account.
o *ids*: "String[]" An array of ids for the messages to fetch.
o *properties*: "String[]|null" A list of properties to fetch for
each message. If "null", all properties will be fetched.
The "id" property is always returned, regardless of whether it is in
the list of requested properties. The possible values for
"properties" can be found above in the description of the Message
Jenkins Expires April 22, 2017 [Page 35]
Internet-Draft JMAP Mail October 2016
object. In addition to this, the client may request the following
special values:
o *body*: If ""body"" is included in the list of requested
properties, it will be interpreted by the server as a request for
""htmlBody"" if the message has an HTML part, or ""textBody""
otherwise.
o *headers.property*: Instead of requesting all the headers (by
requesting the ""headers"" property, the client may specify the
particular headers it wants using the "headers.property-name"
syntax, e.g. ""headers.x-spam-score", "headers.x-spam-hits"").
The server will return a _headers_ property but with just the
requested headers in the object rather than all headers. If
""headers"" is requested, the server MUST ignore the individual
header requests and just return all headers. If a requested
header is not present in the message, it MUST not be present in
the _headers_ object. Header names are case-insensitive.
The response to _getMessages_ is called _messages_. It has the
following arguments:
o *accountId*: "String" The id of the account used for the call.
o *state*: "String" A string encoding the current state on the
server. This string will change if any messages change (that is,
a new message arrives, a change is made to one of the mutable
properties, or a message is deleted). It can be passed to
_getMessageUpdates_ to efficiently get the list of changes from
the previous state.
o *list*: "Message[]" An array of Message objects for the requested
message ids. This may not be in the same order as the ids were in
the request.
o *notFound*: "String[]|null" An array of message ids requested
which could not be found, or "null" if all ids were found.
The following errors may be returned instead of the _messages_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
Jenkins Expires April 22, 2017 [Page 36]
Internet-Draft JMAP Mail October 2016
"requestTooLarge": Returned if the number of _ids_ requested by the
client exceeds the maximum number the server is willing to process in
a single method call.
"invalidArguments": 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 _description_ property MAY be present on the
response object to help debug with an explanation of what the problem
was.
Example request:
["getMessages", {
"ids": [ "f123u456", "f123u457" ],
"properties": [ "threadId", "mailboxIds", "from", "subject", "date" ]
}, "#1"]
and response:
["messages", {
"state": "41234123231",
"list": [
{
messageId: "f123u457",
threadId: "ef1314a",
mailboxIds: [ "f123" ],
from: [{name: "Joe Bloggs", email: "joe@bloggs.com"}],
subject: "Dinner on Thursday?",
date: "2013-10-13T14:12:00Z"
}
],
notFound: [ "f123u456" ]
}, "#1"]
5.2. getMessageUpdates
If a call to _getMessages_ returns with a different _state_ string in
the response to a previous call, the state of the messages has
changed on the server. For example, a new message may have been
delivered, or an existing message may have changed mailboxes.
The _getMessageUpdates_ call allows a client to efficiently update
the state of any cached messages to match the new state on the
server. It takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If not given, defaults to the primary account.
Jenkins Expires April 22, 2017 [Page 37]
Internet-Draft JMAP Mail October 2016
o *sinceState*: "String" The current state of the client. This is
the string that was returned as the _state_ argument in the
_messages_ response. The server will return the changes made
since this state.
o *maxChanges*: "Number|null" The maximum number of changed messages
to return in the response. The server MAY choose to clamp this
value to a particular maximum or set a maximum if none is given by
the client. If supplied by the client, the value MUST be a
positive integer greater than 0. If a value outside of this range
is given, the server MUST reject the call with an
"invalidArguments" error.
o *fetchRecords*: "Boolean|null" If true, immediately after
outputting a _messageUpdates_ response, an implicit call will be
made to _getMessages_ with a list of all message ids in the
_changed_ argument of the response as the _ids_ argument, and the
_fetchRecordProperties_ argument as the _properties_ argument.
o *fetchRecordProperties*: "String[]|null" The list of properties to
fetch on any fetched messages. See _getMessages_ for a full
description.
The response to _getMessageUpdates_ is called _messageUpdates_. It
has the following arguments:
o *accountId*: "String" The id of the account used for the call.
o *oldState*: "String" This is the _sinceState_ argument echoed
back; the state from which the server is returning changes.
o *newState*: "String" This is the state the client will be in after
applying the set of changes to the old state.
o *hasMoreUpdates*: "Boolean" If "true", the client may call
_getMessageUpdates_ again with the _newState_ returned to get
further updates. If "false", _newState_ is the current server
state.
o *changed*: "String[]" An array of message ids for messages that
have either been created or had their state change, and are not
currently deleted.
o *removed*: "String[]" An array of message ids for messages that
have been deleted since the oldState.
If a _maxChanges_ is supplied, or set automatically by the server,
the server MUST ensure the number of ids returned across _changed_
Jenkins Expires April 22, 2017 [Page 38]
Internet-Draft JMAP Mail October 2016
and _removed_ does not exceed this limit. If there are more changes
than this between the client's state and the current server state,
the update returned SHOULD generate an update to take the client to
an intermediate state, from which the client can continue to call
_getMessageUpdates_ until it is fully up to date. If it is unable to
calculat an intermediate state, it MUST return a
"cannotCalculateChanges" error response instead.
If a message has been modified AND deleted since the oldState, the
server SHOULD just return the id in the _removed_ response, but MAY
return it in the changed response as well. If a message has been
created AND deleted since the oldState, the server SHOULD remove the
message id from the response entirely, but MAY include it in the
_removed_ response, and (if in the _removed_ response) MAY included
it in the _changed_ response as well.
The following errors may be returned instead of the _messageUpdates_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"invalidArguments": 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 _description_ property MAY be present on the
response object to help debug with an explanation of what the problem
was.
"cannotCalculateChanges": 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, or the server being unable to
produce an update to an intermediate state when there are too many
updates. The client MUST invalidate its Message cache.
5.3. setMessages
The _setMessages_ method encompasses:
o Creating a draft message
o Sending a message
o Changing the flags of a message (unread/flagged status)
Jenkins Expires April 22, 2017 [Page 39]
Internet-Draft JMAP Mail October 2016
o Adding/removing a message to/from mailboxes (moving a message)
o Deleting messages
It takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If not given, defaults to the primary account.
o *ifInState*: "String|null" This is a state string as returned by
the _getMessages_ method. If supplied, the string must match the
current state, otherwise the method will be aborted and a
"stateMismatch" error returned. If "null", any changes will be
applied to the current state.
o *create*: "String[Message]|null" A map of _creation id_ (an
arbitrary string set by the client) to Message objects (see below
for a detailed description).
o *update*: "String[Message]|null" A map of message id to objects
containing the properties to update for that Message.
o *destroy*: "String[]|null" A list of ids for Message objects to
permanently delete.
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 the _isFlagged_ field but not
the _mailboxIds_ field, if both are supplied in the update object for
a message).
If a create, update or destroy is rejected, the appropriate error
MUST 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.
If an id given cannot be found, the update or destroy MUST be
rejected with a "notFound" set error.
5.3.1. Saving a draft
Creating messages via the _setMessages_ method is only for creating
draft messages and sending them. For delivering/importing a complete
[RFC5322] message, use the "importMessages" method.
The properties of the Message object submitted for creation MUST
conform to the following conditions:
Jenkins Expires April 22, 2017 [Page 40]
Internet-Draft JMAP Mail October 2016
o *id*: This property MUST NOT be included. It is set by the server
upon creation.
o *blobId*: This property MUST NOT be included. It is set by the
server upon creation.
o *threadId*: This property MUST NOT be included. It is set by the
server upon creation.
o *mailboxIds*: This property MUST be included. The value MUST
include the id of either the mailbox with "role == "drafts"" (to
save a draft) or the mailbox with "role == "outbox"" (to send the
message). If this mailbox does not have "mustBeOnlyMailbox ==
true", others may be included too.
o *inReplyToMessageId*: Optional. If included, the server will look
up this message and if found set appropriate "References" and "In-
Reply-To" headers. These will override any such headers supplied
in the _headers_ property. If not found, the creation MUST be
rejected with an "inReplyToNotFound" error.
o *isUnread*: Optional, defaults to "false". If included this MUST
be "false".
o *isFlagged*: Optional, defaults to "false".
o *isAnswered*: Optional, defaults to "false". If included this
MUST be "false".
o *isDraft*: Optional, defaults to "true". If included this MUST be
"true".
o *hasAttachment*: This property MUST NOT be included. It is set by
the server upon creation based on the attachments property.
o *headers*: Optional. The keys MUST only contain the characters
a-z (lower-case only), 0-9 and hyphens.
o *from*: Optional. Overrides a "From" in the _headers_.
o *to*: Optional. Overrides a "To" in the _headers_.
o *cc*: Optional. Overrides a "Cc" in the _headers_.
o *bcc*: Optional. Overrides a "Bcc" in the _headers_.
o *replyTo*: Optional. Overrides a "Reply-To" in the _headers_.
Jenkins Expires April 22, 2017 [Page 41]
Internet-Draft JMAP Mail October 2016
o *subject*: Optional. Defaults to the empty string ("""").
o *date*: Optional. If included, the server SHOULD wait until this
time to send the message (once moved to the outbox mailbox).
Until it is sent, the send may be cancelled by moving the message
back out of the outbox mailbox. If the date is in the past, the
message must be sent immediately. A client may find out if the
server supports delayed sending by querying the server's
_capabilities_ object (see section 1).
o *size*: This MUST NOT be included. It is set by the server upon
creation.
o *preview*: This MUST NOT be included. It is set by the server
upon creation.
o *textBody*: Optional. If not supplied and an htmlBody is, the
server SHOULD generate a text version for the message from the
HTML body.
o *htmlBody*: Optional.
o *attachments*: Optional. An array of Attachment objects detailing
all the attachments to the message. To add an attachment, the
file must first be uploaded using the standard upload mechanism;
this will give the client a blobId that may be used to identify
the file. The "cid" property may be assigned by the client, and
is solely used for matching up with "cid:<id>" links inside the
"htmlBody". The server MAY change the cids upon sending.
If any of the files specified in _attachments_ cannot be found, the
creation MUST be rejected with an "invalidProperties" error. An
extra property SHOULD be included in the error object called
"attachmentsNotFound", of type "String[]", which SHOULD be an array
of the _blobId_ of every attachment that could not be found on the
server. - *attachedMessages*: This MUST NOT be included.
All optional properties default to "null" unless otherwise stated.
Where included, properties MUST conform to the type given in the
Message object definition.
If any of the properties are invalid, the server MUST reject the
create with an "invalidProperties" error. The Error object SHOULD
contain a property called _properties_ of type "String[]" that lists
*all* the properties that were invalid. The object MAY also contain
a _description_ property of type "String" with a user-friendly
description of the problems.
Jenkins Expires April 22, 2017 [Page 42]
Internet-Draft JMAP Mail October 2016
Other than making sure it conforms to the correct type, the server
MUST NOT attempt to validate from/to/cc/bcc when saved as a draft.
This is to ensure messages can be saved at any point. Validation
occurs when the user tries to send a message.
If a draft cannot be saved due to the user reaching their maximum
mail storage quota, the creation MUST be rejected with a
"maxQuotaReached" error.
5.3.2. Updating messages
Messages are mainly immutable, so to update a draft the client must
create a new message and delete the old one. This ensures that if
the draft is also being edited elsewhere, the two will split into two
different drafts to avoid data loss.
Only the following properties may be modified:
o *mailboxIds*: The server MUST reject any attempt to add a message
with "isDraft == false" to the outbox. The server MAY reject
attempts to add a draft message to a mailbox that does not have a
role of "drafts", "outbox" or "templates".
o *isFlagged*
o *isUnread*
o *isAnswered*
Note, a mailbox id may be a _creation id_ (see "setFoos" for a
description of how this works).
If any of the properties in the update are invalid (immutable and
different to the current server value, wrong type, invalid value for
the property - like a mailbox id for non-existent mailbox), the
server MUST reject the update with an "invalidProperties" error. The
Error object SHOULD contain a property called _properties_ of type
"String[]" that lists *all* the properties that were invalid. The
object MAY also contain a _description_ property of type "String"
with a user-friendly description of the problems.
If the _id_ given does not correspond to a Message in the given
account, reject the update with a "notFound" error.
To *delete a message* to trash, simply change the "mailboxIds"
property so it is now in the mailbox with "role == "trash"". If the
mailbox has the property "mustBeOnlyMailbox == true", it must be
removed from all other mailboxes. Otherwise, leave it in those
Jenkins Expires April 22, 2017 [Page 43]
Internet-Draft JMAP Mail October 2016
mailboxes so that it will be restored to its previous state if
undeleted.
5.3.3. Sending messages
To send a message, either create a new message directly into the
mailbox with "role == "outbox"" or move an existing draft into this
mailbox. At this point the server will check that it has everything
it needs for a valid message. In particular, that it has a valid
"From" address (and the user has permission to use this From
address), it has at least one address to send to, and all addresses
in To/Cc/Bcc are valid email addresses. If it cannot send, it will
reject the creation/update with an "invalidProperties" error. The
Error object SHOULD contain a property called _properties_ of type
"String[]" that lists *all* the properties that were invalid. The
object SHOULD also contain a _description_ property of type "String"
with a user-friendly description of the problems to present to the
user.
If the message is accepted, the server SHOULD *asynchronously*
schedule the message to be sent *after* this method call is complete
(note, this MAY occur before the next method in the same API request
or after the whole API request is complete). This means that the
"newState" string in the response represents a state where the
message is still in the outbox.
When the message is sent, the server MUST delete the message from the
*outbox* and SHOULD create a *new* copy of the sent message (with a
new id) in the *sent* mailbox, unless the user has indicated another
preference. If "inReplyToMessageId" was set, the server SHOULD mark
this message as "isAnswered: true" at this point, if found. The
server is responsible for either reporting an error (normally a
"bounce" email), or ensuring delivery of the message to the next hop.
5.3.4. Cancelling a send
A message may be moved out of the *outbox* and back to the *drafts*
mailbox using the standard update message mechanism, if it has not
yet been sent at the time the method is called. This MUST cancel the
queued send. If the message has already been sent then it will have
been deleted from the outbox, so the update will fail with a standard
"notFound" error.
5.3.5. Destroying messages
If the _id_ given does not correspond to a Message in the given
account, the server MUST reject the destruction with a "notFound"
error.
Jenkins Expires April 22, 2017 [Page 44]
Internet-Draft JMAP Mail October 2016
Destroying a message removes it from all mailboxes to which it
belonged.
5.3.6. Response
The response to _setMessages_ is called _messagesSet_. It has the
following arguments:
o *accountId*: "String" The id of the account used for the call.
o *oldState*: "String|null" The state string that would have been
returned by _getMessages_ before making the requested changes, or
"null" if the server doesn't know what the previous state string
was.
o *newState*: "String" The state string that will now be returned by
_getMessages_.
o *created*: "String[Message]" A map of the creation id to an object
containing the _id_, _blobId_, _threadId_, and _size_ properties
for each successfully created Message.
o *updated*: "String[]" A list of Message ids for Messages that were
successfully updated.
o *destroyed*: "String[]" A list of Message ids for Messages that
were successfully destroyed.
o *notCreated*: "String[SetError]" A map of creation id to a
SetError object for each Message that failed to be created. The
possible errors are defined above.
o *notUpdated*: "String[SetError]" A map of Message id to a SetError
object for each Message that failed to be updated. The possible
errors are defined above.
o *notDestroyed*: "String[SetError]" A map of Message id to a
SetError object for each Message that failed to be destroyed. The
possible errors are defined above.
The following errors may be returned instead of the _messagesSet_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
Jenkins Expires April 22, 2017 [Page 45]
Internet-Draft JMAP Mail October 2016
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"accountReadOnly": Returned if the account has "isReadOnly == true".
"invalidArguments": Returned if one of the arguments is of the wrong
type, or otherwise invalid. A _description_ property MAY be present
on the response object to help debug with an explanation of what the
problem was.
"stateMismatch": Returned if an _ifInState_ argument was supplied and
it does not match the current state.
5.4. importMessages
The _importMessages_ method adds [RFC5322] messages to a user's set
of messages. The messages must first be uploaded as a file using the
standard upload mechanism. It takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If "null", defaults to the primary account.
o *messages*: "String[MessageImport]" A map of creation id (client
specified) to MessageImport objects
An *MessageImport* object has the following properties:
o *blobId*: "String" The id representing the raw [RFC5322] message
(see the file upload section).
o *mailboxIds* "String[]" The ids of the mailbox(es) to assign this
message to.
o *isUnread*: "Boolean"
o *isFlagged*: "Boolean"
o *isAnswered*: "Boolean"
o *isDraft*: "Boolean"
If "isDraft == true", the mailboxes MUST include the drafts or outbox
mailbox. Adding to the outbox will send the message, as described in
the _setMessages_ section (it will NOT automatically mark any other
message as _isAnswered_).
Jenkins Expires April 22, 2017 [Page 46]
Internet-Draft JMAP Mail October 2016
The response to _importMessages_ is called _messagesImported_. It has
the following arguments:
o *accountId*: "String" The id of the account used for this call.
o *created*: "String[Message]" A map of the creation id to an object
containing the _id_, _blobId_, _threadId_ and _size_ properties
for each successfully imported Message.
o *notCreated*: "String[SetError]" A map of creation id to a
SetError object for each Message that failed to be created. The
possible errors are defined above.
The following errors may be returned instead of the _messageImported_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"accountReadOnly": Returned if the account has "isReadOnly == true".
"invalidArguments": Returned if one of the arguments is of the wrong
type, or otherwise invalid. A "description" property MAY be present
on the response object to help debug with an explanation of what the
problem was.
"notFound": Returned if the URL given in the "file" argument does not
correspond to an internal file.
"invalidMailboxes": Returned if one of the mailbox ids cannot be
found, or an invalid combination of mailbox ids is specified.
"maxQuotaReached": Returned if the user has reached their mail quota
so the message cannot be imported.
5.5. copyMessages
The only way to move messages *between* two different accounts is to
copy them using the _copyMessages_ method, then once the copy has
succeeded, delete the original. It takes the following arguments:
o *fromAccountId*: "String|null" The id of the account to copy
messages from. If "null", defaults to the primary account.
Jenkins Expires April 22, 2017 [Page 47]
Internet-Draft JMAP Mail October 2016
o *toAccountId*: "String|null" The id of the account to copy
messages to. If "null", defaults to the primary account.
o *messages*: "String[MessageCopy]" A map of _creation id_ to a
MessageCopy object.
A *MessageCopy* object has the following properties:
o *messageId*: "String" The id of the message to be copied in the
"from" account.
o *mailboxIds*: "String[]" The ids of the mailboxes (in the "to"
account) to add the copied message to.
o *isUnread*: "Boolean" The _isUnread_ property for the copy.
o *isFlagged*: "Boolean" The _isFlagged_ property for the copy.
o *isAnswered*: "Boolean" The _isAnswered_ property for the copy.
o *isDraft*: "Boolean" The _isDraft_ property for the copy.
The "from" account may be the same as the "to" account to copy
messages within an account.
The response to _copyMessages_ is called _messagesCopied_. It has the
following arguments:
o *fromAccountId*: "String" The id of the account messages were
copied from.
o *toAccountId*: "String" The id of the account messages were copied
to.
o *created*: "String[Message]|null" A map of the creation id to an
object containing the _id_, _blobId_, _threadId_ and _size_
properties for each successfully copied Message.
o *notCreated*: "String[SetError]|null" A map of creation id to a
SetError object for each Message that failed to be copied, "null"
if none.
The *SetError* may be one of the following types:
"notFound": Returned if the messageId given can't be found.
"invalidMailboxes": Returned if one of the mailbox ids cannot be
found, or an invalid combination of mailbox ids is specified.
Jenkins Expires April 22, 2017 [Page 48]
Internet-Draft JMAP Mail October 2016
"maxQuotaReached": Returned if the user has reached their mail quota
so the message cannot be copied.
The following errors may be returned instead of the _messagesCopied_
response:
"fromAccountNotFound": Returned if a _fromAccountId_ was explicitly
included with the request, but it does not correspond to a valid
account.
"toAccountNotFound": Returned if a _toAccountId_ was explicitly
included with the request, but it does not correspond to a valid
account.
"fromAccountNoMail": Returned if the _fromAccountId_ given
corresponds to a valid account, but does not contain any mail data.
"toAccountNoMail": Returned if the _toAccountId_ given corresponds to
a valid account, but does not contain any mail data.
"accountReadOnly": Returned if the "to" account has "isReadOnly ==
true".
"invalidArguments": Returned if one of the arguments is of the wrong
type, or otherwise invalid. A "description" property MAY be present
on the response object to help debug with an explanation of what the
problem was.
5.6. reportMessages
Messages can be reported as spam or non-spam to help train the user's
spam filter. This MUST NOT affect the state of the Message objects
(it DOES NOT move a message into or out of the Spam mailbox).
To report messages, make a call to _reportMessages_. It takes the
following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If not given, defaults to the primary account.
o *messageIds*: "String[]" The list of ids of messages to report.
o *asSpam*: "Boolean" If "true", learn these messages as spam. If
"false", learn as non-spam.
The response to _reportMessages_ is called _messagesReported_. It has
the following arguments:
Jenkins Expires April 22, 2017 [Page 49]
Internet-Draft JMAP Mail October 2016
o *accountId*: "String" The id of the account used for this call.
o *asSpam*: "Boolean" Echoed back from the call
o *reported*: "String[]" The ids of each message successfully
reported.
o *notFound*: "String[]|null" An array of message ids requested
which could not be found, or "null" if all ids were found.
The following errors may be returned instead of the
_messagesReported_ response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"accountReadOnly": Returned if the account has "isReadOnly == true".
"requestTooLarge": Returned if the total number of objects to create,
update or destroy exceeds the maximum number the server is willing to
process in a single method call.
"invalidArguments": Returned if one of the arguments is of the wrong
type, or otherwise invalid. A "description" property MAY be present
on the response object to help debug with an explanation of what the
problem was.
6. Identities
A *Identity* object stores information about an email address (or
domain) the user may send from. It has the following properties:
o *id*: "String" The id of the identity. This property is
immutable.
o *name*: "String" The "From" _name_ the client SHOULD use when
creating a new message from this identity.
o *email*: "String" The "From" email address the client MUST use
when creating a new message from this identity. This property is
immutable. The "email" property MAY alternatively be of the form
"*@example.com", in which case the client may use any valid email
address ending in "@example.com".
Jenkins Expires April 22, 2017 [Page 50]
Internet-Draft JMAP Mail October 2016
o *replyTo*: "String" The Reply-To value the client SHOULD set when
creating a new message from this identity.
o *bcc*: "String" The Bcc value the client SHOULD set when creating
a new message from this identity.
o *textSignature*: "String" Signature the client SHOULD insert into
new rich-text messages that will be sending from this identity.
Clients MAY ignore this and/or combine this with a client-specific
signature preference.
o *htmlSignature*: "String" Signature the client SHOULD insert into
new HTML messages that will be sending from this identity. This
text MUST be an HTML snippet to be inserted into the
"<body></body>" section of the new email. Clients MAY ignore this
and/or combine this with a client-specific signature preference.
o *mayDeleteIdentity*: "Boolean" Is the user allowed to delete this
identity? Servers may wish to set this to false for the user's
username or other default address.
Multiple identities with the same email address MAY exist, to allow
for different settings the user wants to pick between (for example
with different names/signatures).
6.1. getIdentities
Identities can either be fetched explicitly by id, or all of them at
once. To fetch identities, make a call to "getIdentities". It takes
the following arguments:
o *accountId*: "String|null" The Account to fetch the identities
for. If "null", the primary account is used.
o *ids*: "String[]|null" The ids of the identities to fetch. If
"null", all identities in the account are be fetched.
The response to _getIdentities_ is called _identities_. It has the
following arguments:
o *accountId*: "String" The id of the account used for the call.
o *state*: "String" A string encoding the current state on the
server. This string will change if any identities change (that
is, a new identity is created, a change is made to an existing
identity, or an identity is deleted). It can be passed to
_getIdentityUpdates_ to efficiently get the list of changes from
the previous state.
Jenkins Expires April 22, 2017 [Page 51]
Internet-Draft JMAP Mail October 2016
o *list*: "Identity[]" An array of the Identity objects requested.
This will be the *empty array* if the _ids_ argument was the empty
array, or contained only ids for identities that could not be
found.
o *notFound*: "String[]|null" This array contains the ids passed to
the method for identities that do not exist, or "null" if all
requested ids were found. It MUST be "null" if the _ids_ argument
in the call was "null".
The following errors may be returned instead of the _identities_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"invalidArguments": Returned if one of the arguments is of the wrong
type, or otherwise invalid. A "description" property MAY be present
on the response object to help debug with an explanation of what the
problem was.
6.2. getIdentityUpdates
The _getIdentityUpdates_ call allows a client to efficiently update
the state of its cached identities to match the new state on the
server. It takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If "null", the primary account will be used.
o *sinceState*: "String" The current state of the client. This is
the string that was returned as the _state_ argument in the
_identities_ response. The server will return the changes made
since this state.
o *maxChanges*: "Number|null" The maximum number of Identity ids to
return in the response. The server MAY choose to clamp this value
to a particular maximum or set a maximum if none is given by the
client. If supplied by the client, the value MUST be a positive
integer greater than 0. If a value outside of this range is
given, the server MUST reject the call with an "invalidArguments"
error.
Jenkins Expires April 22, 2017 [Page 52]
Internet-Draft JMAP Mail October 2016
o *fetchRecords*: "Boolean|null" If "true", immediately after
outputting an _identityUpdates_ response, an implicit call will be
made to _getidentities_ with the _changed_ property of the
response as the _ids_ argument, and the _fetchRecordProperties_
argument as the _properties_ argument. If "false" or "null", no
implicit call is made.
The response to _getIdentityUpdates_ is called _identityUpdates_. It
has the following arguments:
o *accountId*: "String" The id of the account used for the call.
o *oldState*: "String" This is the _sinceState_ argument echoed
back; the state from which the server is returning changes.
o *newState*: "String" This is the state the client will be in after
applying the set of changes to the old state.
o *hasMoreUpdates*: "Boolean" If "true", the client may call
_getIdentityUpdates_ again with the _newState_ returned to get
further updates. If "false", _newState_ is the current server
state.
o *changed*: "String[]" An array of Identity ids where a property of
the identity has changed between the old state and the new state,
or the identity has been created, and the identity has not been
destroyed.
o *removed*: "String[]" An array of Identity ids for identities
which have been destroyed since the old state.
If a _maxChanges_ is supplied, or set automatically by the server,
the server must try to limit the number of ids across _changed_ and
_removed_ to the number given. If there are more changes than this
between the client's state and the current server state, the update
returned MUST take the client to an intermediate state, from which
the client can continue to call _getIdentityUpdates_ until it is
fully up to date. The server MAY return more ids than the
_maxChanges_ total if this is required for it to be able to produce
an update to an intermediate state, but it SHOULD try to keep it
close to the maximum requested.
If an identity has been modified AND deleted since the oldState, the
server should just return the id in the _removed_ array, but MAY
return it in the _changed_ array as well. If an identity has been
created AND deleted since the oldState, the server SHOULD remove the
identity id from the response entirely, but MAY include it in the
_removed_ array.
Jenkins Expires April 22, 2017 [Page 53]
Internet-Draft JMAP Mail October 2016
The following errors may be returned instead of the "identityUpdates"
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"invalidArguments": 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 "description" property MAY be present on the
response object to help debug with an explanation of what the problem
was.
"cannotCalculateChanges": 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, or the server being unable to
produce an update to an intermediate state when there are too many
updates. The client MUST invalidate its Identity cache.
6.3. setIdentities
Modifying the state of Identity objects on the server is done via the
_setIdentities_ method. This encompasses creating, updating and
destroying Identity records.
The _setIdentities_ method takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If "null", the primary account will be used.
o *ifInState*: "String|null" This is a state string as returned by
the _getIdentities_ method. If supplied, the string must match
the current state, otherwise the method MUST be aborted and a
"stateMismatch" error returned. If "null", any changes will be
applied to the current state.
o *create*: "String[Identity]|null" A map of _creation id_ (an
arbitrary string set by the client) to Identity objects
(containing all properties except the id).
o *update*: "String[Identity]|null" A map of id to Identity objects.
The object may omit any property; only properties that have
changed need be included.
Jenkins Expires April 22, 2017 [Page 54]
Internet-Draft JMAP Mail October 2016
o *destroy*: "String[]|null" A list of ids for Identity objects to
permanently delete.
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 identity.
If a create, update or destroy is rejected, the appropriate error
MUST 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.
A *create* MAY be rejected with one of the following errors:
o "maxQuotaReached": Returned if the user has reached a server-
defined limit on the number of identities.
o "emailNotPermitted": Returned if the user tries to create an
identity with an email address the user does not allow them to
send from.
If the identity has "mayDeleteIdentity == false", any attempt to
destroy it MUST be rejected with a "forbidden" error.
If an id given cannot be found, the update or destroy MUST be
rejected with a "notFound" set error.
The response to _setIdentities_ is called _identitiesSet_. It has the
following arguments:
o *accountId*: "String" The id of the account used for the call.
o *oldState*: "String|null" The state string that would have been
returned by _getIdentities_ before making the requested changes,
or "null" if the server doesn't know what the previous state
string was.
o *newState*: "String" The state string that will now be returned by
_getIdentities_.
o *created*: "String[Identity]" A map of the creation id to an
object containing the *id* property for all successfully created
identities.
o *updated*: "String[]" A list of ids for identities that were
successfully updated.
Jenkins Expires April 22, 2017 [Page 55]
Internet-Draft JMAP Mail October 2016
o *destroyed*: "String[]" A list of ids for identities that were
successfully destroyed.
o *notCreated*: "String[SetError]" A map of creation id to a
SetError object for each identity that failed to be created. The
possible errors are defined in the description of the method for
specific data types.
o *notUpdated*: "String[SetError]" A map of Identity id to a
SetError object for each identity that failed to be updated. The
possible errors are defined in the description of the method for
specific data types.
o *notDestroyed*: "String[SetError]" A map of Identity id to a
SetError object for each identity that failed to be destroyed.
The possible errors are defined in the description of the method
for specific data types.
A *SetError* object has the following properties:
o *type*: "String" The type of error.
o *description*: "String|null" A description of the error to display
to the user.
The following errors may be returned instead of the _identitiesSet_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"accountReadOnly": Returned if the account has MailCapabilities with
"isReadOnly == true".
"requestTooLarge": Returned if the total number of objects to create,
update or destroy exceeds the maximum number the server is willing to
process in a single method call.
"invalidArguments": Returned if one of the arguments is of the wrong
type, or otherwise invalid. A _description_ property MAY be present
on the response object to help debug with an explanation of what the
problem was.
Jenkins Expires April 22, 2017 [Page 56]
Internet-Draft JMAP Mail October 2016
"stateMismatch": Returned if an _ifInState_ argument was supplied and
it does not match the current state.
7. SearchSnippets
When doing a search on a "String" property, the client may wish to
show the relevant section of the body that matches the search as a
preview instead of the beginning of the message, and to highlight any
matching terms in both this and the subject of the message. Search
snippets represent this data.
A *SearchSnippet* object has the following properties:
o *messageId*: "String" The message id the snippet applies to.
o *subject*: "String|null" If text from the filter matches the
subject, this is the subject of the message HTML-escaped, with
matching words/phrases wrapped in "<mark></mark>" tags. If it
does not match, this is "null".
o *preview*: "String|null" If text from the filter matches the
plain-text or HTML body, this is the relevant section of the body
(converted to plain text if originally HTML), HTML-escaped, with
matching words/phrases wrapped in "<mark></mark>" tags, up to 256
characters long. If it does not match, this is "null".
It is server-defined what is a relevant section of the body for
preview. If the server is unable to determine search snippets, it
MUST return "null" for both the _subject_ and _preview_ properties.
Note, unlike most data types, a SearchSnippet DOES NOT have a
property called "id".
7.1. getSearchSnippets
To fetch search snippets, make a call to "getSearchSnippets". It
takes the following arguments:
o *accountId*: "String|null" The id of the account to use for this
call. If "null", defaults to the primary account.
o *messageIds*: "String[]" The list of ids of messages to fetch the
snippets for.
o *filter*: "FilterCondition|FilterOperator|null" The same filter as
passed to getMessageList; see the description of this method for
details.
Jenkins Expires April 22, 2017 [Page 57]
Internet-Draft JMAP Mail October 2016
The response to "getSearchSnippets" is called "searchSnippets". It
has the following arguments:
o *accountId*: "String" The id of the account used for the call.
o *filter*: "FilterCondition|FilterOperator|null" Echoed back from
the call.
o *list*: "SearchSnippet[]" An array of SearchSnippets objects for
the requested message ids. This may not be in the same order as
the ids that were in the request.
o *notFound*: "String[]|null" An array of message ids requested
which could not be found, or "null" if all ids were found.
Since snippets are only based on immutable properties, there is no
state string or update mechanism needed.
The following errors may be returned instead of the _searchSnippets_
response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"requestTooLarge": Returned if the number of _messageIds_ requested
by the client exceeds the maximum number the server is willing to
process in a single method call.
"cannotDoFilter": Returned if the server is unable to process the
given _filter_ for any reason.
"invalidArguments": 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 "description" property MAY be present on the
response object to help debug with an explanation of what the problem
was.
8. Vacation Response
The *VacationResponse* object represents the state of vacation-
response related settings for an account. It has the following
properties:
Jenkins Expires April 22, 2017 [Page 58]
Internet-Draft JMAP Mail October 2016
o *id*: "String" The id of the object. This property is immutable.
There is only ever one vacation response object, and its id is
""singleton"".
o *isEnabled* "Boolean" Should a vacation response be sent if a
message arrives between the _fromDate_ and _toDate_?
o *fromDate*: "Date|null" If _isEnabled_ is "true", the date/time
after which messages that arrive should receive the user's
vacation response, in UTC. If "null", the vacation response is
effective immediately.
o *toDate*: "Date|null" If _isEnabled_ is "true", the date/time
after which messages that arrive should no longer receive the
user's vacation response, in UTC. If "null", the vacation
response is effective indefinitely.
o *subject*: "String|null" The subject that will be used by the mail
sent in response to messages when the vacation response is
enabled. If null, an appropriate subject SHOULD be set by the
server.
o *textBody*: "String|null" The plain text part of the message to
send in response to messages when the vacation response is
enabled. If this is "null", when the vacation message is sent a
plain-text body part SHOULD be generated from the _htmlBody_ but
the server MAY choose to send the response as HTML only.
o *htmlBody*: "String|null" The HTML message to send in response to
messages when the vacation response is enabled. If this is
"null", when the vacation message is sent an HTML body part MAY be
generated from the _textBody_, or the server MAY choose to send
the response as plain-text only.
8.1. getVacationResponse
There MUST only be exactly one VacationResponse object in an account.
It MUST have the id ""singleton"".
To fetch the vacation response object, make a call to
"getVacationResponse". It takes the following argument:
o *accountId*: "String|null" The Account to get the vacation
response for. If "null", the primary account is used.
The response to _getVacationResponse_ is called _vacationResponse_.
It has the following arguments:
Jenkins Expires April 22, 2017 [Page 59]
Internet-Draft JMAP Mail October 2016
o *accountId*: "String" The id of the account used for the call.
o *list*: "VacationResponse[]" An array containing the single
VacationResponse object.
The following errors may be returned instead of the
_vacationResponse_ response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
8.2. setVacationResponse
Sets properties on the vacation response object. It takes the
following arguments:
o *accountId*: "String|null" The Account to set the vacation
response for. If "null", the primary account is used.
o *update*: "String[VacationResponse]|null" A map of id
("singleton") to the VacationResponse object with new values for
the properties you wish to change. The object may omit any
property; only properties that have changed need be included.
If any of the properties in the update are invalid (immutable and
different to the current server value, wrong type), the server MUST
reject the update with a SetError of type "invalidProperties". The
SetError object SHOULD contain a property called _properties_ of type
"String[]" that lists *all* the properties that were invalid. The
object MAY also contain a _description_ property of type "String"
with a user-friendly description of the problems.
The response is called _vacationResponseSet_. It has the following
arguments:
o *updated*: "String[]" Contains the single id ("singleton") if the
vacation response was successfully updated.
o *notUpdated*: "String[SetError]" A map of id ("singleton") to a
SetError object if the update failed.
A *SetError* object has the following properties:
o *type*: "String" The type of error.
Jenkins Expires April 22, 2017 [Page 60]
Internet-Draft JMAP Mail October 2016
o *description*: "String|null" A description of the error to display
to the user.
The following errors may be returned instead of the
_vacationResponseSet_ response:
"accountNotFound": Returned if an _accountId_ was explicitly included
with the request, but it does not correspond to a valid account.
"accountNotSupportedByMethod": Returned if the _accountId_ given
corresponds to a valid account, but the account does not support this
data type.
"invalidArguments": Returned if one of the arguments is of the wrong
type, or otherwise invalid (including using an id other than
""singleton""). A "description" property MAY be present on the
response object to help debug with an explanation of what the problem
was.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008,
<http://www.rfc-editor.org/info/rfc5322>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <http://www.rfc-editor.org/info/rfc7159>.
9.2. URIs
[1] server.html
[2] https://tools.ietf.org/html/rfc4648
[3] http://tools.ietf.org/html/rfc2047
Jenkins Expires April 22, 2017 [Page 61]
Internet-Draft JMAP Mail October 2016
Author's Address
Neil Jenkins
FastMail
Level 1, 91 William St
Melbourne VIC 3000
Australia
Email: neilj@fastmail.com
URI: https://www.fastmail.com
Jenkins Expires April 22, 2017 [Page 62]
