Listen to Fastmail CEO Bron Gondwana talk about JMAP on the Digital Citizen Podcast

JMAP Mail

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

Introduction

The JSON Meta Application Protocol (JMAP) [@!RFC8620] 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 accessing a mail store over JMAP, allowing you to query, read, organise, and submit mail for sending.

The data model is designed to allow a server to provide consistent access to the same data via IMAP [@?RFC3501] as well as JMAP. As in IMAP, a message must belong to a Mailbox; however, in JMAP, its id does not change if you move it between Mailboxes, and the server may allow it to belong to multiple Mailboxes simultaneously (often exposed in a user agent as labels rather than folders).

As in IMAP, messages may also be assigned zero or more keywords: short arbitrary strings. These are primarily intended to store metadata to inform client display, such as unread status or whether a message has been replied to. An IANA registry allows common semantics to be shared between clients and extended easily in the future.

A message and its replies are linked on the server by a common Thread id. Clients may fetch the list of messages with a particular Thread id to more easily present a threaded or conversational interface.

Permissions for message access happen on a per-Mailbox basis. Servers may give the user restricted permissions for certain Mailboxes, for example, if another user’s inbox has been shared as read-only with them.

Notational Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [@!RFC2119] [@!RFC8174] when, and only when, they appear in all capitals, as shown here.

Type signatures, examples, and property descriptions in this document follow the conventions established in Section 1.1 of [@!RFC8620]. Data types defined in the core specification are also used in this document.

Servers MUST support all properties specified for the new data types defined in this document.

Terminology

This document uses the same terminology as in the core JMAP specification.

The terms Mailbox, Thread, Email, SearchSnippet, EmailSubmission and VacationResponse (with that specific capitalisation) are used to refer to the data types defined in this document and instances of those data types.

The term message refers to a document in Internet Message Format, as described in [@!RFC5322]. The Email data type represents messages in the mail store and associated metadata.

Additions to the Capabilities Object

The capabilities object is returned as part of the JMAP Session object; see [@!RFC8620], Section 2.

This document defines three additional capability URIs.

urn:ietf:params:jmap:mail

This represents support for the Mailbox, Thread, Email, and SearchSnippet data types and associated API methods. The value of this property in the JMAP session capabilities property is an empty object.

The value of this property in an account’s accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:

urn:ietf:params:jmap:submission

This represents support for the Identity and EmailSubmission data types and associated API methods. The value of this property in the JMAP session capabilities property is an empty object.

The value of this property in an account’s accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:

urn:ietf:params:jmap:vacationresponse

This represents support for the VacationResponse data type and associated API methods. The value of this property is an empty object in both the JMAP session capabilities property and an account’s accountCapabilities property.

Data Type Support in Different Accounts

The server MUST include the appropriate capability strings as keys in the accountCapabilities property of any account with which the user may use the data types represented by that URI. Supported data types may differ between accounts the user has access to. For example, in the user’s personal account, they may have access to all three sets of data, but in a shared account, they may only have data for urn:ietf:params:jmap:mail. This means they can access Mailbox/Thread/Email data in the shared account but are not allowed to send as that account (and so do not have access to Identity/EmailSubmission objects) or view/set its VacationResponse.

Push

Servers MUST support the JMAP push mechanisms, as specified in [@!RFC8620] Section 7, to receive notifications when the state changes for any of the types defined in this specification.

In addition, servers that implement the “urn:ietf:params:jmap:mail” capability MUST support pushing state changes for a type called “EmailDelivery”. There are no methods to act on this type; it only exists as part of the push mechanism. The state string for this MUST change whenever a new Email is added to the store, but it SHOULD NOT change upon any other change to the Email objects, for example, if one is marked as read or deleted.

Clients in battery-constrained environments may wish to delay fetching changes initiated by the user but fetch new Emails immediately so they can notify the user. To do this, they can register for pushes for the EmailDelivery type rather than the Email type (as defined in Section 4).

Example

The client has registered for push notifications (see [@!RFC8620]) just for the EmailDelivery type. The user marks an Email as read on another device, causing the state string for the Email type to change; however, as nothing new was added to the store, the EmailDelivery state does not change and nothing is pushed to the client. A new message arrives in the user’s inbox, again causing the Email state to change. This time, the EmailDelivery state also changes, and a StateChange object is pushed to the client with the new state string. The client may then resync to fetch the new Email immediately.

Ids

If a JMAP Mail server also provides an IMAP interface to the data and supports IMAP Extension for Object Identifiers [@!RFC8474], the ids SHOULD be the same for Mailbox, Thread, and Email objects in JMAP.

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:

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 it from the trash Mailbox and leave it in the other Mailbox).

The following JMAP methods are supported.

Mailbox/get

This is a standard “/get” method as described in [@!RFC8620], Section 5.1. The ids argument may be null to fetch all at once.

Mailbox/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2 but with one extra argument to the response:

Since counts frequently change but other properties are generally only changed rarely, the server can help the client optimise data transfer by keeping track of changes to Email/Thread counts separate from other state changes. The updatedProperties array may be used directly via a back-reference in a subsequent Mailbox/get call in the same request, so only these properties are returned if nothing else has changed.

Mailbox/query

This is a standard “/query” method as described in [@!RFC8620], Section 5.5, but with the following additional request argument:

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

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

The following Mailbox properties MUST be supported for sorting:

Mailbox/queryChanges

This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6.

Mailbox/set

This is a standard “/set” method as described in [@!RFC8620], Section 5.3, but with the following additional request argument:

The following extra SetError types are defined:

For destroy:

Example

Fetching all Mailboxes in an account:

[[ "Mailbox/get", {
  "accountId": "u33084183",
  "ids": null
}, "0" ]]

And the response:

[[ "Mailbox/get", {
  "accountId": "u33084183",
  "state": "78540",
  "list": [{
    "id": "MB23cfa8094c0f41e6",
    "name": "Inbox",
    "parentId": null,
    "role": "inbox",
    "sortOrder": 10,
    "totalEmails": 16307,
    "unreadEmails": 13905,
    "totalThreads": 5833,
    "unreadThreads": 5128,
    "myRights": {
      "mayAddItems": true,
      "mayRename": false,
      "maySubmit": true,
      "mayDelete": false,
      "maySetKeywords": true,
      "mayRemoveItems": true,
      "mayCreateChild": true,
      "maySetSeen": true,
      "mayReadItems": true
    },
    "isSubscribed": true
  }, {
    "id": "MB674cc24095db49ce",
    "name": "Important mail",
    ...
  }, ... ],
  "notFound": []
}, "0" ]]

Now suppose an Email is marked read, and we get a push update that the Mailbox state has changed. You might fetch the updates like this:

[[ "Mailbox/changes", {
  "accountId": "u33084183",
  "sinceState": "78540"
}, "0" ],
[ "Mailbox/get", {
  "accountId": "u33084183",
  "#ids": {
    "resultOf": "0",
    "name": "Mailbox/changes",
    "path": "/created"
  }
}, "1" ],
[ "Mailbox/get", {
  "accountId": "u33084183",
  "#ids": {
    "resultOf": "0",
    "name": "Mailbox/changes",
    "path": "/updated"
  },
  "#properties": {
    "resultOf": "0",
    "name": "Mailbox/changes",
    "path": "/updatedProperties"
  }
}, "2" ]]

This fetches the list of ids for created/updated/destroyed Mailboxes, then using back-references, it fetches the data for just the created/updated Mailboxes in the same request. The response may look something like this:

[[ "Mailbox/changes", {
  "accountId": "u33084183",
  "oldState": "78541",
  "newState": "78542",
  "hasMoreChanges": false,
  "updatedProperties": [
    "totalEmails", "unreadEmails",
    "totalThreads", "unreadThreads"
  ],
  "created": [],
  "updated": ["MB23cfa8094c0f41e6"],
  "destroyed": []
}, "0" ],
[ "Mailbox/get", {
  "accountId": "u33084183",
  "state": "78542",
  "list": [],
  "notFound": []
}, "1" ],
[ "Mailbox/get", {
  "accountId": "u33084183",
  "state": "78542",
  "list": [{
    "id": "MB23cfa8094c0f41e6",
    "totalEmails": 16307,
    "unreadEmails": 13903,
    "totalThreads": 5833,
    "unreadThreads": 5127
  }],
  "notFound": []
}, "2" ]]

Here’s an example where we try to rename one Mailbox and destroy another:

[[ "Mailbox/set", {
  "accountId": "u33084183",
  "ifInState": "78542",
  "update": {
    "MB674cc24095db49ce": {
      "name": "Maybe important mail"
    }
  },
  "destroy": [ "MB23cfa8094c0f41e6" ]
}, "0" ]]

Suppose the rename succeeds, but we don’t have permission to destroy the Mailbox we tried to destroy; we might get back:

[[ "Mailbox/set", {
  "accountId": "u33084183",
  "oldState": "78542",
  "newState": "78549",
  "updated": {
      "MB674cc24095db49ce": null
  },
  "notDestroyed": {
    "MB23cfa8094c0f41e6": {
      "type": "forbidden"
    }
  }
}, "0" ]]

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 exact algorithm for determining whether two Emails belong to the same Thread is not mandated in this spec to allow for compatibility with different existing systems. For new implementations, it is suggested that two messages belong in the same Thread if both of the following conditions apply:

  1. An identical message id [@!RFC5322] appears in both messages in any of the Message-Id, In-Reply-To, and References header fields.
  2. After stripping automatically added prefixes such as “Fwd:”, “Re:”, “[List-Tag]”, etc., and ignoring white space, the subjects are the same. This avoids the situation where a person replies to an old message as a convenient way of finding the right recipient to send to but changes the subject and starts a new conversation.

If messages are delivered out of order for some reason, a user may have two Emails in the same Thread but without headers that associate them with each other. The arrival of a third Email 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

This is a standard “/get” method as described in [@!RFC8620], Section 5.1.

Example

Request:

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

with response:

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

Thread/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.

Emails

An Email object is a representation of a message [@!RFC5322], which allows clients to avoid the complexities of MIME parsing, transfer encoding, and character encoding.

Properties of the Email Object

Broadly, a message consists of two parts: a list of header fields and then a body. The Email data type provides a way to access the full structure or to use simplified properties and avoid some complexity if this is sufficient for the client application.

While raw headers can be fetched and set, the vast majority of clients should use an appropriate parsed form for each of the header fields it wants to process, as this allows it to avoid the complexities of various encodings that are required in a valid message per RFC 5322.

The body of a message is normally a MIME-encoded set of documents in a tree structure. This may be arbitrarily nested, but the majority of email clients present a flat model of a message body (normally plaintext or HTML) with a set of attachments. Flattening the MIME structure to form this model can be difficult and causes inconsistency between clients. Therefore, in addition to the bodyStructure property, which gives the full tree, the Email object contains 3 alternate properties with flat lists of body parts:

The bodyValues property allows for clients to fetch the value of text parts directly without having to do a second request for the blob and to have the server handle decoding the charset into unicode. This data is in a separate property rather than on the EmailBodyPart object to avoid duplication of large amounts of data, as the same part may be included twice if the client fetches more than one of bodyStructure, textBody, and htmlBody.

In the following subsections, the common notational convention for wildcards has been adopted for content types, so foo/* means any content type that starts with foo/.

Due to the number of properties involved, the set of Email properties is specified over the following four subsections. This is purely for readability; all properties are top-level peers.

Metadata

These properties represent metadata about the message in the mail store and are not derived from parsing the message itself.

Header Fields Parsed Forms

Header field properties are derived from the message header fields [@!RFC5322] [@!RFC6532]. All header fields may be fetched in a raw form. Some header fields may also be fetched in a parsed form. The structured form that may be fetched depends on the header. The forms are defined in the subsections that follow.

Raw

Type: String

The raw octets of the header field value from the first octet following the header field name terminating colon, up to but excluding the header field terminating CRLF. Any standards-compliant message MUST be either ASCII (RFC 5322) or UTF-8 (RFC 6532); however, other encodings exist in the wild. A server SHOULD replace any octet or octet run with the high bit set that violates UTF-8 syntax with the unicode replacement character (U+FFFD). Any NUL octet MUST be dropped.

This form will typically have a leading space, as most generated messages insert a space after the colon that terminates the header field name.

Text

Type: String

The header field value with:

  1. White space unfolded (as defined in [@!RFC5322], Section 2.2.3).
  2. The terminating CRLF at the end of the value removed.
  3. Any SP characters at the beginning of the value removed.
  4. Any syntactically correct encoded sections [@!RFC2047] with a known character set decoded. Any NUL octets or control characters encoded per [@!RFC2047] are dropped from the decoded value. Any text that looks like syntax per [@!RFC2047] but violates placement or white space rules per [@!RFC2047] MUST NOT be decoded.
  5. The resulting unicode converted to Normalization Form C (NFC) form.

If any decodings fail, the parser SHOULD insert a unicode replacement character (U+FFFD) and attempt to continue as much as possible.

To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:

Addresses

Type: EmailAddress[]

The header field is parsed as an address-list value, as specified in [@!RFC5322], Section 3.4, into the EmailAddress[] type. There is an EmailAddress item for each mailbox parsed from the address-list. Group and comment information is discarded.

An EmailAddress object has the following properties:

Any syntactically correct encoded sections [@!RFC2047] with a known encoding MUST be decoded, following the same rules as for the Text form.

Parsing SHOULD be best effort in the face of invalid structure to accommodate invalid messages and semi-complete drafts. EmailAddress objects MAY have an email property that does not conform to the addr-spec form (for example, may not contain an @ symbol).

For example, the following address-list string:

"  James Smythe" <james@example.com>, Friends:
  jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?=
  <john@example.com>;

would be parsed as:

[
  { "name": "James Smythe", "email": "james@example.com" },
  { "name": null, "email": "jane@example.com" },
  { "name": "John Smîth", "email": "john@example.com" }
]

To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:

GroupedAddresses

Type: EmailAddressGroup[]

This is similar to the Addresses form but preserves group information. The header field is parsed as an address-list value, as specified in [@!RFC5322], Section 3.4, into the GroupedAddresses[] type. Consecutive mailbox values that are not part of a group are still collected under an EmailAddressGroup object to provide a uniform type.

An EmailAddressGroup object has the following properties:

Any syntactically correct encoded sections [@!RFC2047] with a known encoding MUST be decoded, following the same rules as for the Text form.

Parsing SHOULD be best effort in the face of invalid structure to accommodate invalid messages and semi-complete drafts.

For example, the following address-list string:

"  James Smythe" <james@example.com>, Friends:
  jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?=
  <john@example.com>;

would be parsed as:

[
  { "name": null, "addresses": [
    { "name": "James Smythe", "email": "james@example.com" }
  ]},
  { "name": "Friends", "addresses": [
    { "name": null, "email": "jane@example.com" },
    { "name": "John Smîth", "email": "john@example.com" }
  ]}
]

To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the same header fields as the Addresses form.

MessageIds

Type: String[]|null

The header field is parsed as a list of msg-id values, as specified in [@!RFC5322], Section 3.6.4, into the String[] type. Comments and/or folding white space (CFWS) and surrounding angle brackets (<>) are removed. If parsing fails, the value is null.

To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:

Date

Type: Date|null

The header field is parsed as a date-time value, as specified in [@!RFC5322], Section 3.3, into the Date type. If parsing fails, the value is null.

To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:

URLs

Type: String[]|null

The header field is parsed as a list of URLs, as described in [@!RFC2369], into the String[] type. Values do not include the surrounding angle brackets or any comments in the header with the URLs. If parsing fails, the value is null.

To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:

Header Fields Properties

The following low-level Email property is specified for complete access to the header data of the message:

In addition, the client may request/send properties representing individual header fields of the form:

header:{header-field-name}

Where {header-field-name} means any series of one or more printable ASCII characters (i.e., characters that have values between 33 and 126, inclusive), except for colon (:). The property may also have the following suffixes:

If both suffixes are used, they MUST be specified in the order above. Header field names are matched case insensitively. The value is typed according to the requested form or to an array of that type if :all is used. If no header fields exist in the message with the requested name, the value is null if fetching a single instance or an empty array if requesting :all.

As a simple example, if the client requests a property called header:subject, this means find the last header field in the message named “subject” (matched case insensitively) and return the value in Raw form, or null if no header field of this name is found.

For a more complex example, consider the client requesting a property called header:Resent-To:asAddresses:all. This means:

  1. Find all header fields named Resent-To (matched case insensitively).
  2. For each instance, parse the header field value in the Addresses form.
  3. The result is of type EmailAddress[][] — each item in the array corresponds to the parsed value (which is itself an array) of the Resent-To header field instance.

The following convenience properties are also specified for the Email object:

Body Parts

These properties are derived from the message body [@!RFC5322] and its MIME entities [@RFC2045].

An EmailBodyPart object has the following properties:

In addition, the client may request/send EmailBodyPart properties representing individual header fields, following the same syntax and semantics as for the Email object, e.g., header:Content-Type.

The following Email properties are specified for access to the body data of the message:

The exact algorithm for decomposing bodyStructure into textBody, htmlBody, and attachments part lists is not mandated, as this is a quality-of-service implementation issue and likely to require workarounds for malformed content discovered over time. However, the following algorithm (expressed here in JavaScript) is suggested as a starting point, based on real-world experience:

function isInlineMediaType ( type ) {
  return type.startsWith( 'image/' ) ||
         type.startsWith( 'audio/' ) ||
         type.startsWith( 'video/' );
}

function parseStructure ( parts, multipartType, inAlternative,
        htmlBody, textBody, attachments ) {

    // For multipartType == alternative
    let textLength = textBody ? textBody.length : -1;
    let htmlLength = htmlBody ? htmlBody.length : -1;

    for ( let i = 0; i < parts.length; i += 1 ) {
        let part = parts[i];
        let isMultipart = part.type.startsWith( 'multipart/' );
        // Is this a body part rather than an attachment
        let isInline = part.disposition != "attachment" &&
            // Must be one of the allowed body types
            ( part.type == "text/plain" ||
              part.type == "text/html" ||
              isInlineMediaType( part.type ) ) &&
            // If multipart/related, only the first part can be inline
            // If a text part with a filename, and not the first item
            // in the multipart, assume it is an attachment
            ( i === 0 ||
              ( multipartType != "related" &&
                ( isInlineMediaType( part.type ) || !part.name ) ) );

        if ( isMultipart ) {
            let subMultiType = part.type.split( '/' )[1];
            parseStructure( part.subParts, subMultiType,
                inAlternative || ( subMultiType == 'alternative' ),
                htmlBody, textBody, attachments );
        } else if ( isInline ) {
            if ( multipartType == 'alternative' ) {
                switch ( part.type ) {
                case 'text/plain':
                    textBody.push( part );
                    break;
                case 'text/html':
                    htmlBody.push( part );
                    break;
                default:
                    attachments.push( part );
                    break;
                }
                continue;
            } else if ( inAlternative ) {
                if ( part.type == 'text/plain' ) {
                    htmlBody = null;
                }
                if ( part.type == 'text/html' ) {
                    textBody = null;
                }
            }
            if ( textBody ) {
                textBody.push( part );
            }
            if ( htmlBody ) {
                htmlBody.push( part );
            }
            if ( ( !textBody || !htmlBody ) &&
                    isInlineMediaType( part.type ) ) {
                attachments.push( part );
            }
        } else {
            attachments.push( part );
        }
    }

    if ( multipartType == 'alternative' && textBody && htmlBody ) {
        // Found HTML part only
        if ( textLength == textBody.length &&
                htmlLength != htmlBody.length ) {
            for ( let i = htmlLength; i < htmlBody.length; i += 1 ) {
                textBody.push( htmlBody[i] );
            }
        }
        // Found plaintext part only
        if ( htmlLength == htmlBody.length &&
                textLength != textBody.length ) {
            for ( let i = textLength; i < textBody.length; i += 1 ) {
                htmlBody.push( textBody[i] );
            }
        }
    }
}

// Usage:
let htmlBody = [];
let textBody = [];
let attachments = [];

parseStructure( [ bodyStructure ], 'mixed', false,
    htmlBody, textBody, attachments );

For instance, consider a message with both text and HTML versions that has gone through a list software manager that attaches a header and footer. It might have a MIME structure something like:

multipart/mixed
  text/plain, content-disposition=inline - A
  multipart/mixed
    multipart/alternative
      multipart/mixed
        text/plain, content-disposition=inline - B
        image/jpeg, content-disposition=inline - C
        text/plain, content-disposition=inline - D
      multipart/related
        text/html - E
        image/jpeg - F
    image/jpeg, content-disposition=attachment - G
    application/x-excel - H
    message/rfc822 - J
  text/plain, content-disposition=inline - K

In this case, the above algorithm would decompose this to:

textBody => [ A, B, C, D, K ]
htmlBody => [ A, E, K ]
attachments => [ C, F, G, H, J ]

Email/get

This is a standard “/get” method as described in [@!RFC8620], Section 5.1, with the following additional request arguments:

If the standard properties argument is omitted or null, the following default MUST be used instead of “all” properties:

[ "id", "blobId", "threadId", "mailboxIds", "keywords", "size",
"receivedAt", "messageId", "inReplyTo", "references", "sender", "from",
"to", "cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment",
"preview", "bodyValues", "textBody", "htmlBody", "attachments" ]

The following properties are expected to be fast to fetch in a quality implementation:

Clients SHOULD take care when fetching any other properties, as there may be significantly longer latency in fetching and returning the data.

As specified above, parsed forms of headers may only be used on appropriate header fields. Attempting to fetch a form that is forbidden (e.g., header:From:asDate) MUST result in the method call being rejected with an invalidArguments error.

Where a specific header field is requested as a property, the capitalization of the property name in the response MUST be identical to that used in the request.

Example

Request:

[[ "Email/get", {
  "ids": [ "f123u456", "f123u457" ],
  "properties": [ "threadId", "mailboxIds", "from", "subject",
    "receivedAt", "header:List-POST:asURLs",
    "htmlBody", "bodyValues" ],
  "bodyProperties": [ "partId", "blobId", "size", "type" ],
  "fetchHTMLBodyValues": true,
  "maxBodyValueBytes": 256
}, "#1" ]]

and response:

[[ "Email/get", {
  "accountId": "abc",
  "state": "41234123231",
  "list": [
    {
      "id": "f123u457",
      "threadId": "ef1314a",
      "mailboxIds": { "f123": true },
      "from": [{ "name": "Joe Bloggs", "email": "joe@example.com" }],
      "subject": "Dinner on Thursday?",
      "receivedAt": "2013-10-13T14:12:00Z",
      "header:List-POST:asURLs": [
        "mailto:partytime@lists.example.com"
      ],
      "htmlBody": [{
        "partId": "1",
        "blobId": "B841623871",
        "size": 283331,
        "type": "text/html"
      }, {
        "partId": "2",
        "blobId": "B319437193",
        "size": 10343,
        "type": "text/plain"
      }],
      "bodyValues": {
        "1": {
          "isEncodingProblem": false,
          "isTruncated": true,
          "value": "<html><body><p>Hello ..."
        },
        "2": {
          "isEncodingProblem": false,
          "isTruncated": false,
          "value": "-- Sent by your friendly mailing list ..."
        }
      }
    }
  ],
  "notFound": [ "f123u456" ]
}, "#1" ]]

Email/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2. If generating intermediate states for a large set of changes, it is recommended that newer changes be returned first, as these are generally of more interest to users.

Email/query

This is a standard “/query” method as described in [@!RFC8620], Section 5.5, but with the following additional request arguments:

In quality implementations, the query “total” property is expected to be fast to calculate when the filter consists solely of a single inMailbox property, as it is the same as the totalEmails or totalThreads properties (depending on whether collapseThreads is true) of the associated Mailbox object.

Filtering

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 value for the property field on the Comparator object MUST be supported for sorting:

The following values for the property field on the Comparator object SHOULD be supported for sorting. When specifying a “hasKeyword”, “allInThreadHaveKeyword”, or “someInThreadHaveKeyword” sort, the Comparator object MUST also have a keyword property.

The server MAY support sorting based on other properties as well. A client can discover which properties are supported by inspecting the account’s capabilities object (see Section 1.3).

Example sort:

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

This would sort Emails in flagged Threads first (the Thread is considered flagged if any Email within it is flagged), in subject order second, and then from newest first for messages with the same subject. If two Emails have identical values for all three properties, then the order is server dependent but must be stable.

Thread Collapsing

When collapseThreads is 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 result, at the position of the first Email in the list that belongs to the Thread (given the current sort/filter).

Email/queryChanges

This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6, with the following additional request argument:

Email/set

This is a standard “/set” method as described in [@!RFC8620], Section 5.3. The Email/set method encompasses:

The format of the keywords/mailboxIds properties means that when updating an Email, you can either replace the entire set of keywords/Mailboxes (by setting the full value of the property) or add/remove individual ones using the JMAP patch syntax (see [@!RFC8620], Section 5.3 for the specification and Section 5.7 for an example).

Due to the format of the Email object, when creating an Email there are a number of ways to specify the same information. To ensure that the message [@!RFC5322] to create is unambiguous, the following constraints apply to Email objects submitted for creation:

Creation attempts that violate any of this SHOULD be rejected with an invalidProperties error; however, a server MAY choose to modify the Email (e.g., choose between conflicting headers, use a different content-encoding, etc.) to comply with its requirements instead.

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

The final message generated may be invalid per RFC 5322. For example, if it is a half-finished draft, the To header field may have a value that does not conform to the required syntax for this header. The message will be checked for strict conformance when submitted for sending (see the EmailSubmission object description).

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 a role property equal to trash, and remove all other Mailbox ids.

When emptying the trash, clients SHOULD NOT destroy Emails that are also in a Mailbox other than trash. For those Emails, they SHOULD just remove the trash Mailbox from the Email.

For successfully created Email objects, the created response contains the id, blobId, threadId, and size properties of the object.

The following extra SetError types are defined:

For create:

For create and update:

Email/copy

This is a standard “/copy” method as described in [@!RFC8620], Section 5.4, except only the mailboxIds, keywords, and receivedAt properties may be set during the copy. This method cannot modify the message represented by the Email.

The server MAY forbid two Email objects with identical message content [@!RFC5322], or even just with the same Message-ID [@!RFC5322], to coexist within an account; if the target account already has the Email, the copy will be rejected with a standard alreadyExists error.

For successfully copied Email objects, the created response contains the id, blobId, threadId, and size properties of the new object.

Email/import

The Email/import method adds messages [@!RFC5322] to the set of Emails in an account. The server MUST support messages with Email Address Internationalization (EAI) headers [@!RFC6532]. The messages must first be uploaded as blobs using the standard upload mechanism. The method takes the following arguments:

An EmailImport object has the following properties:

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

The server MAY forbid two Email objects with the same exact content [@!RFC5322], or even just with the same Message-ID [@!RFC5322], to coexist within an account. In this case, it MUST reject attempts to import an Email considered to be a duplicate with an alreadyExists SetError. An existingId property of type Id MUST be included on the SetError object with the id of the existing Email. If duplicates are allowed, the newly created Email object MUST have a separate id and independent mutable properties to the existing object.

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 an overQuota SetError.

If the blob referenced is not a valid message [@!RFC5322], the server MAY modify the message to fix errors (such as removing NUL octets 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:

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

stateMismatch: An ifInState argument was supplied, and it does not match the current state.

Email/parse

This method allows you to parse blobs as messages [@!RFC5322] to get Email objects. The server MUST support messages with EAI headers [@!RFC6532]. This can be used to parse and display attached messages without having to import them as top-level Email objects in the mail store in their own right.

The following metadata properties on the Email objects will be null if requested:

The threadId property of the Email MAY be present if the server can calculate which Thread the Email would be assigned to were it to be imported. Otherwise, this too is null if fetched.

The Email/parse method takes the following arguments:

The response has the following arguments:

As specified above, parsed forms of headers may only be used on appropriate header fields. Attempting to fetch a form that is forbidden (e.g., header:From:asDate) MUST result in the method call being rejected with an invalidArguments error.

Where a specific header field is requested as a property, the capitalization of the property name in the response MUST be identical to that used in the request.

Examples

A client logs in for the first time. It first fetches the set of Mailboxes. Now it will display the inbox to the user, which we will presume has Mailbox id “fb666a55”. The inbox may be (very!) large, but the user’s screen is only so big, so the client can just load the Threads it needs to fill the screen and then load in more only when the user scrolls. The client sends this request:

[[ "Email/query",{
  "accountId": "ue150411c",
  "filter": {
    "inMailbox": "fb666a55"
  },
  "sort": [{
    "isAscending": false,
    "property": "receivedAt"
  }],
  "collapseThreads": true,
  "position": 0,
  "limit": 30,
  "calculateTotal": true
}, "0" ],
[ "Email/get", {
  "accountId": "ue150411c",
  "#ids": {
    "resultOf": "0",
    "name": "Email/query",
    "path": "/ids"
  },
  "properties": [
    "threadId"
  ]
}, "1" ],
[ "Thread/get", {
  "accountId": "ue150411c",
  "#ids": {
    "resultOf": "1",
    "name": "Email/get",
    "path": "/list/*/threadId"
  }
}, "2" ],
[ "Email/get", {
  "accountId": "ue150411c",
  "#ids": {
    "resultOf": "2",
    "name": "Thread/get",
    "path": "/list/*/emailIds"
  },
  "properties": [
    "threadId",
    "mailboxIds",
    "keywords",
    "hasAttachment",
    "from",
    "subject",
    "receivedAt",
    "size",
    "preview"
  ]
}, "3" ]]

Let’s break down the 4 method calls to see what they’re doing:

“0”: This asks the server for the ids of the first 30 Email objects in the inbox, sorted newest first, ignoring Emails from the same Thread as a newer Email in the Mailbox (i.e., it is the first 30 unique Threads).

“1”: Now we use a back-reference to fetch the Thread ids for each of these Email ids.

“2”: Another back-reference fetches the Thread object for each of these Thread ids.

“3”: Finally, we fetch the information we need to display the Mailbox listing (but no more!) for every Email in each of these 30 Threads. The client may aggregate this data for display, for example, by showing the Thread as “flagged” if any of the Emails in it has the $flagged keyword.

The response from the server may look something like this:

[[ "Email/query", {
  "accountId": "ue150411c",
  "queryState": "09aa9a075588-780599:0",
  "canCalculateChanges": true,
  "position": 0,
  "total": 115,
  "ids": [ "Ma783e5cdf5f2deffbc97930a",
    "M9bd17497e2a99cb345fc1d0a", ... ]
}, "0" ],
[ "Email/get", {
  "accountId": "ue150411c",
  "state": "780599",
  "list": [{
    "id": "Ma783e5cdf5f2deffbc97930a",
    "threadId": "T36703c2cfe9bd5ed"
  }, {
    "id": "M9bd17497e2a99cb345fc1d0a",
    "threadId": "T0a22ad76e9c097a1"
  }, ... ],
  "notFound": []
}, "1" ],
[ "Thread/get", {
  "accountId": "ue150411c",
  "state": "22a8728b",
  "list": [{
    "id": "T36703c2cfe9bd5ed",
    "emailIds": [ "Ma783e5cdf5f2deffbc97930a" ]
  }, {
    "id": "T0a22ad76e9c097a1",
    "emailIds": [ "M3b568670a63e5d100f518fa5",
      "M9bd17497e2a99cb345fc1d0a" ]
  },  ... ],
  "notFound": []
}, "2" ],
[ "Email/get", {
  "accountId": "ue150411c",
  "state": "780599",
  "list": [{
    "id": "Ma783e5cdf5f2deffbc97930a",
    "threadId": "T36703c2cfe9bd5ed",
    "mailboxIds": {
      "fb666a55": true
    },
    "keywords": {
      "$seen": true,
      "$flagged": true
    },
    "hasAttachment": true,
    "from": [{
      "email": "jdoe@example.com",
      "name": "Jane Doe"
    }],
    "subject": "The Big Reveal",
    "receivedAt": "2018-06-27T00:20:35Z",
    "size": 175047,
    "preview": "As you may be aware, we are required to prepare a
      presentation where we wow a panel of 5 random members of the
      public, on or before 30 June each year. We have drafted…"
  },
  ...
  ],
  "notFound": []
}, "3" ]]

Now, on another device, the user marks the first Email as unread, sending this API request:

[[ "Email/set", {
  "accountId": "ue150411c",
  "update": {
    "Ma783e5cdf5f2deffbc97930a": {
      "keywords/$seen": null
    }
  }
}, "0" ]]

The server applies this and sends the success response:

[[ "Email/set", {
  "accountId": "ue150411c",
  "oldState": "780605",
  "newState": "780606",
  "updated": {
    "Ma783e5cdf5f2deffbc97930a": null
  },
  ...
}, "0" ]]

The user also deletes a few Emails, and then a new message arrives.

Back on our original machine, we receive a push update that the state string for Email is now “780800”. As this does not match the client’s current state, it issues a request for the changes:

[[ "Email/changes", {
  "accountId": "ue150411c",
  "sinceState": "780605",
  "maxChanges": 50
}, "3" ],
[ "Email/queryChanges", {
  "accountId": "ue150411c",
  "filter": {
    "inMailbox": "fb666a55"
  },
  "sort": [{
    "property": "receivedAt",
    "isAscending": false
  }],
  "collapseThreads": true,
  "sinceQueryState": "09aa9a075588-780599:0",
  "upToId": "Mc2781d5e856a908d8a35a564",
  "maxChanges": 25,
  "calculateTotal": true
}, "11" ]]

The response:

[[ "Email/changes", {
  "accountId": "ue150411c",
  "oldState": "780605",
  "newState": "780800",
  "hasMoreChanges": false,
  "created": [ "Me8de6c9f6de198239b982ea2" ],
  "updated": [ "Ma783e5cdf5f2deffbc97930a" ],
  "destroyed": [ "M9bd17497e2a99cb345fc1d0a", ... ]
}, "3" ],
[ "Email/queryChanges", {
  "accountId": "ue150411c",
  "oldQueryState": "09aa9a075588-780599:0",
  "newQueryState": "e35e9facf117-780615:0",
  "added": [{
    "id": "Me8de6c9f6de198239b982ea2",
    "index": 0
  }],
  "removed": [ "M9bd17497e2a99cb345fc1d0a" ],
  "total": 115
}, "11" ]]

The client can update its local cache of the query results by removing “M9bd17497e2a99cb345fc1d0a” and then splicing in “Me8de6c9f6de198239b982ea2” at position 0. As it does not have the data for this new Email, it will then fetch it (it also could have done this in the same request using back-references).

It knows something has changed about “Ma783e5cdf5f2deffbc97930a”, so it will refetch the Mailbox ids and keywords (the only mutable properties) for this Email too.

The user starts composing a new Email. The email is plaintext and the client knows the email in in English so adds this metadata to the body part. The user saves a draft while the composition is still in progress. The client sends:

[[ "Email/set", {
  "accountId": "ue150411c",
  "create": {
    "k192": {
      "mailboxIds": {
        "2ea1ca41b38e": true
      },
      "keywords": {
        "$seen": true,
        "$draft": true
      },
      "from": [{
        "name": "Joe Bloggs",
        "email": "joe@example.com"
      }],
      "subject": "World domination",
      "receivedAt": "2018-07-10T01:03:11Z",
      "sentAt": "2018-07-10T11:03:11+10:00",
      "bodyStructure": {
        "type": "text/plain",
        "partId": "bd48",
        "header:Content-Language": "en"
      },
      "bodyValues": {
        "bd48": {
          "value": "I have the most brilliant plan. Let me tell you
            all about it. What we do is, we",
          "isTruncated": false
        }
      }
    }
  }
}, "0" ]]

The server creates the message and sends the success response:

[[ "Email/set", {
  "accountId": "ue150411c",
  "oldState": "780823",
  "newState": "780839",
  "created": {
    "k192": {
      "id": "Mf40b5f831efa7233b9eb1c7f",
      "blobId": "Gf40b5f831efa7233b9eb1c7f8f97d84eeeee64f7",
      "threadId": "Td957e72e89f516dc",
      "size": 359
    }
  },
  ...
}, "0" ]]

The message created on the server looks something like this:

Message-Id: <bbce0ae9-58be-4b24-ac82-deb840d58016@sloti7d1t02>
User-Agent: Cyrus-JMAP/3.1.6-736-gdfb8e44
Mime-Version: 1.0
Date: Tue, 10 Jul 2018 11:03:11 +1000
From: "Joe Bloggs" <joe@example.com>
Subject: World domination
Content-Language: en
Content-Type: text/plain

I have the most brilliant plan. Let me tell you all about it. What we do
is, we

The user adds a recipient and converts the message to HTML so they can add formatting, then saves an updated draft:

[[ "Email/set", {
  "accountId": "ue150411c",
  "create": {
    "k1546": {
      "mailboxIds": {
        "2ea1ca41b38e": true
      },
      "keywords": {
        "$seen": true,
        "$draft": true
      },
      "from": [{
        "name": "Joe Bloggs",
        "email": "joe@example.com"
      }],
      "to": [{
        "name": "John",
        "email": "john@example.com"
      }],
      "subject": "World domination",
      "receivedAt": "2018-07-10T01:05:08Z",
      "sentAt": "2018-07-10T11:05:08+10:00",
      "bodyStructure": {
        "type": "multipart/alternative",
        "subParts": [{
          "partId": "a49d",
          "type": "text/html",
          "header:Content-Language": "en"
        }, {
          "partId": "bd48",
          "type": "text/plain",
          "header:Content-Language": "en"
        }]
      },
      "bodyValues": {
        "bd48": {
          "value": "I have the most brilliant plan. Let me tell you
            all about it. What we do is, we",
          "isTruncated": false
        },
        "a49d": {
          "value": "<!DOCTYPE html><html><head><title></title>
            <style type=\"text/css\">div{font-size:16px}</style></head>
            <body><div>I have the most <b>brilliant</b> plan. Let me
            tell you all about it. What we do is, we</div></body>
            </html>",
          "isTruncated": false
        }
      }
    }
  },
  "destroy": [ "Mf40b5f831efa7233b9eb1c7f" ]
}, "0" ]]

The server creates the new draft, deletes the old one, and sends the success response:

[[ "Email/set", {
  "accountId": "ue150411c",
  "oldState": "780839",
  "newState": "780842",
  "created": {
    "k1546": {
      "id": "Md45b47b4877521042cec0938",
      "blobId": "Ge8de6c9f6de198239b982ea214e0f3a704e4af74",
      "threadId": "Td957e72e89f516dc",
      "size": 11721
    }
  },
  "destroyed": [ "Mf40b5f831efa7233b9eb1c7f" ],
  ...
}, "0" ]]

The client moves this draft to a different account. The only way to do this is via the Email/copy method. It MUST set a new mailboxIds property, since the current value will not be valid Mailbox ids in the destination account:

[[ "Email/copy", {
  "fromAccountId": "ue150411c",
  "accountId": "u6c6c41ac",
  "create": {
    "k45": {
      "id": "Md45b47b4877521042cec0938",
      "mailboxIds": {
        "75a4c956": true
      }
    }
  },
  "onSuccessDestroyOriginal": true
}, "0" ]]

The server successfully copies the Email and deletes the original. Due to the implicit call to “Email/set”, there are two responses to the single method call, both with the same method call id:

[[ "Email/copy", {
  "fromAccountId": "ue150411c",
  "accountId": "u6c6c41ac",
  "oldState": "7ee7e9263a6d",
  "newState": "5a0d2447ed26",
  "created": {
    "k45": {
      "id": "M138f9954a5cd2423daeafa55",
      "blobId": "G6b9fb047cba722c48c611e79233d057c6b0b74e8",
      "threadId": "T2f242ea424a4079a",
      "size": 11721
    }
  },
  "notCreated": null
}, "0" ],
[ "Email/set", {
  "accountId": "ue150411c",
  "oldState": "780842",
  "newState": "780871",
  "destroyed": [ "Md45b47b4877521042cec0938" ],
  ...
}, "0" ]]

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 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:

What is a relevant section of the body for preview is server defined. If the server is unable to determine search snippets, it MUST return null for both the subject and preview properties.

Note that 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:

As the search snippets are derived from the message content and the algorithm for doing so could change over time, fetching the same snippets a second time MAY return a different result. However, the previous value is not considered incorrect, so there is no state string or update mechanism needed.

The following additional errors may be returned instead of the SearchSnippet/get response:

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

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

Example

Here, we did an Email/query to search for any Email in the account containing the word “foo”; now, we are fetching the search snippets for some of the ids that were returned in the results:

[[ "SearchSnippet/get", {
  "accountId": "ue150411c",
  "filter": {
    "text": "foo"
  },
  "emailIds": [
    "M44200ec123de277c0c1ce69c",
    "M7bcbcb0b58d7729686e83d99",
    "M28d12783a0969584b6deaac0",
    ...
  ]
}, "0" ]]

Example response:

[[ "SearchSnippet/get", {
  "accountId": "ue150411c",
  "list": [{
      "emailId": "M44200ec123de277c0c1ce69c",
      "subject": null,
      "preview": null
  }, {
      "emailId": "M7bcbcb0b58d7729686e83d99",
      "subject": "The <mark>Foo</mark>sball competition",
      "preview": "...year the <mark>foo</mark>sball competition will
        be held in the Stadium de ..."
  }, {
      "emailId": "M28d12783a0969584b6deaac0",
      "subject": null,
      "preview": "...the <mark>Foo</mark>/bar method results often
        returns &lt;1 widget rather than the complete..."
  },
  ...
  ],
  "notFound": null
}, "0" ]]

Identities

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

See the “Addresses” header form description in the Email object for the definition of EmailAddress.

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

This is a standard “/get” method as described in [@!RFC8620], Section 5.1. The ids argument may be null to fetch all at once.

Identity/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.

Identity/set

This is a standard “/set” method as described in [@!RFC8620], Section 5.3. The following extra SetError types are defined:

For create:

Example

Request:

[ "Identity/get", {
  "accountId": "acme"
}, "0" ]

with response:

[ "Identity/get", {
  "accountId": "acme",
  "state": "99401312ae-11-333",
  "list": [
    {
      "id": "XD-3301-222-11_22AAz",
      "name": "Joe Bloggs",
      "email": "joe@example.com",
      "replyTo": null,
      "bcc": [{
        "name": null,
        "email": "joe+archive@example.com"
      }],
      "textSignature": "-- \nJoe Bloggs\nMaster of Email",
      "htmlSignature": "<div><b>Joe Bloggs</b></div>
        <div>Master of Email</div>",
      "mayDelete": false
    },
    {
      "id": "XD-9911312-11_22AAz",
      "name": "Joe B",
      "email": "*@example.com",
      "replyTo": null,
      "bcc": null,
      "textSignature": "",
      "htmlSignature": "",
      "mayDelete": true
    }
  ],
  "notFound": []
}, "0" ]

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 an EmailSubmission object. It SHOULD only do this if it exposes them in the dsnBlobIds and mdnblobIds fields instead, and it 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 at any time after the message is successfully sent or after it has finished retrying to send the message. 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

This is a standard “/get” method as described in [@!RFC8620], Section 5.1.

EmailSubmission/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.

EmailSubmission/query

This is a standard “/query” method as described in [@!RFC8620], Section 5.5.

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

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

The following EmailSubmission properties MUST be supported for sorting:

EmailSubmission/queryChanges

This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6.

EmailSubmission/set

This is a standard “/set” method as described in [@!RFC8620], Section 5.3 with the following two additional request arguments:

After all create/update/destroy items in the EmailSubmission/set invocation have been processed, a single implicit Email/set call MUST be made 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 an EmailSubmission object. When processing each create, the server must check that the message is valid, and the user has sufficient authorisation to send it. If the creation succeeds, the message will be sent to the recipients given in the envelope rcptTo parameter. The server MUST remove any Bcc header field present on the message during delivery. The server MAY add or remove other header fields from the submitted message 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 submission (i.e., it does not cancel a future send). The emailId and threadId properties of the EmailSubmission object remain, but trying to fetch them (with a standard Email/get call) will return a notFound error if the corresponding objects have been destroyed.

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

If the message to be sent is larger than the server supports sending, a standard tooLarge SetError MUST be returned. A maxSize UnsignedInt property MUST be present on the SetError specifying the maximum size of an message that may be sent, in octets.

If the Email or Identity id given cannot be found, the submission creation is rejected with a standard invalidProperties SetError.

The following extra SetError types are defined:

For create:

For update:

Example

The following example presumes a draft of the Email to be sent has already been saved, and its Email id is “M7f6ed5bcfd7e2604d1753f6c”. This call then sends the Email immediately, and if successful, removes the $draft flag and moves it from the drafts folder (which has Mailbox id “7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e”) to the sent folder (which we presume has Mailbox id “73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6”).

[[ "EmailSubmission/set", {
  "accountId": "ue411d190",
  "create": {
    "k1490": {
      "identityId": "I64588216",
      "emailId": "M7f6ed5bcfd7e2604d1753f6c",
      "envelope": {
        "mailFrom": {
          "email": "john@example.com",
          "parameters": null
        },
        "rcptTo": [{
          "email": "jane@example.com",
          "parameters": null
        },
        ...
        ]
      }
    }
  },
  "onSuccessUpdateEmail": {
    "#k1490": {
      "mailboxIds/7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e": null,
      "mailboxIds/73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6": true,
      "keywords/$draft": null
    }
  }
}, "0" ]]

A successful response might look like this. Note that there are two responses due to the implicit Email/set call, but both have the same method call id as they are due to the same call in the request:

[[ "EmailSubmission/set", {
  "accountId": "ue411d190",
  "oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
  "newState": "355421f6-8aed-4cf4-a0c4-7377e951af36",
  "created": {
    "k1490": {
      "id": "ES-3bab7f9a-623e-4acf-99a5-2e67facb02a0"
    }
  }
}, "0" ],
[ "Email/set", {
  "accountId": "ue411d190",
  "oldState": "778193",
  "newState": "778197",
  "updated": {
      "M7f6ed5bcfd7e2604d1753f6c": null
  }
}, "0" ]]

Suppose instead an admin has removed sending rights for the user, so the submission is rejected with a “forbiddenToSend” error. The description argument of the error is intended for display to the user, so it should be localised appropriately. Let’s suppose the request was sent with an Accept-Language header like this:

Accept-Language: de;q=0.9,en;q=0.8

The server should attempt to choose the best localisation from those it has available based on the Accept-Language header, as described in [@!RFC8620], Section 3.8. If the server has English, French, and German translations, it would choose German as the preferred language and return a response like this:

[[ "EmailSubmission/set", {
  "accountId": "ue411d190",
  "oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
  "newState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
  "notCreated": {
    "k1490": {
      "type": "forbiddenToSend",
      "description": "Verzeihung, wegen verdächtiger Aktivitäten Ihres Benutzerkontos haben wir den Versand von Nachrichten gesperrt. Bitte wenden Sie sich für Hilfe an unser Support Team."
    }
  }
}, "0" ]]

Vacation Response

A vacation response sends an automatic reply when a message is delivered to the mail store, informing the original sender that their message may not be read for some time.

Automated message sending can produce undesirable behaviour. To avoid this, implementors MUST follow the recommendations set forth in [@!RFC3834].

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

This is a standard “/get” method as described in [@!RFC8620], Section 5.1.

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

VacationResponse/set

This is a standard “/set” method as described in [@!RFC8620], Section 5.3.

Security Considerations

All security considerations of JMAP ([@!RFC8620]) apply to this specification. Additional considerations specific to the data types and functionality introduced by this document are described in the following subsections.

EmailBodyPart Value

Service providers typically perform security filtering on incoming messages, and it’s important that the detection of content-type and charset for the security filter aligns with the heuristics performed by JMAP servers. Servers that apply heuristics to determine the content-type or charset for an EmailBodyValue SHOULD document the heuristics and provide a mechanism to turn them off in the event they are misaligned with the security filter used at a particular mail host.

Automatic conversion of charsets that allow hidden channels for ASCII text, such as UTF-7, have been problematic for security filters in the past, so server implementations can mitigate this risk by having such conversions off-by-default and/or separately configurable.

To allow the client to restrict the volume of data it can receive in response to a request, a maximum length may be requested for the data returned for a textual body part. However, truncating the data may change the semantic meaning, for example, truncating a URL changes its location. Servers that scan for links to malicious sites should take care to either ensure truncation is not at a semantically significant point or rescan the truncated value for malicious content before returning it.

HTML Email Display

HTML message bodies provide richer formatting for messages but present a number of security challenges, especially when embedded in a webmail context in combination with interface HTML. Clients that render HTML messages should carefully consider the potential risks, including:

There are a number of ways clients can mitigate these issues, and a defence-in-depth approach that uses a combination of techniques will provide the strongest security.

As highly complex software components, HTML rendering engines increase the attack surface of a client considerably, especially when being used to process untrusted, potentially malicious content. Serious bugs have been found in image decoders, JavaScript engines, and HTML parsers in the past, which could lead to full system compromise. Clients using an engine should ensure they get the latest version and continue to incorporate any security patches released by the vendor.

Multiple Part Display

Messages may consist of multiple parts to be displayed sequentially as a body. Clients MUST render each part in isolation and MUST NOT concatenate the raw text values to render. Doing so may change the overall semantics of the message. If the client or server is decrypting a Pretty Good Privacy (PGP) or S/MIME encrypted part, concatenating with other parts may leak the decrypted text to an attacker, as described in EFAIL.

Email Submission

SMTP submission servers [@!RFC6409] use a number of mechanisms to mitigate damage caused by compromised user accounts and end-user systems including rate limiting, anti-virus/anti-spam milters (mail filters), and other technologies. The technologies work better when they have more information about the client connection. If JMAP email submission is implemented as a proxy to an SMTP submission server, it is useful to communicate this information from the JMAP proxy to the submission server. The de facto XCLIENT extension to SMTP can be used to do this, but use of an authenticated channel is recommended to limit use of that extension to explicitly authorised proxies.

JMAP servers that proxy to an SMTP submission server SHOULD allow use of the submissions port [@!RFC8314]. Implementation of a mechanism similar to SMTP XCLIENT is strongly encouraged. While Simple Authentication and Security Layer (SASL) PLAIN over TLS [@!RFC4616] is presently the mandatory-to-implement mechanism for interoperability with SMTP submission servers [@!RFC4954], a JMAP submission proxy SHOULD implement and prefer a stronger mechanism for this use case such as TLS client certificate authentication with SASL EXTERNAL ([@!RFC4422], Appendix A) or Salted Challenge Response Authentication Mechanism (SCRAM) [@!RFC7677].

In the event the JMAP server directly relays mail to SMTP servers in other administrative domains, implementation of the de facto milter protocol is strongly encouraged to integrate with third-party products that address security issues including anti-virus/anti-spam, reputation protection, compliance archiving, and data loss prevention. Proxying to a local SMTP submission server may be a simpler way to provide such security services.

Partial Account Access

A user may only have permission to access a subset of the data that exists in an account. To avoid leaking unauthorised information, in such a situation, the server MUST treat any data the user does not have permission to access the same as if it did not exist.

For example, suppose user A has an account with two Mailboxes, inbox and sent, but only shares the inbox with user B. In this case, when user B fetches Mailboxes for this account, the server MUST behave as though the sent Mailbox did not exist. Similarly, when querying or fetching Email objects, it MUST treat any messages that just belong to the sent Mailbox as though they did not exist. Fetching Thread objects MUST only return ids for Email objects the user has permission to access; if none, the Thread again MUST be treated the same as if it did not exist.

If the server forbids a single account from having two identical messages, or two messages with the same Message-Id header field, a user with write access can use the error returned by trying to create/import such a message to detect whether it already exists in an inaccessible portion of the account.

Permission to Send from an Address

In recent years, the email ecosystem has moved towards associating trust with the From address in the message [@!RFC5322], particularly with schemes such as Domain-based Message Authentication, Reporting, and Conformance (DMARC) ([@?RFC7489]).

The set of Identity objects (see Section 6) in an account lets the client know which email addresses the user has permission to send from. Each email submission is associated with an Identity, and servers SHOULD reject submissions where the From header field of the message does not correspond to the associated Identity.

The server MAY allow an exception to send an exact copy of an existing message received into the mail store to another address (otherwise known as “redirecting” or “bouncing”), although it is RECOMMENDED the server limit this to destinations the user has verified they also control.

If the user attempts to create a new Identity object, the server MUST reject it with the appropriate error if the user does not have permission to use that email address to send from.

The SMTP MAIL FROM address [@!RFC5321] is often confused with the From message header field [@!RFC5322]. The user generally only ever sees the address in the message header field, and this is the primary one to enforce. However, the server MUST also enforce appropriate restrictions on the MAIL FROM address [@!RFC5321] to stop the user from flooding a third-party address with bounces and non-delivery notices.

The JMAP submission model provides separate errors for impermissible addresses in either context.

IANA Considerations

JMAP Capability Registration for “mail”

IANA has registered the “mail” JMAP Capability as follows:

Capability Name: urn:ietf:params:jmap:mail

Specification document: this document

Intended use: common

Change Controller: IETF

Security and privacy considerations: this document, Section 9

JMAP Capability Registration for “submission”

IANA has registered the “submission” JMAP Capability as follows:

Capability Name: urn:ietf:params:jmap:submission

Specification document: this document

Intended use: common

Change Controller: IETF

Security and privacy considerations: this document, Section 9

JMAP Capability Registration for “vacationresponse”

IANA has registered the “vacationresponse” JMAP Capability as follows:

Capability Name: urn:ietf:params:jmap:vacationresponse

Specification document: this document

Intended use: common

Change Controller: IETF

Security and privacy considerations: this document, Section 9

IMAP and JMAP Keywords Registry

This document makes two changes to the IMAP keywords registry as defined in [@!RFC5788].

First, the name of the registry is changed to the “IMAP and JMAP Keywords” registry.

Second, a scope column is added to the template and registry indicating whether a keyword applies to “IMAP-only”, “JMAP-only”, “both”, or “reserved”. All keywords already in the IMAP keyword registry have been marked with a scope of “both”. The “reserved” status can be used to prevent future registration of a name that would be confusing if registered. Registration of keywords with scope “reserved” omit most fields in the registration template (see registration of $recent below for an example); such registrations are intended to be infrequent.

IMAP clients MAY silently ignore any keywords marked “JMAP-only” or “reserved” in the event they appear in protocol. JMAP clients MAY silently ignore any keywords marked “IMAP-only” or “reserved” in the event they appear in protocol.

New “JMAP-only” keywords are registered in the following subsections. These keywords correspond to IMAP system keywords and are thus not appropriate for use in IMAP. These keywords cannot be subsequently registered for use in IMAP except via standards action.

Registration of JMAP Keyword ‘$draft’

This registers the “JMAP-only” keyword $draft in the “IMAP and JMAP Keywords” registry.

Keyword name: $draft

Scope: JMAP-only

Purpose (description): This is set when the user wants to treat the message as a draft the user is composing. This is the JMAP equivalent of the IMAP \Draft flag.

Private or Shared on a server: BOTH

Is it an advisory keyword or may it cause an automatic action: Automatic. If the account has an IMAP mailbox marked with the \Drafts special use attribute [RFC6154], setting this flag MAY cause the message to appear in that mailbox automatically. Certain JMAP computed values such as unreadEmails will change as a result of changing this flag. In addition, mail clients will typically present draft messages in a composer window rather than a viewer window.

When/by whom the keyword is set/cleared: This is typically set by a JMAP client when referring to a draft message. One model for draft Emails would result in clearing this flag in an EmailSubmission/set operation with an onSuccessUpdateEmail argument. In a mail store shared by JMAP and IMAP, this is also set and cleared as necessary so it matches the IMAP \Draft flag.

Related keywords: None

Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]

Security Considerations: A server implementing this keyword as a shared keyword may disclose that a user considers the message a draft message. This information would be exposed to other users with read permission for the Mailbox keywords.

Published specification: this document

Person & email address to contact for further information: JMAP mailing list jmap@ietf.org

Intended usage: COMMON

Owner/Change controller: IESG

Registration of JMAP Keyword ‘$seen’

This registers the “JMAP-only” keyword $seen in the “IMAP and JMAP Keywords” registry.

Keyword name: $seen

Scope: JMAP-only

Purpose (description): This is set when the user wants to treat the message as read. This is the JMAP equivalent of the IMAP \Seen flag.

Private or Shared on a server: BOTH

Is it an advisory keyword or may it cause an automatic action: Advisory. However, certain JMAP computed values such as unreadEmails will change as a result of changing this flag.

When/by whom the keyword is set/cleared: This is set by a JMAP client when it presents the message content to the user; clients often offer an option to clear this flag. In a mail store shared by JMAP and IMAP, this is also set and cleared as necessary so it matches the IMAP \Seen flag.

Related keywords: None

Related IMAP/JMAP Capabilities: None

Security Considerations: A server implementing this keyword as a shared keyword may disclose that a user considers the message to have been read. This information would be exposed to other users with read permission for the Mailbox keywords.

Published specification: this document

Person & email address to contact for further information: JMAP mailing list jmap@ietf.org

Intended usage: COMMON

Owner/Change controller: IESG

Registration of JMAP Keyword ‘$flagged’

This registers the “JMAP-only” keyword $flagged in the “IMAP and JMAP Keywords” registry.

Keyword name: $flagged

Scope: JMAP-only

Purpose (description): This is set when the user wants to treat the message as flagged for urgent/special attention. This is the JMAP equivalent of the IMAP \Flagged flag.

Private or Shared on a server: BOTH

Is it an advisory keyword or may it cause an automatic action: Automatic. If the account has an IMAP mailbox marked with the \Flagged special use attribute [RFC6154], setting this flag MAY cause the message to appear in that mailbox automatically.

When/by whom the keyword is set/cleared: JMAP clients typically allow a user to set/clear this flag as desired. In a mail store shared by JMAP and IMAP, this is also set and cleared as necessary so it matches the IMAP \Flagged flag.

Related keywords: None

Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]

Security Considerations: A server implementing this keyword as a shared keyword may disclose that a user considers the message as flagged for urgent/special attention. This information would be exposed to other users with read permission for the Mailbox keywords.

Published specification: this document

Person & email address to contact for further information: JMAP mailing list jmap@ietf.org

Intended usage: COMMON

Owner/Change controller: IESG

Registration of JMAP Keyword ‘$answered’

This registers the “JMAP-only” keyword $answered in the “IMAP and JMAP Keywords” registry.

Keyword name: $answered

Scope: JMAP-only

Purpose (description): This is set when the message has been answered.

Private or Shared on a server: BOTH

Is it an advisory keyword or may it cause an automatic action: Advisory.

When/by whom the keyword is set/cleared: JMAP clients typically set this when submitting a reply or answer to the message. It may be set by the EmailSubmission/set operation with an onSuccessUpdateEmail argument. In a mail store shared by JMAP and IMAP, this is also set and cleared as necessary so it matches the IMAP \Answered flag.

Related keywords: None

Related IMAP/JMAP Capabilities: None

Security Considerations: A server implementing this keyword as a shared keyword may disclose that a user has replied to a message. This information would be exposed to other users with read permission for the Mailbox keywords.

Published specification: this document

Person & email address to contact for further information: JMAP mailing list jmap@ietf.org

Intended usage: COMMON

Owner/Change controller: IESG

Registration of ‘$recent’ Keyword

This registers the keyword $recent in the “IMAP and JMAP Keywords” registry.

Keyword name: $recent

Scope: reserved

Purpose (description): This keyword is not used to avoid confusion with the IMAP \Recent system flag.

Published specification: this document

Person & email address to contact for further information: JMAP mailing list jmap@ietf.org

Owner/Change controller: IESG

IMAP Mailbox Name Attributes Registry

Registration of “inbox” Role

This registers the “JMAP-only” inbox attribute in the “IMAP Mailbox Name Attributes” registry, as established in [@!RFC8457].

Attribute Name: Inbox

Description: New mail is delivered here by default.

Reference: This document, Section 10.5.

Usage Notes: JMAP only

JMAP Error Codes Registry

The following subsections register several new error codes in the “JMAP Error Codes” registry, as defined in [@!RFC8620].

mailboxHasChild

JMAP Error Code: mailboxHasChild

Intended use: common

Change controller: IETF

Reference: This document, Section 2.5

Description: The Mailbox still has at least one child Mailbox. The client MUST remove these before it can delete the parent Mailbox.

mailboxHasEmail

JMAP Error Code: mailboxHasEmail

Intended use: common

Change controller: IETF

Reference: This document, Section 2.5

Description: The Mailbox has at least one message assigned to it and the onDestroyRemoveEmails argument was false.

blobNotFound

JMAP Error Code: blobNotFound

Intended use: common

Change controller: IETF

Reference: This document, Section 4.6

Description: At least one blob id referenced in the object doesn’t exist.

tooManyKeywords

JMAP Error Code: tooManyKeywords

Intended use: common

Change controller: IETF

Reference: This document, Section 4.6

Description: The change to the Email’s keywords would exceed a server-defined maximum.

tooManyMailboxes

JMAP Error Code: tooManyMailboxes

Intended use: common

Change controller: IETF

Reference: This document, Section 4.6

Description: The change to the set of Mailboxes that this Email is in would exceed a server-defined maximum.

invalidEmail

JMAP Error Code: invalidEmail

Intended use: common

Change controller: IETF

Reference: This document, Section 7.5

Description: The Email to be sent is invalid in some way.

tooManyRecipients

JMAP Error Code: tooManyRecipients

Intended use: common

Change controller: IETF

Reference: This document, Section 7.5

Description: The envelope [@!RFC5321] (supplied or generated) has more recipients than the server allows.

noRecipients

JMAP Error Code: noRecipients

Intended use: common

Change controller: IETF

Reference: This document, Section 7.5

Description: The envelope [@!RFC5321] (supplied or generated) does not have any rcptTo email addresses.

invalidRecipients

JMAP Error Code: invalidRecipients

Intended use: common

Change controller: IETF

Reference: This document, Section 7.5

Description: The rcptTo property of the envelope [@!RFC5321] (supplied or generated) contains at least one rcptTo value that is not a valid email address for sending to.

forbiddenMailFrom

JMAP Error Code: forbiddenMailFrom

Intended use: common

Change controller: IETF

Reference: This document, Section 7.5

Description: – The server does not permit the user to send a message with this envelope From address [@!RFC5321].

forbiddenFrom

JMAP Error Code: forbiddenFrom

Intended use: common

Change controller: IETF

Reference: This document, sections 6.3 and 7.5

Description: The server does not permit the user to send a message with the From header field [@!RFC5322] of the message to be sent.

forbiddenToSend

JMAP Error Code: forbiddenToSend

Intended use: common

Change controller: IETF

Reference: This document, Section 7.5

Description: The user does not have permission to send at all right now.