JMAP for Mail

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.

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 . 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 . 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: Boolean|String – The value is either a JSON Boolean value, or a JSON String value. 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. Foo[] – An array of objects of type Foo. String[Foo] – A JSON Object being used as a map (associative array), where all the values are of type Foo.

The same terminology is used in this document as in the core JMAP specification.

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: 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). canDelaySend: Boolean Does the server support inserting a message into the outbox to be sent later at a user-specified time? 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.

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 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: id: String The id of the mailbox. This property is immutable. 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 maximum 256 bytes in size. Servers SHOULD forbid sibling Mailboxes with the same name. 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. 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 cannot 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. 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. 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. 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. mayAddItems: Boolean The user may add messages to this mailbox (by either creating a new message or moving an existing one). mayRemoveItems: Boolean The user may remove messages from this mailbox (by either changing the mailboxes of a message or deleting it). mayCreateChild: Boolean The user may create a mailbox with this mailbox as its parent. mayRename: Boolean The user may rename the mailbox or make it a child of another mailbox. mayDelete: Boolean The user may delete the mailbox itself. totalMessages: Number The number of messages in this mailbox. unreadMessages: Number The number of messages in this mailbox that have neither the $Seen keyword nor the $Draft keyword. totalThreads: Number The number of threads where at least one message in the thread is in this mailbox. unreadThreads: Number The number of threads where at least one message in the thread has neither the $Seen keyword nor the $Draft keyword AND at least one message in the thread is in this mailbox (but see below for special case handling of Trash). Note, the unread message does not need to be the one in this mailbox. The Trash mailbox (that is a mailbox with role == "trash") MUST be treated specially for the purpose of unread counts: Messages that are only in the Trash (and no other mailbox) are ignored when calculating the unreadThreads count of other mailboxes. Messages that are not in the Trash are ignored when calculating the unreadThreads 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 unread 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. So 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. For IMAP compatibility, a message in both the Trash and another mailbox SHOULD be treated by the client as existing in both places (i.e. when emptying the trash, the client SHOULD just remove the Trash mailbox and leave it in the other mailbox).

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: accountId: String|null The Account to fetch the mailboxes for. If null, the primary account is used. ids: String[]|null The ids of the mailboxes to fetch. If null, all mailboxes in the account are returned. 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. The response to getMailboxes is called mailboxes. It has the following arguments: accountId: String The id of the account used for the call. 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. 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. 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.

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: accountId: String|null The id of the account to use for this call. If null, the primary account will be used. 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. 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. 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: accountId: String The id of the account used for the call. oldState: String This is the sinceState argument echoed back; the state from which the server is returning changes. newState: String This is the state the client will be in after applying the set of changes to the old state. 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. removed: String[] An array of Mailbox ids for mailboxes which have been destroyed since the old state. 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 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.

Mailboxes can be created, updated and destroyed using the setMailboxes method. The method takes the following arguments: accountId: String|null The id of the account to use for this call. If null, defaults to the primary account. 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. 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. 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. 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.

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.

The properties of the Mailbox object submitted for creation MUST conform to the following conditions: The id property MUST NOT be present. The parentId property MUST be either null or be a valid id for a mailbox for which the mayCreateChild property is true. The role property MUST be either null, a valid role as listed in the Mailbox object specification, or prefixed by "x-". The mustBeOnlyMailbox property MUST NOT be present. This is server dependent and will be set by the server. 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). 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.

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: The name property MUST be a valid UTF-8 string of at least 1 character in length and maximum 256 bytes in size. 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. These properties are immutable or may only be set by the server: id role 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.

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 MUST NOT be destroyed if it still has any child mailboxes. Attempts to do so MUST be rejected with a mailboxHasChild error. A mailbox MUST NOT be destroyed if it has any messages assigned to it. Attempts to do so MUST be rejected with a mailboxHasMessage error.

The response to setMailboxes is called mailboxesSet. It has the following arguments: accountId: String The id of the account used for the call. 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. newState: String The state string that will now be returned by getMailboxes. 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. updated: String[Mailbox|null] The keys in this map are the ids of all mailboxes that were successfully updated. If the server made any other changes to the record beyond those explicitly requested by the client, the value for the corresponding id in the map is an object containing the updated value of each property the server changed. Otherwise (if no properties changed on the server other than those explicitly updated by the client), the value is null. destroyed: String[] A list of ids for Mailboxes that were successfully destroyed. 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. 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. 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: 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" ]

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 state. If the server doesn't support this, the client still only needs to fetch the message list again, not the messages themselves.

To fetch a message list, make a call to getMessageList. It takes the following arguments: accountId: String|null The id of the account to use for this call. If null, the primary account will be used. filter: FilterCondition|FilterOperator|null Determines the set of messages returned in the results. See the "Filtering" section below for allowed values and semantics. sort: String[]|null A list of Message property names to sort by. See the "Sorting" section below for allowed values and semantics. 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. 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. 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). 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). 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 reached the end of the list. If a negative value is given, the call MUST be rejected with an invalidArguments error. 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. 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. fetchMessageProperties: String[]|null The list of properties to fetch on any fetched messages. See getMessages for a full description. 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.

A FilterOperator object has the following properties: 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. conditions: (FilterCondition|FilterOperator)[] The conditions to evaluate against each message. A FilterCondition object has the following properties: inMailbox: String|null A mailbox id. A message must be in this mailbox to match the condition. inMailboxOtherThan: String|null A mailbox id. A message be in any mailbox other than this one to match the condition. This is to allow messages solely in trash/spam to be easily excluded from a search. before: Date|null The date of the message (as returned on the Message object) must be before this date to match the condition. 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. 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. 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. allInThreadHaveKeyword: String All messages (including this one) in the same thread as this message must have the given keyword to match the condition. someInThreadHaveKeyword: String At least one message (possibly this one) in the same thread as this message must have the given keyword to match the condition. noneInThreadHaveKeyword: String All messages (including this one) in the same thread as this message must not have the given keyword to match the condition. hasKeyword: String This message must have the given keyword to match the condition. notKeyword: String This message must not have the given keyword to match the condition. hasAttachment: Boolean|null The hasAttachment property of the message must be identical to the value given to match the condition. text: String|null Looks for the text in the from, to, cc, bcc, subject, textBody or htmlBody properties of the message. from: String|null Looks for the text in the from property of the message. to: String|null Looks for the text in the to property of the message. cc: String|null Looks for the text in the cc property of the message. bcc: String|null Looks for the text in the bcc property of the message. subject: String|null Looks for the text in the subject property of the message. body: String|null Looks for the text in the textBody or htmlBody property of the message. 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: Text SHOULD be matched in a case-insensitive manner. 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 word or sequence of words, excluding the surrounding quotation marks. Use \", \' and \\ to match a literal ", ' and \ respectively in a phrase. 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. 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"). When searching inside the htmlBody property, HTML tags and attributes SHOULD be ignored.

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: id - The id as returned in the Message object. date - The date as returned in the Message object. The following properties SHOULD be supported for sorting: size - The size as returned in the Message object. 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. 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. subject - This is taken to be the subject of the Message with any ignoring any leading "Fwd:"s or "Re:"s (case-insensitive match). keyword:$keyword - This value MUST be considered true if the message has the keyword, or false otherwise. allThreadKeyword:$keyword - This value MUST be considered true for the message if all of the messages in the same thread (regardless of mailbox) have the keyword. someThreadKeyword:$keyword - This value MUST be considered true for the message if any of the messages in the same thread (regardless of mailbox) have the keyword. 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: 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. Date: If sorting in ascending order, the earlier date MUST come first. Boolean: If sorting in ascending order, a false value MUST come before a true value. Example sort:

`[ "someThreadKeyword:$Flagged desc", "date desc" ] This would sort messages in flagged threads first (the thread is considered flagged if any message within it is flagged), and then in date order, newest first. If two messages have both identical flagged status and date, the order is server-dependent but must be stable.

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.

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.

The response to a call to getMessageList is called messageList. It has the following arguments: accountId: String The id of the account used for the call. filter: FilterCondition|FilterOperator|null The filter of the message list. Echoed back from the call. sort: String[]|null A list of Message property names used to sort by. Echoed back from the call. collapseThreads: Boolean|null Echoed back from the call. 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, if the server supports it, call getMessageListUpdates to get the delta difference. 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. position: Number The 0-based index of the first result in the threadIds array within the complete list. total: Number The total number of messages in the message list (given the filter and collapseThreads arguments). 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. 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 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.

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: accountId: String|null The id of the account to use for this call. If null, the primary account will be used. filter: FilterCondition|FilterOperator|null The filter argument that was used with getMessageList. sort: String[]|null The sort argument that was used with getMessageList. collapseThreads: Boolean|null The collapseThreads argument that was used with getMessageList. 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. 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. 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: accountId: String The id of the account used for the call. filter: FilterCondition|FilterOperator|null The filter of the message list. Echoed back from the call. sort: String[]|null A list of Message property names used to sort by. Echoed back from the call. collapseThreads: Boolean|null Echoed back from the call. oldState: String This is the sinceState argument echoed back; the state from which the server is returning changes. newState: String This is the state the client will be in after applying the set of changes to the old state. uptoMessageId: String|null Echoed back from the call. total: Number The total number of messages in the message list (given the filter and collapseThreads arguments). 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 a keyword, the server MUST include all messages in the current list for which this keyword MAY have changed. If the sort includes a "some/all-in-thread-keyword", then the server MUST include all messages in the current list for which this keyword MAY have changed on any of the messages in the thread. 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: messageId: String threadId: String An AddedItem object has the following properties: messageId: String threadId: String 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.

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. 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: id: String The id of the thread. This property is immutable. messageIds: String[] The ids of the messages in the thread, sorted such that: Any message with the $Draft keyword that has an In-Reply-To header is sorted after the first non-draft message in the thread with the corresponding Message-Id header, but before any subsequent non-draft messages. Other than that, everything is sorted in date order (as determined by the date property on the Message object), oldest first. If two messages are identical under the above two conditions, the sort is server-dependent but MUST be stable (sorting by id is recommended).

Threads can only be fetched explicitly by id. To fetch threads, make a call to getThreads. It takes the following arguments: accountId: String|null The id of the account to use for this call. If not given, defaults to the primary account. ids: String[] An array of ids for the threads to fetch. 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 ids argument, and the fetchMessageProperties argument as the properties argument. If false or null, no implicit call will be made. 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: accountId: String The id of the account used for the call. 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. 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. 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:

[ "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" ]

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: accountId: String|null The id of the account to use for this call. If not given, defaults to the primary account. 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. 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 integer greater than 0. If a value outside of this range is given, the server MUST reject the call with an invalidArguments error. 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: accountId: String The id of the account used for the call. oldState: String This is the sinceState argument echoed back; the state from which the server is returning changes. newState: String This is the state the client will be in after applying the set of changes to the old state. 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. 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. 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 calculate 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 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.

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 textual body parts, such as base64, or RFC 2047 encoding of non-ASCII characters, MUST be fully decoded into UTF-8. A Message object has the following properties: id: String The id of the message. blobId: String The id representing the raw message. This may be used to download the original message or to attach it directly to another message etc. threadId: String The id of the thread to which this message belongs. 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). keywords: String[Boolean] (Mutable) A set of keywords that apply to the message. The set is represented as an object, with the keys being the keywords. The value for each key in the object MUST be true. Keywords are shared with IMAP. The six system keywords from IMAP are treated specially. The following four keywords have their first character changed from \ in IMAP to $ in JMAP and have particular semantic meaning: $Draft: The message is a draft the user is composing. $Seen: The message has been read. $Flagged: The message has been flagged for urgent/special attention. $Answered: The message has been replied to. The IMAP \Recent keyword is not exposed via JMAP. The IMAP \Deleted keyword is also not present: IMAP uses a delete+expunge model, which JMAP does not. Any message with the \Deleted keyword MUST NOT be visible via JMAP. Users may add arbitrary keywords to a message. For compatibility with IMAP, a keyword is a (case-sensitive) string of 1–255 characters in the ASCII subset %x21–%x127 (excludes control chars and space), and MUST NOT include any of these characters: ()]{%*"\ The IANA Keyword Registry as established in assigns semantic meaning to some other keywords in common use. New keywords may be established here in the future. In particular, note: $Forwarded: The message has been forwarded. $Phishing: The message is highly likely to be phishing. Clients SHOULD warn users to take care when viewing this message and disable links and attachments. $Junk: The message is definitely spam. Clients SHOULD set this flag when users report spam to help train automated spam-detection systems. $NotJunk: The message is definitely not spam. Clients SHOULD set this flag when users indicate a message is legitimate, to help train automated spam-detection systems. hasAttachment: Boolean Does the message have any attachments? 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. 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. 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. 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. 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. 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. 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. subject: String The subject of the message. date: Date The date the message was sent (or saved, if the message is a draft). size: Number The size in bytes of the whole message as counted by the server towards the user's quota. 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. 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. If there is neither a text/plain nor a text/html body part, this MUST be the empty string. htmlBody: String|null The HTML body part for the message if present. attachments: Attachment[]|null An array of attachment objects (see below) detailing all the attachments to the message. attachedMessages: String[Message]|null An object mapping attachment id (as found in the attachments property) to a Message object with the following properties, for each message attached to this one: headers from to cc bcc replyTo subject date textBody htmlBody attachments attachedMessages An Emailer object has the following properties: name: String The name of the sender/recipient. If a name cannot be extracted for an email, this property SHOULD be the empty string. 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:

[ {name:"Joe Bloggs", email:"joeb@example.com"}, {name:"", email:"john@example.com"}, {name:"John Smith", email: "john@"} ] An Attachment object has the following properties: blobId: String The id of the binary data. type: String The content-type of the attachment. name: String|null The full file name, e.g. "myworddocument.doc", if available. 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). 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. isInline: Boolean True if the attachment is referenced by a cid: link from within the HTML body of the message. width: Number|null (optional, server MAY omit if not supported) The width (in px) of the image, if the attachment is an image. height: Number|null (optional, server MAY omit if not supported) The height (in px) of the image, if the attachment is an image.

Messages can only be fetched explicitly by id. To fetch messages, make a call to getMessages. It takes the following arguments: accountId: String|null The id of the account to use for this call. If not given, defaults to the primary account. ids: String[] An array of ids for the messages to fetch. 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 object. In addition to this, the client may request the following special values: 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. 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: accountId: String The id of the account used for the call. 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. 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. 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. 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"]

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: accountId: String|null The id of the account to use for this call. If not given, defaults to the primary account. 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. 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. 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. 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: accountId: String The id of the account used for the call. oldState: String This is the sinceState argument echoed back; the state from which the server is returning changes. newState: String This is the state the client will be in after applying the set of changes to the old state. 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. changed: String[] An array of message ids for messages that have either been created or had their state change, and are not currently deleted. 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 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 calculate 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.

The setMessages method encompasses: Creating a draft message Sending a message Changing the flags of a message (unread/flagged status) Adding/removing a message to/from mailboxes (moving a message) Deleting messages It takes the following arguments: accountId: String|null The id of the account to use for this call. If not given, defaults to the primary account. 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. 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). update: String[Message]|null A map of message id to objects containing the properties to update for that Message. 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 keywords 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.

Creating messages via the setMessages method is only for creating draft messages and sending them. For delivering/importing a complete message, use the importMessages method. The properties of the Message object submitted for creation MUST conform to the following conditions: id: This property MUST NOT be included. It is set by the server upon creation. blobId: This property MUST NOT be included. It is set by the server upon creation. threadId: This property MUST NOT be included. It is set by the server upon creation. 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. keywords: This property MUST be included. It MUST include the $Draft keyword and SHOULD also include $Seen. hasAttachment: This property MUST NOT be included. It is set by the server upon creation based on the attachments property. headers: Optional. The keys MUST only contain the characters a-z (lower-case only), 0-9 and hyphens. from: Optional. Overrides a "From" in the headers. to: Optional. Overrides a "To" in the headers. cc: Optional. Overrides a "Cc" in the headers. bcc: Optional. Overrides a "Bcc" in the headers. replyTo: Optional. Overrides a "Reply-To" in the headers. subject: Optional. Defaults to the empty string (""). 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). size: This MUST NOT be included. It is set by the server upon creation. preview: This MUST NOT be included. It is set by the server upon creation. textBody: Optional. If not supplied and an htmlBody is, the server SHOULD generate a text version for the message from the HTML body. htmlBody: Optional. 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. 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.

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 mailboxIds and keywords properties may be modified, and they are subject to the following constraints: mailboxIds: The server MUST reject any attempt to add a message to the outbox that does not have the $Draft keyword with an invalidProperties error. keywords: The server MUST reject any attempt to add or remove the $Draft flag in an update with an invalidProperties error. The server MAY have a maximum number of keywords it supports; if the change would exceed this, it MUST be rejected with a tooManyKeywords error. 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", and remove all other mailbox ids.

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 remove the message from the outbox and add it to the sent mailbox, unless the user has indicated another preference. The version added to the sent mailbox MAY be different (for example have extra headers added by the server), and so have a different id to the version that was in the outbox. If the message has an In-Reply-To header, the server SHOULD add the $Answered keyword to all messages with the coresponding Message-Id header at this point. If the message has an X-Forwarded-Message-Id header, the server SHOULD add the $Forwarded keyword to all messages with the coresponding Message-Id header at this point. The server is responsible for either reporting an error (normally a "bounce" email), or ensuring delivery of the message to the next hop.

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.

If the id given does not correspond to a Message in the given account, the server MUST reject the destruction with a notFound error. Destroying a message removes it from all mailboxes to which it belonged. When emptying the trash, clients SHOULD NOT destroy messages which are also in a mailbox other than trash. For those messages, they should just remove the Trash mailbox from the message.

The response to setMessages is called messagesSet. It has the following arguments: accountId: String The id of the account used for the call. 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. newState: String The state string that will now be returned by getMessages. 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. updated: String[Message|null] The keys in this map are the ids of all messages that were successfully updated. If the server made any other changes to the record beyond those explicitly requested by the client, the value for the corresponding id in the map is an object containing the updated value of each property the server changed. Otherwise (if no properties changed on the server other than those explicitly updated by the client), the value is null. destroyed: String[] A list of Message ids for Messages that were successfully destroyed. 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. 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. 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. 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.

The importMessages method adds 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: accountId: String|null The id of the account to use for this call. If null, defaults to the primary account. messages: String[MessageImport] A map of creation id (client specified) to MessageImport objects An MessageImport object has the following properties: blobId: String The id representing the raw message (see the file upload section). mailboxIds String[] The ids of the mailbox(es) to assign this message to. keywords: String[Boolean] Adding to the outbox will send the message, as described in the setMessages section. The $Draft keyword MUST also be included if the message is being imported to the outbox. The response to importMessages is called messagesImported. It has the following arguments: accountId: String The id of the account used for this call. 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. 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.

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: fromAccountId: String|null The id of the account to copy messages from. If null, defaults to the primary account. toAccountId: String|null The id of the account to copy messages to. If null, defaults to the primary account. messages: String[MessageCopy] A map of creation id to a MessageCopy object. A MessageCopy object has the following properties: messageId: String The id of the message to be copied in the "from" account. mailboxIds: String[] The ids of the mailboxes (in the "to" account) to add the copied message to. keywords: String[Boolean] The keywords 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: fromAccountId: String The id of the account messages were copied from. toAccountId: String The id of the account messages were copied to. 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. 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. 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.

A Identity object stores information about an email address (or domain) the user may send from. It has the following properties: id: String The id of the identity. This property is immutable. name: String The "From" name the client SHOULD use when creating a new message from this identity. 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. replyTo: String The Reply-To value the client SHOULD set when creating a new message from this identity. bcc: String The Bcc value the client SHOULD set when creating a new message from this identity. 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. 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. 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).

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: accountId: String|null The Account to fetch the identities for. If null, the primary account is used. 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: accountId: String The id of the account used for the call. 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. 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. 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.

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: accountId: String|null The id of the account to use for this call. If null, the primary account will be used. 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. 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. 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: accountId: String The id of the account used for the call. oldState: String This is the sinceState argument echoed back; the state from which the server is returning changes. newState: String This is the state the client will be in after applying the set of changes to the old state. 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. 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. 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. 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.

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: accountId: String|null The id of the account to use for this call. If null, the primary account will be used. 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. 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). 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. 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: maxQuotaReached: Returned if the user has reached a server-defined limit on the number of identities. 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: accountId: String The id of the account used for the call. 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. newState: String The state string that will now be returned by getIdentities. created: String[Identity] A map of the creation id to an object containing the id property for all successfully created identities. updated: String[Identity|null] The keys in this map are the ids of all identities that were successfully updated. If the server made any other changes to the record beyond those explicitly requested by the client, the value for the corresponding id in the map is an object containing the updated value of each property the server changed. Otherwise (if no properties changed on the server other than those explicitly updated by the client), the value is null. destroyed: String[] A list of ids for identities that were successfully destroyed. 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. 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. 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: type: String The type of error. 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. stateMismatch: Returned if an ifInState argument was supplied and it does not match the current state.

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: messageId: String The message id the snippet applies to. 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. 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.

To fetch search snippets, make a call to getSearchSnippets. It takes the following arguments: accountId: String|null The id of the account to use for this call. If null, defaults to the primary account. messageIds: String[] The list of ids of messages to fetch the snippets for. filter: FilterCondition|FilterOperator|null The same filter as passed to getMessageList; see the description of this method for details. The response to getSearchSnippets is called searchSnippets. It has the following arguments: accountId: String The id of the account used for the call. filter: FilterCondition|FilterOperator|null Echoed back from the call. list: SearchSnippet[] An array of SearchSnippet objects for the requested message ids. This may not be in the same order as the ids that were in the request. 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.

The VacationResponse object represents the state of vacation-response related settings for an account. It has the following properties: id: String The id of the object. This property is immutable. There is only ever one vacation response object, and its id is "singleton". isEnabled Boolean Should a vacation response be sent if a message arrives between the fromDate and toDate? 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. 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. 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. 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. 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.

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: 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: accountId: String The id of the account used for the call. 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.

Sets properties on the vacation response object. It takes the following arguments: accountId: String|null The Account to set the vacation response for. If null, the primary account is used. 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: updated: String[] updated: String[VacationResponse|null] If successfully updated, this map will have a sole key of "singleton". The value in the map is an object containing the updated value of each property the server changed on the record, if any. Otherwise (if no properties changed on the server other than those explicitly updated by the client), the value is null. notUpdated: String[SetError] A map of id ("singleton") to a SetError object if the update failed. A SetError object has the following properties: type: String The type of error. 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.