Fork me on GitHub

JMAP Mail

This document specifies a data model for synchronising mail with a server using JMAP.

Introduction

JMAP https://tools.ietf.org/html/draft-ietf-jmap-core-03 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.

Notational Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [@!RFC2119].

The underlying format used for this specification is I-JSON ([@!RFC7493]). Consequently, the terms “object” and “array” as well as the four primitive types (strings, numbers, booleans, and null) are to be interpreted as described in Section 1 of [@!RFC7159]. Unless otherwise noted, all the property names and values are case sensitive.

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:

Object properties may also have a set of attributes defined along with the type signature. These have the following meanings:

The Date datatypes

Where Date is given as a type, it means a string in [@!RFC3339] date-time format. To ensure a normalised form, the time-secfrac MUST always be omitted and any letters in the string (e.g. “T” and “Z”) MUST be upper-case. For example, "2014-10-30T14:12:00+08:00".

Where UTCDate is given as a type, it means a Date where the time-offset component MUST be Z (i.e. it must be in UTC time). For example, "2014-10-30T06:12:00Z".

Terminology

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

Addition to the capabilities object

The capabilities object is returned as part of the standard JMAP session object; see the JMAP spec. Servers supporting this specification MUST add a property called ietf:jmapmail to the capabilities object. The value of this property is an object which MUST contain the following information on server capabilities:

Mailboxes

A mailbox represents a named set of emails. This is the primary mechanism for organising emails 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, an email MUST belong to one or more mailboxes. The email id does not change if the email changes mailboxes.

A Mailbox object has the following properties:

The Trash mailbox (that is a mailbox with role == "trash") MUST be treated specially for the purpose of unread counts:

  1. Emails that are only in the Trash (and no other mailbox) are ignored when calculating the unreadThreads count of other mailboxes.
  2. Emails that are not in the Trash are ignored when calculating the unreadThreads count for the Trash mailbox.

The result of this is that emails 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 emails in the Trash when viewing a thread in another mailbox and vice versa. This allows you to delete a single email 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 emails: an unread email in the Trash and a read email in the Inbox. The unreadThreads count would be 1 for the Trash and 0 for the Inbox.

For IMAP compatibility, an email 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).

The following JMAP methods are supported:

Mailbox/get

Standard /get method. The ids argument may be null to fetch all at once.

Mailbox/changes

Standard /changes method, but with one extra argument to the response:

Since counts frequently change but the rest of the mailboxes state for most use cases changes rarely, the server can help the client optimise data transfer by keeping track of changes to email/thread counts separately to other state changes. The changedProperties array may be used directly via a result reference in a subsequent Mailboxe/get call in a single request.

Mailbox/query

Standard /query method.

The FilterCondition object (optionally passed as the filter argument) has the following properties, any of which may be omitted:

A Mailbox object matches the filter if and only if all of the given conditions given match. If zero properties are specified, it is automatically true for all objects.

The following properties MUST be supported for sorting:

Mailbox/queryChanges

Standard /queryChanges method.

Mailbox/set

Standard /set method, but with the following additional argument:

The following extra SetError types are defined:

For destroy:

Threads

Replies are grouped together with the original message to form a thread. In JMAP, a thread is simply a flat list of emails, ordered by date. Every email MUST belong to a thread, even if it is the only email in the thread.

The JMAP spec does not require the server to use any particular algorithm for determining whether two emails belong to the same thread, however there is a recommended algorithm in the implementation guide.

If emails are delivered out of order for some reason, a user may receive two emails in the same thread but without headers that associate them with each other. The arrival of a third email in the thread may provide the missing references to join them all together into a single thread. Since the threadId of an email is immutable, if the server wishes to merge the threads, it MUST handle this by deleting and reinserting (with a new email id) the emails that change threadId.

A Thread object has the following properties:

The following JMAP methods are supported:

Thread/get

Standard /get method.

Example

Request:

[ "Thread/get", {
  "ids": ["f123u4", "f41u44"],
}, "#1" ]

with response:

[ "Thread/get", {
  "accountId": "acme",
  "state": "f6a7e214",
  "list": [
    {
      "id": "f123u4",
      "emailIds": [ "eaa623", "f782cbb"]
    },
    {
      "id": "f41u44",
      "emailIds": [ "82cf7bb" ]
    }
  ],
  "notFound": null
}, "#1" ]

Thread/changes

Standard /changes method.

Emails

An Email object is a JSON representation of an [@!RFC5322] message that hides the complexities of MIME. All special encodings of either headers or textual body parts, such as Base64 ([@!RFC4648]), or [@!RFC2047] encoding of non-ASCII characters, MUST be fully decoded into UTF-8. It has the following properties:

An Emailer object has the following properties:

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:

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 following JMAP methods are supported:

Email/get

Standard /get method, except the client may use the following pseudo values in the properties argument:

Example

Request:

["Email/get", {
  "ids": [ "f123u456", "f123u457" ],
  "properties": [ "threadId", "mailboxIds", "from", "subject", "date" ]
}, "#1"]

and response:

["Email/get", {
  "accountId": "abc",
  "state": "41234123231",
  "list": [
    {
      id: "f123u457",
      threadId: "ef1314a",
      mailboxIds: { "f123": true },
      from: [{name: "Joe Bloggs", email: "joe@bloggs.com"}],
      subject: "Dinner on Thursday?",
      date: "2013-10-13T14:12:00Z"
    }
  ],
  notFound: [ "f123u456" ]
}, "#1"]

Email/changes

Standard /changes method.

Email/query

Standard /query method, but with the following additional arguments:

Filtering

A FilterOperator object has the following properties:

A FilterCondition object has the following properties, any of which may be omitted:

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:

Sorting

The following properties MUST be supported for sorting:

The following properties SHOULD be supported for sorting:

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).

Example sort:

[{
  "property": "someInThreadHaveKeyword:$Flagged",
  "isAscending": false,
}, {
  "property": "subject",
  "collation": "i;ascii-casemap"
}, {
  "property": "receivedAt desc",
  "isAscending": false,
}]

This would sort emails in flagged threads first (the thread is considered flagged if any email within it is flagged), and then in subject order, then newest first for messages with the same subject. If two emails have both identical flagged status, subject and date, the order is server-dependent but must be stable.

Thread collapsing

When collapseThreads == true, then after filtering and sorting the email list, the list is further winnowed by removing any emails 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 email in the list that belongs to the thread.

Response

The response has the following additional argument:

Email/queryChanges

Standard /queryChanges method, with the following additional arguments:

The response has the following additional argument:

Email/set

Standard /set method. The Email/set method encompasses:

When creating an email, the headers property specifies extra headers to add in addition to any based off the parsed properties (like from/to/subject). The keys MUST only contain the characters a-z (lower-case only), 0-9 and hyphens. If a header is included that conflicts with one of the other properties on the Email object (e.g. from, date), the value in the headers object MUST be ignored.

The server MAY also choose to set additional headers. If not included, the server MUST generate and set a Message-Id header in conformance with [@!RFC5322] section 3.6.4.

Other than making sure it conforms to the correct type, the server MUST NOT attempt to validate from/to/cc/bcc (e.g. checking if an email address is valid) when creating an email. This is to ensure drafts can be saved at any point.

Destroying an email removes it from all mailboxes to which it belonged. To just delete an email to trash, simply change the mailboxIds property so it is now in the mailbox with role == "trash", and remove all other mailbox ids.

When emptying the trash, clients SHOULD NOT destroy emails which are also in a mailbox other than trash. For those emails, they SHOULD just remove the Trash mailbox from the email.

The following extra SetError types are defined:

For create:

For create and update:

Email/import

The Email/import method adds [@!RFC5322] messages to a user’s set of emails. The messages must first be uploaded as a file using the standard upload mechanism. It takes the following arguments:

An EmailImport object has the following properties:

Each email to import is considered an atomic unit which may succeed or fail individually. Importing successfully creates a new email object from the data reference by the blobId and applies the given mailboxes, keywords and receivedAt date.

The server MAY forbid two email objects with the same exact [@!RFC5322] content, or even just with the same [@!RFC5322] Message-Id, to coexist within an account. In this case, it MUST reject attempts to import an email considered a duplicate with an alreadyExists SetError. An emailId property of type String MUST be included on the error object with the id of the existing email.

If the blobId, mailboxIds, or keywords properties are invalid (e.g. missing, wrong type, id not found), the server MUST reject the import with an invalidProperties SetError.

If the email cannot be imported because it would take the account over quota, the import should be rejected with a maxQuotaReached SetError.

If the blob referenced is not a valid [@!RFC5322] message, the server MAY modify the message to fix errors (such as removing null bytes or fixing invalid headers). If it does this, the blobId on the response MUST represent the new representation and therefore be different to the blobId on the EmailImport object. Alternatively, the server MAY reject the import with an invalidEmail SetError.

The response has the following arguments:

Email/copy

The only way to move messages between two different accounts is to copy them using the Email/copy method, then once the copy has succeeded, delete the original. The onSuccessDestroyOriginal argument allows you to try to do this in one method call, however note that the two different actions are not atomic, and so it is possible for the copy to succeed but the original not to be destroyed for some reason.

The Email/copy method takes the following arguments:

An EmailCopy object has the following properties:

The server MAY forbid two email objects with the same exact [@!RFC5322] content, or even just with the same [@!RFC5322] Message-Id, to coexist within an account. If duplicates are allowed though, the “from” account may be the same as the “to” account to copy emails within an account.

Each email copy is considered an atomic unit which may succeed or fail individually. Copying successfully MUST create a new email object, with separate ids and mutable properties (e.g. mailboxes and keywords) to the original email.

The response has the following arguments:

The SetError may be any of the standard set errors that may be returned for a create. The following extra SetError type is also defined:

alreadyExists: The server forbids duplicates and the email already exists in the target account. An emailId property of type String MUST be included on the error object with the id of the existing email.

The following additional errors may be returned instead of the Email/copy response:

fromAccountNotFound: A fromAccountId was explicitly included with the request, but it does not correspond to a valid account.

toAccountNotFound: A toAccountId was explicitly included with the request, but it does not correspond to a valid account.

fromAccountNotSupportedByMethod: The fromAccountId given corresponds to a valid account, but does not contain any mail data.

toAccountNotSupportedByMethod: The toAccountId given corresponds to a valid account, but does not contain any mail data.

Email submission

An EmailSubmission object represents the submission of an email for delivery to one or more recipients. It has the following properties:

JMAP servers MAY choose not to expose DSN and MDN responses as Email objects if they correlate to a EmailSubmission object. It SHOULD only do this if it exposes them in the dsnBlobIds and mdnblobIds fields instead, and expects the user to be using clients capable of fetching and displaying delivery status via the EmailSubmission object.

For efficiency, a server MAY destroy EmailSubmission objects a certain amount of time after the email is successfully sent or it has finished retrying sending the email. For very basic SMTP proxies, this MAY be immediately after creation, as it has no way to assign a real id and return the information again if fetched later.

The following JMAP methods are supported:

EmailSubmission/get

Standard /get method.

EmailSubmission/changes

Standard /changes method.

EmailSubmission/query

Standard /query method.

The FilterCondition object (optionally passed as the filter argument) has the following properties, any of which may be omitted:

A EmailSubmission object matches the filter if and only if all of the given conditions given match. If zero properties are specified, it is automatically true for all objects.

The following properties MUST be supported for sorting:

EmailSubmission/queryChanges

Standard /queryChanges method.

EmailSubmission/set

Standard /set method, with the following two extra arguments:

A single implicit Email/set call MUST be made after all EmailSubmission create/update/destroy requests have been processed to perform any changes requested in these two arguments. The response to this MUST be returned after the EmailSubmission/set response.

An email is sent by creating a EmailSubmission object. When processing each create, the server must check that the email is valid, and the user has sufficient authorization to send it. If the creation succeeds, the email will be sent to the recipients given in the envelope rcptTo parameter. The server MUST remove any Bcc header present on the email during delivery. The server MAY add or remove other headers from the submitted email, or make further alterations in accordance with the server’s policy during delivery.

If the referenced email is destroyed at any point after the EmailSubmission object is created, this MUST NOT change the behaviour of the email submission (i.e. it does not cancel a future send).

Similarly, destroying a EmailSubmission object MUST NOT affect the deliveries it represents. It purely removes the record of the email submission. The server MAY automatically destroy EmailSubmission objects after a certain time or in response to other triggers, and MAY forbid the client from manually destroying EmailSubmission objects.

The following extra SetError types are defined:

For create:

For update:

Identities

An Identity object stores information about an email address (or domain) the user may send from. It has the following properties:

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).

The following JMAP methods are supported:

Identity/get

Standard /get method. The ids argument may be null to fetch all at once.

Identity/changes

Standard /changes method.

Identity/set

Standard /set method. The following extra SetError types are defined:

For create:

For destroy:

Search snippets

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 email. Search snippets represent this data.

A SearchSnippet object has the following properties:

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, preview and attachments properties.

Note, unlike most data types, a SearchSnippet DOES NOT have a property called id.

The following JMAP method is supported:

SearchSnippet/get

To fetch search snippets, make a call to SearchSnippet/get. It takes the following arguments:

The response has the following arguments:

Since snippets are only based on immutable properties, there is no state string or update mechanism needed.

The following additional errors may be returned instead of the searchSnippets response:

requestTooLarge: Returned if the number of emailIds requested by the client exceeds the maximum number the server is willing to process in a single method call.

unsupportedFilter: Returned if the server is unable to process the given filter for any reason.

Vacation response

The VacationResponse object represents the state of vacation-response related settings for an account. It has the following properties:

The following JMAP methods are supported:

VacationResponse/get

Standard /get method.

There MUST only be exactly one VacationResponse object in an account. It MUST have the id "singleton".

VacationResponse/set

Standard /set method.

Security considerations

All security considerations of JMAP {TODO: insert RFC ref} apply to this specification.