···
+
Internet Engineering Task Force (IETF) N. Jenkins
+
Request for Comments: 8621 Fastmail
+
Updates: 5788 C. Newman
+
Category: Standards Track Oracle
+
ISSN: 2070-1721 August 2019
+
The JSON Meta Application Protocol (JMAP) for Mail
+
This document specifies a data model for synchronising email data
+
with a server using the JSON Meta Application Protocol (JMAP).
+
Clients can use this to efficiently search, access, organise, and
+
send messages, and to get push notifications for fast
+
resynchronisation when new messages are delivered or a change is made
+
This is an Internet Standards Track document.
+
This document is a product of the Internet Engineering Task Force
+
(IETF). It represents the consensus of the IETF community. It has
+
received public review and has been approved for publication by the
+
Internet Engineering Steering Group (IESG). Further information on
+
Internet Standards is available in Section 2 of RFC 7841.
+
Information about the current status of this document, any errata,
+
and how to provide feedback on it may be obtained at
+
https://www.rfc-editor.org/info/rfc8621.
+
Copyright (c) 2019 IETF Trust and the persons identified as the
+
document authors. All rights reserved.
+
This document is subject to BCP 78 and the IETF Trust's Legal
+
Provisions Relating to IETF Documents
+
(https://trustee.ietf.org/license-info) in effect on the date of
+
publication of this document. Please review these documents
+
carefully, as they describe your rights and restrictions with respect
+
to this document. Code Components extracted from this document must
+
include Simplified BSD License text as described in Section 4.e of
+
the Trust Legal Provisions and are provided without warranty as
+
described in the Simplified BSD License.
+
Jenkins & Newman Standards Track [Page 1]
+
RFC 8621 JMAP Mail August 2019
+
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
+
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
+
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
+
1.3. Additions to the Capabilities Object . . . . . . . . . . 5
+
1.3.1. urn:ietf:params:jmap:mail . . . . . . . . . . . . . . 5
+
1.3.2. urn:ietf:params:jmap:submission . . . . . . . . . . . 7
+
1.3.3. urn:ietf:params:jmap:vacationresponse . . . . . . . . 8
+
1.4. Data Type Support in Different Accounts . . . . . . . . . 8
+
1.5. Push . . . . . . . . . . . . . . . . . . . . . . . . . . 8
+
1.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 9
+
1.6. Ids . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
+
2. Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . 9
+
2.1. Mailbox/get . . . . . . . . . . . . . . . . . . . . . . . 14
+
2.2. Mailbox/changes . . . . . . . . . . . . . . . . . . . . . 14
+
2.3. Mailbox/query . . . . . . . . . . . . . . . . . . . . . . 14
+
2.4. Mailbox/queryChanges . . . . . . . . . . . . . . . . . . 15
+
2.5. Mailbox/set . . . . . . . . . . . . . . . . . . . . . . . 16
+
2.6. Example . . . . . . . . . . . . . . . . . . . . . . . . . 17
+
3. Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
+
3.1. Thread/get . . . . . . . . . . . . . . . . . . . . . . . 22
+
3.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 22
+
3.2. Thread/changes . . . . . . . . . . . . . . . . . . . . . 22
+
4. Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
+
4.1. Properties of the Email Object . . . . . . . . . . . . . 23
+
4.1.1. Metadata . . . . . . . . . . . . . . . . . . . . . . 24
+
4.1.2. Header Fields Parsed Forms . . . . . . . . . . . . . 26
+
4.1.3. Header Fields Properties . . . . . . . . . . . . . . 32
+
4.1.4. Body Parts . . . . . . . . . . . . . . . . . . . . . 35
+
4.2. Email/get . . . . . . . . . . . . . . . . . . . . . . . . 42
+
4.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 44
+
4.3. Email/changes . . . . . . . . . . . . . . . . . . . . . . 45
+
4.4. Email/query . . . . . . . . . . . . . . . . . . . . . . . 45
+
4.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 46
+
4.4.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 49
+
4.4.3. Thread Collapsing . . . . . . . . . . . . . . . . . . 50
+
4.5. Email/queryChanges . . . . . . . . . . . . . . . . . . . 51
+
4.6. Email/set . . . . . . . . . . . . . . . . . . . . . . . . 51
+
4.7. Email/copy . . . . . . . . . . . . . . . . . . . . . . . 53
+
4.8. Email/import . . . . . . . . . . . . . . . . . . . . . . 54
+
4.9. Email/parse . . . . . . . . . . . . . . . . . . . . . . . 56
+
4.10. Examples . . . . . . . . . . . . . . . . . . . . . . . . 58
+
5. Search Snippets . . . . . . . . . . . . . . . . . . . . . . . 68
+
5.1. SearchSnippet/get . . . . . . . . . . . . . . . . . . . . 69
+
5.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 71
+
Jenkins & Newman Standards Track [Page 2]
+
RFC 8621 JMAP Mail August 2019
+
6. Identities . . . . . . . . . . . . . . . . . . . . . . . . . 72
+
6.1. Identity/get . . . . . . . . . . . . . . . . . . . . . . 73
+
6.2. Identity/changes . . . . . . . . . . . . . . . . . . . . 73
+
6.3. Identity/set . . . . . . . . . . . . . . . . . . . . . . 73
+
6.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 73
+
7. Email Submission . . . . . . . . . . . . . . . . . . . . . . 74
+
7.1. EmailSubmission/get . . . . . . . . . . . . . . . . . . . 80
+
7.2. EmailSubmission/changes . . . . . . . . . . . . . . . . . 80
+
7.3. EmailSubmission/query . . . . . . . . . . . . . . . . . . 80
+
7.4. EmailSubmission/queryChanges . . . . . . . . . . . . . . 81
+
7.5. EmailSubmission/set . . . . . . . . . . . . . . . . . . . 81
+
7.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 84
+
8. Vacation Response . . . . . . . . . . . . . . . . . . . . . . 86
+
8.1. VacationResponse/get . . . . . . . . . . . . . . . . . . 87
+
8.2. VacationResponse/set . . . . . . . . . . . . . . . . . . 88
+
9. Security Considerations . . . . . . . . . . . . . . . . . . . 88
+
9.1. EmailBodyPart Value . . . . . . . . . . . . . . . . . . . 88
+
9.2. HTML Email Display . . . . . . . . . . . . . . . . . . . 88
+
9.3. Multiple Part Display . . . . . . . . . . . . . . . . . . 91
+
9.4. Email Submission . . . . . . . . . . . . . . . . . . . . 91
+
9.5. Partial Account Access . . . . . . . . . . . . . . . . . 92
+
9.6. Permission to Send from an Address . . . . . . . . . . . 92
+
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 93
+
10.1. JMAP Capability Registration for "mail" . . . . . . . . 93
+
10.2. JMAP Capability Registration for "submission" . . . . . 93
+
10.3. JMAP Capability Registration for "vacationresponse" . . 94
+
10.4. IMAP and JMAP Keywords Registry . . . . . . . . . . . . 94
+
10.4.1. Registration of JMAP Keyword "$draft" . . . . . . . 95
+
10.4.2. Registration of JMAP Keyword "$seen" . . . . . . . . 96
+
10.4.3. Registration of JMAP Keyword "$flagged" . . . . . . 97
+
10.4.4. Registration of JMAP Keyword "$answered" . . . . . . 98
+
10.4.5. Registration of "$recent" Keyword . . . . . . . . . 99
+
10.5. IMAP Mailbox Name Attributes Registry . . . . . . . . . 99
+
10.5.1. Registration of "inbox" Role . . . . . . . . . . . . 99
+
10.6. JMAP Error Codes Registry . . . . . . . . . . . . . . . 100
+
10.6.1. mailboxHasChild . . . . . . . . . . . . . . . . . . 100
+
10.6.2. mailboxHasEmail . . . . . . . . . . . . . . . . . . 100
+
10.6.3. blobNotFound . . . . . . . . . . . . . . . . . . . . 100
+
10.6.4. tooManyKeywords . . . . . . . . . . . . . . . . . . 101
+
10.6.5. tooManyMailboxes . . . . . . . . . . . . . . . . . . 101
+
10.6.6. invalidEmail . . . . . . . . . . . . . . . . . . . . 101
+
10.6.7. tooManyRecipients . . . . . . . . . . . . . . . . . 102
+
10.6.8. noRecipients . . . . . . . . . . . . . . . . . . . . 102
+
10.6.9. invalidRecipients . . . . . . . . . . . . . . . . . 102
+
10.6.10. forbiddenMailFrom . . . . . . . . . . . . . . . . . 103
+
10.6.11. forbiddenFrom . . . . . . . . . . . . . . . . . . . 103
+
10.6.12. forbiddenToSend . . . . . . . . . . . . . . . . . . 103
+
Jenkins & Newman Standards Track [Page 3]
+
RFC 8621 JMAP Mail August 2019
+
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 104
+
11.1. Normative References . . . . . . . . . . . . . . . . . . 104
+
11.2. Informative References . . . . . . . . . . . . . . . . . 107
+
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 108
+
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
+
This specification defines a data model for accessing a mail store
+
over JMAP, allowing you to query, read, organise, and submit mail for
+
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
+
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
+
1.1. 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.
+
Jenkins & Newman Standards Track [Page 4]
+
RFC 8621 JMAP Mail August 2019
+
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
+
Servers MUST support all properties specified for the new data types
+
defined in this document.
+
This document uses the same terminology as in the core JMAP
+
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
+
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.
+
1.3. 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.
+
1.3.1. 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
+
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:
+
o maxMailboxesPerEmail: "UnsignedInt|null"
+
The maximum number of Mailboxes (see Section 2) that can be can
+
assigned to a single Email object (see Section 4). This MUST be
+
an integer >= 1, or null for no limit (or rather, the limit is
+
always the number of Mailboxes in the account).
+
Jenkins & Newman Standards Track [Page 5]
+
RFC 8621 JMAP Mail August 2019
+
o maxMailboxDepth: "UnsignedInt|null"
+
The maximum depth of the Mailbox hierarchy (i.e., one more than
+
the maximum number of ancestors a Mailbox may have), or null for
+
o maxSizeMailboxName: "UnsignedInt"
+
The maximum length, in (UTF-8) octets, allowed for the name of a
+
Mailbox. This MUST be at least 100, although it is recommended
+
o maxSizeAttachmentsPerEmail: "UnsignedInt"
+
The maximum total size of attachments, in octets, allowed for a
+
single Email object. A server MAY still reject the import or
+
creation of an Email with a lower attachment size total (for
+
example, if the body includes several megabytes of text, causing
+
the size of the encoded MIME structure to be over some server-
+
Note that this limit is for the sum of unencoded attachment sizes.
+
Users are generally not knowledgeable about encoding overhead,
+
etc., nor should they need to be, so marketing and help materials
+
normally tell them the "max size attachments". This is the
+
unencoded size they see on their hard drive, so this capability
+
matches that and allows the client to consistently enforce what
+
the user understands as the limit.
+
The server may separately have a limit for the total size of the
+
message [RFC5322], created by combining the attachments (often
+
base64 encoded) with the message headers and bodies. For example,
+
suppose the server advertises "maxSizeAttachmentsPerEmail:
+
50000000" (50 MB). The enforced server limit may be for a message
+
size of 70000000 octets. Even with base64 encoding and a 2 MB
+
HTML body, 50 MB attachments would fit under this limit.
+
o emailQuerySortOptions: "String[]"
+
A list of all the values the server supports for the "property"
+
field of the Comparator object in an "Email/query" sort (see
+
Section 4.4.2). This MAY include properties the client does not
+
recognise (for example, custom properties specified in a vendor
+
extension). Clients MUST ignore any unknown properties in the
+
Jenkins & Newman Standards Track [Page 6]
+
RFC 8621 JMAP Mail August 2019
+
o mayCreateTopLevelMailbox: "Boolean"
+
If true, the user may create a Mailbox (see Section 2) in this
+
account with a null parentId. (Permission for creating a child of
+
an existing Mailbox is given by the "myRights" property on that
+
1.3.2. 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:
+
o maxDelayedSend: "UnsignedInt"
+
The number in seconds of the maximum delay the server supports in
+
sending (see the EmailSubmission object description). This is 0
+
if the server does not support delayed send.
+
o submissionExtensions: "String[String[]]"
+
The set of SMTP submission extensions supported by the server,
+
which the client may use when creating an EmailSubmission object
+
(see Section 7). Each key in the object is the "ehlo-name", and
+
the value is a list of "ehlo-args".
+
A JMAP implementation that talks to a submission server [RFC6409]
+
SHOULD have a configuration setting that allows an administrator
+
to modify the set of submission EHLO capabilities it may expose on
+
this property. This allows a JMAP server to easily add access to
+
a new submission extension without code changes. By default, the
+
JMAP server should hide EHLO capabilities that have to do with the
+
transport mechanism and thus are only relevant to the JMAP server
+
(for example, PIPELINING, CHUNKING, or STARTTLS).
+
Examples of Submission extensions to include:
+
* FUTURERELEASE [RFC4865]
+
Jenkins & Newman Standards Track [Page 7]
+
RFC 8621 JMAP Mail August 2019
+
* MT-PRIORITY [RFC6710]
+
A JMAP server MAY advertise an extension and implement the
+
semantics of that extension locally on the JMAP server even if a
+
submission server used by JMAP doesn't implement it.
+
The full IANA registry of submission extensions can be found at
+
<https://www.iana.org/assignments/mail-parameters>.
+
1.3.3. 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.
+
1.4. 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.
+
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).
+
Jenkins & Newman Standards Track [Page 8]
+
RFC 8621 JMAP Mail August 2019
+
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
+
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.
+
A Mailbox represents a named set of Email objects. This is the
+
primary mechanism for organising messages within an account. It is
+
analogous to a folder or a label in other systems. A Mailbox may
+
perform a certain role in the system; see below for more details.
+
For compatibility with IMAP, an Email MUST belong to one or more
+
Mailboxes. The Email id does not change if the Email changes
+
A *Mailbox* object has the following properties:
+
o id: "Id" (immutable; server-set)
+
User-visible name for the Mailbox, e.g., "Inbox". This MUST be a
+
Net-Unicode string [RFC5198] of at least 1 character in length,
+
subject to the maximum size given in the capability object. There
+
MUST NOT be two sibling Mailboxes with both the same parent and
+
the same name. Servers MAY reject names that violate server
+
policy (e.g., names containing a slash (/) or control characters).
+
Jenkins & Newman Standards Track [Page 9]
+
RFC 8621 JMAP Mail August 2019
+
o parentId: "Id|null" (default: null)
+
The Mailbox id for the parent of this Mailbox, or null if this
+
Mailbox is at the top level. Mailboxes form acyclic graphs
+
(forests) directed by the child-to-parent relationship. There
+
o role: "String|null" (default: null)
+
Identifies Mailboxes that have a particular common purpose (e.g.,
+
the "inbox"), regardless of the "name" property (which may be
+
This value is shared with IMAP (exposed in IMAP via the SPECIAL-
+
USE extension [RFC6154]). However, unlike in IMAP, a Mailbox MUST
+
only have a single role, and there MUST NOT be two Mailboxes in
+
the same account with the same role. Servers providing IMAP
+
access to the same data are encouraged to enforce these extra
+
restrictions in IMAP as well. Otherwise, modifying the IMAP
+
attributes to ensure compliance when exposing the data over JMAP
+
is implementation dependent.
+
The value MUST be one of the Mailbox attribute names listed in the
+
IANA "IMAP Mailbox Name Attributes" registry at
+
<https://www.iana.org/assignments/imap-mailbox-name-attributes/>,
+
as established in [RFC8457], converted to lowercase. New roles
+
may be established here in the future.
+
An account is not required to have Mailboxes with any particular
+
o sortOrder: "UnsignedInt" (default: 0)
+
Defines the sort order of Mailboxes when presented in the client's
+
UI, so it is consistent between devices. The number MUST be an
+
integer in the range 0 <= sortOrder < 2^31.
+
A Mailbox with a lower order should be displayed before a Mailbox
+
with a higher order (that has the same parent) in any Mailbox
+
listing in the client's UI. Mailboxes with equal order SHOULD be
+
sorted in alphabetical order by name. The sorting should take
+
into account locale-specific character order convention.
+
o totalEmails: "UnsignedInt" (server-set)
+
The number of Emails in this Mailbox.
+
Jenkins & Newman Standards Track [Page 10]
+
RFC 8621 JMAP Mail August 2019
+
o unreadEmails: "UnsignedInt" (server-set)
+
The number of Emails in this Mailbox that have neither the "$seen"
+
keyword nor the "$draft" keyword.
+
o totalThreads: "UnsignedInt" (server-set)
+
The number of Threads where at least one Email in the Thread is in
+
o unreadThreads: "UnsignedInt" (server-set)
+
An indication of the number of "unread" Threads in the Mailbox.
+
For compatibility with existing implementations, the way "unread
+
Threads" is determined is not mandated in this document. The
+
simplest solution to implement is simply the number of Threads
+
where at least one Email in the Thread is both in this Mailbox and
+
has neither the "$seen" nor "$draft" keywords.
+
However, a quality implementation will return the number of unread
+
items the user would see if they opened that Mailbox. A Thread is
+
shown as unread if it contains any unread Emails that will be
+
displayed when the Thread is opened. Therefore, "unreadThreads"
+
should be the number of Threads where at least one Email in the
+
Thread has neither the "$seen" nor the "$draft" keyword AND at
+
least one Email in the Thread is in this Mailbox. Note that the
+
unread Email does not need to be the one in this Mailbox. In
+
addition, the trash Mailbox (that is, a Mailbox whose "role" is
+
"trash") requires special treatment:
+
1. Emails that are *only* in the trash (and no other Mailbox) are
+
ignored when calculating the "unreadThreads" count of other
+
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.
+
For example, suppose you have an account where the entire contents
+
is a single Thread 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.
+
Jenkins & Newman Standards Track [Page 11]
+
RFC 8621 JMAP Mail August 2019
+
o myRights: "MailboxRights" (server-set)
+
The set of rights (Access Control Lists (ACLs)) the user has in
+
relation to this Mailbox. These are backwards compatible with
+
IMAP ACLs, as defined in [RFC4314]. A *MailboxRights* object has
+
the following properties:
+
* mayReadItems: "Boolean"
+
If true, the user may use this Mailbox as part of a filter in
+
an "Email/query" call, and the Mailbox may be included in the
+
"mailboxIds" property of Email objects. Email objects may be
+
fetched if they are in *at least one* Mailbox with this
+
permission. If a sub-Mailbox is shared but not the parent
+
Mailbox, this may be false. Corresponds to IMAP ACLs "lr" (if
+
mapping from IMAP, both are required for this to be true).
+
* mayAddItems: "Boolean"
+
The user may add mail to this Mailbox (by either creating a new
+
Email or moving an existing one). Corresponds to IMAP ACL "i".
+
* mayRemoveItems: "Boolean"
+
The user may remove mail from this Mailbox (by either changing
+
the Mailboxes of an Email or destroying the Email).
+
Corresponds to IMAP ACLs "te" (if mapping from IMAP, both are
+
required for this to be true).
+
* maySetSeen: "Boolean"
+
The user may add or remove the "$seen" keyword to/from an
+
Email. If an Email belongs to multiple Mailboxes, the user may
+
only modify "$seen" if they have this permission for *all* of
+
the Mailboxes. Corresponds to IMAP ACL "s".
+
* maySetKeywords: "Boolean"
+
The user may add or remove any keyword other than "$seen" to/
+
from an Email. If an Email belongs to multiple Mailboxes, the
+
user may only modify keywords if they have this permission for
+
*all* of the Mailboxes. Corresponds to IMAP ACL "w".
+
* mayCreateChild: "Boolean"
+
The user may create a Mailbox with this Mailbox as its parent.
+
Corresponds to IMAP ACL "k".
+
Jenkins & Newman Standards Track [Page 12]
+
RFC 8621 JMAP Mail August 2019
+
The user may rename the Mailbox or make it a child of another
+
Mailbox. Corresponds to IMAP ACL "x" (although this covers
+
both rename and delete permissions).
+
The user may delete the Mailbox itself. Corresponds to IMAP
+
ACL "x" (although this covers both rename and delete
+
Messages may be submitted directly to this Mailbox.
+
Corresponds to IMAP ACL "p".
+
o isSubscribed: "Boolean"
+
Has the user indicated they wish to see this Mailbox in their
+
client? This SHOULD default to false for Mailboxes in shared
+
accounts the user has access to and true for any new Mailboxes
+
created by the user themself. This MUST be stored separately per
+
user where multiple users have access to a shared Mailbox.
+
A user may have permission to access a large number of shared
+
accounts, or a shared account with a very large set of Mailboxes,
+
but only be interested in the contents of a few of these. Clients
+
may choose to only display Mailboxes where the "isSubscribed"
+
property is set to true, and offer a separate UI to allow the user
+
to see and subscribe/unsubscribe from the full set of Mailboxes.
+
However, clients MAY choose to ignore this property, either
+
entirely for ease of implementation or just for an account where
+
"isPersonal" is true (indicating it is the user's own rather than
+
This property corresponds to IMAP [RFC3501] mailbox subscriptions.
+
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.
+
Jenkins & Newman Standards Track [Page 13]
+
RFC 8621 JMAP Mail August 2019
+
This is a standard "/get" method as described in [RFC8620],
+
Section 5.1. The "ids" argument may be "null" to fetch all at once.
+
This is a standard "/changes" method as described in [RFC8620],
+
Section 5.2 but with one extra argument to the response:
+
o updatedProperties: "String[]|null"
+
If only the "totalEmails", "unreadEmails", "totalThreads", and/or
+
"unreadThreads" Mailbox properties have changed since the old
+
state, this will be the list of properties that may have changed.
+
If the server is unable to tell if only counts have changed, it
+
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
+
This is a standard "/query" method as described in [RFC8620],
+
Section 5.5 but with the following additional request argument:
+
o sortAsTree: "Boolean" (default: false)
+
If true, when sorting the query results and comparing Mailboxes A
+
* If A is an ancestor of B, it always comes first regardless of
+
the sort comparators. Similarly, if A is descendant of B, then
+
* Otherwise, if A and B do not share a "parentId", find the
+
nearest ancestors of each that do have the same "parentId" and
+
compare the sort properties on those Mailboxes instead.
+
The result of this is that the Mailboxes are sorted as a tree
+
according to the parentId properties, with each set of children
+
with a common parent sorted according to the standard sort
+
Jenkins & Newman Standards Track [Page 14]
+
RFC 8621 JMAP Mail August 2019
+
o filterAsTree: "Boolean" (default: false)
+
If true, a Mailbox is only included in the query if all its
+
ancestors are also included in the query according to the filter.
+
A *FilterCondition* object has the following properties, any of which
+
The Mailbox "parentId" property must match the given value
+
The Mailbox "name" property contains the given string.
+
The Mailbox "role" property must match the given value exactly.
+
o hasAnyRole: "Boolean"
+
If true, a Mailbox matches if it has any non-null value for its
+
o isSubscribed: "Boolean"
+
The "isSubscribed" property of the Mailbox must be identical to
+
the value given to match the condition.
+
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:
+
2.4. Mailbox/queryChanges
+
This is a standard "/queryChanges" method as described in [RFC8620],
+
Jenkins & Newman Standards Track [Page 15]
+
RFC 8621 JMAP Mail August 2019
+
This is a standard "/set" method as described in [RFC8620],
+
Section 5.3 but with the following additional request argument:
+
o onDestroyRemoveEmails: "Boolean" (default: false)
+
If false, any attempt to destroy a Mailbox that still has Emails
+
in it will be rejected with a "mailboxHasEmail" SetError. If
+
true, any Emails that were in the Mailbox will be removed from it,
+
and if in no other Mailboxes, they will be destroyed when the
+
The following extra SetError types are defined:
+
o "mailboxHasChild": The Mailbox still has at least one child
+
Mailbox. The client MUST remove these before it can delete the
+
o "mailboxHasEmail": The Mailbox has at least one Email assigned to
+
it, and the "onDestroyRemoveEmails" argument was false.
+
Jenkins & Newman Standards Track [Page 16]
+
RFC 8621 JMAP Mail August 2019
+
Fetching all Mailboxes in an account:
+
"accountId": "u33084183",
+
"accountId": "u33084183",
+
"id": "MB23cfa8094c0f41e6",
+
"maySetKeywords": true,
+
"mayRemoveItems": true,
+
"mayCreateChild": true,
+
"id": "MB674cc24095db49ce",
+
"name": "Important mail",
+
Jenkins & Newman Standards Track [Page 17]
+
RFC 8621 JMAP Mail August 2019
+
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
+
[[ "Mailbox/changes", {
+
"accountId": "u33084183",
+
"accountId": "u33084183",
+
"name": "Mailbox/changes",
+
"accountId": "u33084183",
+
"name": "Mailbox/changes",
+
"name": "Mailbox/changes",
+
"path": "/updatedProperties"
+
Jenkins & Newman Standards Track [Page 18]
+
RFC 8621 JMAP Mail August 2019
+
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
+
[[ "Mailbox/changes", {
+
"accountId": "u33084183",
+
"hasMoreChanges": false,
+
"totalEmails", "unreadEmails",
+
"totalThreads", "unreadThreads"
+
"updated": ["MB23cfa8094c0f41e6"],
+
"accountId": "u33084183",
+
"accountId": "u33084183",
+
"id": "MB23cfa8094c0f41e6",
+
Jenkins & Newman Standards Track [Page 19]
+
RFC 8621 JMAP Mail August 2019
+
Here's an example where we try to rename one Mailbox and destroy
+
"accountId": "u33084183",
+
"MB674cc24095db49ce": {
+
"name": "Maybe important mail"
+
"destroy": [ "MB23cfa8094c0f41e6" ]
+
Suppose the rename succeeds, but we don't have permission to destroy
+
the Mailbox we tried to destroy; we might get back:
+
"accountId": "u33084183",
+
"MB674cc24095db49ce": null
+
"MB23cfa8094c0f41e6": {
+
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
+
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.
+
Jenkins & Newman Standards Track [Page 20]
+
RFC 8621 JMAP Mail August 2019
+
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
+
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:
+
o id: "Id" (immutable; server-set)
+
o emailIds: "Id[]" (server-set)
+
The ids of the Emails in the Thread, sorted by the "receivedAt"
+
date of the Email, oldest first. If two Emails have an identical
+
date, the sort is server dependent but MUST be stable (sorting by
+
The following JMAP methods are supported.
+
Jenkins & Newman Standards Track [Page 21]
+
RFC 8621 JMAP Mail August 2019
+
This is a standard "/get" method as described in [RFC8620],
+
"ids": ["f123u4", "f41u44"]
+
"emailIds": [ "eaa623", "f782cbb"]
+
"emailIds": [ "82cf7bb" ]
+
This is a standard "/changes" method as described in [RFC8620],
+
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.
+
Jenkins & Newman Standards Track [Page 22]
+
RFC 8621 JMAP Mail August 2019
+
4.1. 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
+
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:
+
o "textBody"/"htmlBody": These provide a list of parts that should
+
be rendered sequentially as the "body" of the message. This is a
+
list rather than a single part as messages may have headers and/or
+
footers appended/prepended as separate parts when they are
+
transmitted, and some clients send text and images intended to be
+
displayed inline in the body (or even videos and sound clips) as
+
multiple parts rather than a single HTML part with referenced
+
Because MIME allows for multiple representations of the same data
+
(using "multipart/alternative"), there is a "textBody" property
+
(which prefers a plaintext representation) and an "htmlBody"
+
property (which prefers an HTML representation) to accommodate the
+
two most common client requirements. The same part may appear in
+
both lists where there is no alternative between the two.
+
o "attachments": This provides a list of parts that should be
+
presented as "attachments" to the message. Some images may be
+
solely there for embedding within an HTML body part; clients may
+
wish to not present these as attachments in the user interface if
+
they are displaying the HTML with the embedded images directly.
+
Some parts may also be in htmlBody/textBody; again, clients may
+
wish to not present these as attachments in the user interface if
+
rendered as part of the body.
+
Jenkins & Newman Standards Track [Page 23]
+
RFC 8621 JMAP Mail August 2019
+
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.
+
These properties represent metadata about the message in the mail
+
store and are not derived from parsing the message itself.
+
o id: "Id" (immutable; server-set)
+
The id of the Email object. Note that this is the JMAP object id,
+
NOT the Message-ID header field value of the message [RFC5322].
+
o blobId: "Id" (immutable; server-set)
+
The id representing the raw octets of the message [RFC5322] for
+
this Email. This may be used to download the raw original message
+
or to attach it directly to another Email, etc.
+
o threadId: "Id" (immutable; server-set)
+
The id of the Thread to which this Email belongs.
+
o mailboxIds: "Id[Boolean]"
+
The set of Mailbox ids this Email belongs to. An Email in the
+
mail store MUST belong to one or more Mailboxes at all times
+
(until it is destroyed). The set is represented as an object,
+
with each key being a Mailbox id. The value for each key in the
+
Jenkins & Newman Standards Track [Page 24]
+
RFC 8621 JMAP Mail August 2019
+
o keywords: "String[Boolean]" (default: {})
+
A set of keywords that apply to the Email. The set is represented
+
as an object, with the keys being the keywords. The value for
+
each key in the object MUST be true.
+
Keywords are shared with IMAP. The six system keywords from IMAP
+
get special treatment. The following four keywords have their
+
first character changed from "\" in IMAP to "$" in JMAP and have
+
particular semantic meaning:
+
* "$draft": The Email is a draft the user is composing.
+
* "$seen": The Email has been read.
+
* "$flagged": The Email has been flagged for urgent/special
+
* "$answered": The Email has been replied to.
+
The IMAP "\Recent" keyword is not exposed via JMAP. The IMAP
+
"\Deleted" keyword is also not present: IMAP uses a delete+expunge
+
model, which JMAP does not. Any message with the "\Deleted"
+
keyword MUST NOT be visible via JMAP (and so are not counted in
+
the "totalEmails", "unreadEmails", "totalThreads", and
+
"unreadThreads" Mailbox properties).
+
Users may add arbitrary keywords to an Email. For compatibility
+
with IMAP, a keyword is a case-insensitive string of 1-255
+
characters in the ASCII subset %x21-%x7e (excludes control chars
+
and space), and it MUST NOT include any of these characters:
+
Because JSON is case sensitive, servers MUST return keywords in
+
The IANA "IMAP and JMAP Keywords" registry at
+
<https://www.iana.org/assignments/imap-jmap-keywords/> as
+
established in [RFC5788] assigns semantic meaning to some other
+
keywords in common use. New keywords may be established here in
+
the future. In particular, note:
+
* "$forwarded": The Email has been forwarded.
+
* "$phishing": The Email is highly likely to be phishing.
+
Clients SHOULD warn users to take care when viewing this Email
+
and disable links and attachments.
+
Jenkins & Newman Standards Track [Page 25]
+
RFC 8621 JMAP Mail August 2019
+
* "$junk": The Email is definitely spam. Clients SHOULD set this
+
flag when users report spam to help train automated spam-
+
* "$notjunk": The Email is definitely not spam. Clients SHOULD
+
set this flag when users indicate an Email is legitimate, to
+
help train automated spam-detection systems.
+
o size: "UnsignedInt" (immutable; server-set)
+
The size, in octets, of the raw data for the message [RFC5322] (as
+
referenced by the "blobId", i.e., the number of octets in the file
+
the user would download).
+
o receivedAt: "UTCDate" (immutable; default: time of creation on
+
The date the Email was received by the message store. This is the
+
"internal date" in IMAP [RFC3501].
+
4.1.2. 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.
+
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
+
This form will typically have a leading space, as most generated
+
messages insert a space after the colon that terminates the header
+
Jenkins & Newman Standards Track [Page 26]
+
RFC 8621 JMAP Mail August 2019
+
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)
+
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:
+
o Any header field not defined in [RFC5322] or [RFC2369]
+
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.
+
Jenkins & Newman Standards Track [Page 27]
+
RFC 8621 JMAP Mail August 2019
+
An *EmailAddress* object has the following properties:
+
The "display-name" of the "mailbox" [RFC5322]. If this is a
+
1. The surrounding DQUOTE characters are removed.
+
2. Any "quoted-pair" is decoded.
+
3. White space is unfolded, and then any leading and trailing
+
white space is removed.
+
If there is no "display-name" but there is a "comment" immediately
+
following the "addr-spec", the value of this SHOULD be used
+
instead. Otherwise, this property is null.
+
The "addr-spec" of the "mailbox" [RFC5322].
+
Any syntactically correct encoded sections [RFC2047] with a known
+
encoding MUST be decoded, following the same rules as for the Text
+
form (see Section 4.1.2.2).
+
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?=
+
{ "name": "James Smythe", "email": "james@example.com" },
+
{ "name": null, "email": "jane@example.com" },
+
{ "name": "John Smith", "email": "john@example.com" }
+
Jenkins & Newman Standards Track [Page 28]
+
RFC 8621 JMAP Mail August 2019
+
To prevent obviously nonsense behaviour, which can lead to
+
interoperability issues, this form may only be fetched or set for the
+
following header fields:
+
o Any header field not defined in [RFC5322] or [RFC2369]
+
4.1.2.4. 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
+
Jenkins & Newman Standards Track [Page 29]
+
RFC 8621 JMAP Mail August 2019
+
An *EmailAddressGroup* object has the following properties:
+
The "display-name" of the "group" [RFC5322], or null if the
+
addresses are not part of a group. If this is a "quoted-string",
+
it is processed the same as the "name" in the EmailAddress type.
+
o addresses: "EmailAddress[]"
+
The "mailbox" values that belong to this group, represented as
+
Any syntactically correct encoded sections [RFC2047] with a known
+
encoding MUST be decoded, following the same rules as for the Text
+
form (see Section 4.1.2.2).
+
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?=
+
{ "name": null, "addresses": [
+
{ "name": "James Smythe", "email": "james@example.com" }
+
{ "name": "Friends", "addresses": [
+
{ "name": null, "email": "jane@example.com" },
+
{ "name": "John Smith", "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 (see Section 4.1.2.3).
+
Jenkins & Newman Standards Track [Page 30]
+
RFC 8621 JMAP Mail August 2019
+
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:
+
o Any header field not defined in [RFC5322] or [RFC2369]
+
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
+
To prevent obviously nonsense behaviour, which can lead to
+
interoperability issues, this form may only be fetched or set for the
+
following header fields:
+
o Any header field not defined in [RFC5322] or [RFC2369]
+
Jenkins & Newman Standards Track [Page 31]
+
RFC 8621 JMAP Mail August 2019
+
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 field 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:
+
o Any header field not defined in [RFC5322] or [RFC2369]
+
4.1.3. Header Fields Properties
+
The following low-level Email property is specified for complete
+
access to the header data of the message:
+
o headers: "EmailHeader[]" (immutable)
+
This is a list of all header fields [RFC5322], in the same order
+
they appear in the message. An *EmailHeader* object has the
+
The header "field name" as defined in [RFC5322], with the same
+
capitalization that it has in the message.
+
The header "field value" as defined in [RFC5322], in Raw form.
+
Jenkins & Newman Standards Track [Page 32]
+
RFC 8621 JMAP Mail August 2019
+
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:
+
This means the value is in a parsed form, where "{header-form}" is
+
one of the parsed-form names specified above. If not given, the
+
This means the value is an array, with the items corresponding to
+
each instance of the header field, in the order they appear in the
+
message. If this suffix is not used, the result is the value of
+
the *last* instance of the header field (i.e., identical to the
+
last item in the array if :all is used), or null if none.
+
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
+
2. For each instance, parse the header field value in the Addresses
+
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.
+
Jenkins & Newman Standards Track [Page 33]
+
RFC 8621 JMAP Mail August 2019
+
The following convenience properties are also specified for the Email
+
o messageId: "String[]|null" (immutable)
+
The value is identical to the value of "header:Message-
+
ID:asMessageIds". For messages conforming to RFC 5322, this will
+
be an array with a single entry.
+
o inReplyTo: "String[]|null" (immutable)
+
The value is identical to the value of "header:In-Reply-
+
o references: "String[]|null" (immutable)
+
The value is identical to the value of
+
"header:References:asMessageIds".
+
o sender: "EmailAddress[]|null" (immutable)
+
The value is identical to the value of
+
"header:Sender:asAddresses".
+
o from: "EmailAddress[]|null" (immutable)
+
The value is identical to the value of "header:From:asAddresses".
+
o to: "EmailAddress[]|null" (immutable)
+
The value is identical to the value of "header:To:asAddresses".
+
o cc: "EmailAddress[]|null" (immutable)
+
The value is identical to the value of "header:Cc:asAddresses".
+
o bcc: "EmailAddress[]|null" (immutable)
+
The value is identical to the value of "header:Bcc:asAddresses".
+
o replyTo: "EmailAddress[]|null" (immutable)
+
The value is identical to the value of "header:Reply-
+
o subject: "String|null" (immutable)
+
The value is identical to the value of "header:Subject:asText".
+
Jenkins & Newman Standards Track [Page 34]
+
RFC 8621 JMAP Mail August 2019
+
o sentAt: "Date|null" (immutable; default on creation: current
+
The value is identical to the value of "header:Date:asDate".
+
These properties are derived from the message body [RFC5322] and its
+
MIME entities [RFC2045].
+
An *EmailBodyPart* object has the following properties:
+
o partId: "String|null"
+
Identifies this part uniquely within the Email. This is scoped to
+
the "emailId" and has no meaning outside of the JMAP Email object
+
representation. This is null if, and only if, the part is of type
+
The id representing the raw octets of the contents of the part,
+
after decoding any known Content-Transfer-Encoding (as defined in
+
[RFC2045]), or null if, and only if, the part is of type
+
"multipart/*". Note that two parts may be transfer-encoded
+
differently but have the same blob id if their decoded octets are
+
identical and the server is using a secure hash of the data for
+
the blob id. If the transfer encoding is unknown, it is treated
+
as though it had no transfer encoding.
+
The size, in octets, of the raw data after content transfer
+
decoding (as referenced by the "blobId", i.e., the number of
+
octets in the file the user would download).
+
o headers: "EmailHeader[]"
+
This is a list of all header fields in the part, in the order they
+
appear in the message. The values are in Raw form.
+
This is the decoded "filename" parameter of the Content-
+
Disposition header field per [RFC2231], or (for compatibility with
+
existing systems) if not present, then it's the decoded "name"
+
parameter of the Content-Type header field per [RFC2047].
+
Jenkins & Newman Standards Track [Page 35]
+
RFC 8621 JMAP Mail August 2019
+
The value of the Content-Type header field of the part, if
+
present; otherwise, the implicit type as per the MIME standard
+
("text/plain" or "message/rfc822" if inside a "multipart/digest").
+
CFWS is removed and any parameters are stripped.
+
o charset: "String|null"
+
The value of the charset parameter of the Content-Type header
+
field, if present, or null if the header field is present but not
+
of type "text/*". If there is no Content-Type header field, or it
+
exists and is of type "text/*" but has no charset parameter, this
+
is the implicit charset as per the MIME standard: "us-ascii".
+
o disposition: "String|null"
+
The value of the Content-Disposition header field of the part, if
+
present; otherwise, it's null. CFWS is removed and any parameters
+
The value of the Content-Id header field of the part, if present;
+
otherwise, it's null. CFWS and surrounding angle brackets ("<>")
+
are removed. This may be used to reference the content from
+
within a "text/html" body part [HTML] using the "cid:" protocol,
+
as defined in [RFC2392].
+
o language: "String[]|null"
+
The list of language tags, as defined in [RFC3282], in the
+
Content-Language header field of the part, if present.
+
o location: "String|null"
+
The URI, as defined in [RFC2557], in the Content-Location header
+
field of the part, if present.
+
o subParts: "EmailBodyPart[]|null"
+
If the type is "multipart/*", this contains the body parts of each
+
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".
+
Jenkins & Newman Standards Track [Page 36]
+
RFC 8621 JMAP Mail August 2019
+
The following Email properties are specified for access to the body
+
o bodyStructure: "EmailBodyPart" (immutable)
+
This is the full MIME structure of the message body, without
+
recursing into "message/rfc822" or "message/global" parts. Note
+
that EmailBodyParts may have subParts if they are of type
+
o bodyValues: "String[EmailBodyValue]" (immutable)
+
This is a map of "partId" to an EmailBodyValue object for none,
+
some, or all "text/*" parts. Which parts are included and whether
+
the value is truncated is determined by various arguments to
+
"Email/get" and "Email/parse". An *EmailBodyValue* object has the
+
The value of the body part after decoding Content-Transfer-
+
Encoding and the Content-Type charset, if both known to the
+
server, and with any CRLF replaced with a single LF. The
+
server MAY use heuristics to determine the charset to use for
+
decoding if the charset is unknown, no charset is given, or it
+
believes the charset given is incorrect. Decoding is best
+
effort; the server SHOULD insert the unicode replacement
+
character (U+FFFD) and continue when a malformed section is
+
Note that due to the charset decoding and line ending
+
normalisation, the length of this string will probably not be
+
exactly the same as the "size" property on the corresponding
+
* isEncodingProblem: "Boolean" (default: false)
+
This is true if malformed sections were found while decoding
+
the charset, the charset was unknown, or the content-transfer-
+
* isTruncated: "Boolean" (default: false)
+
This is true if the "value" has been truncated.
+
See the Security Considerations section for issues related to
+
truncation and heuristic determination of the content-type and
+
Jenkins & Newman Standards Track [Page 37]
+
RFC 8621 JMAP Mail August 2019
+
o textBody: "EmailBodyPart[]" (immutable)
+
A list of "text/plain", "text/html", "image/*", "audio/*", and/or
+
"video/*" parts to display (sequentially) as the message body,
+
with a preference for "text/plain" when alternative versions are
+
o htmlBody: "EmailBodyPart[]" (immutable)
+
A list of "text/plain", "text/html", "image/*", "audio/*", and/or
+
"video/*" parts to display (sequentially) as the message body,
+
with a preference for "text/html" when alternative versions are
+
o attachments: "EmailBodyPart[]" (immutable)
+
A list, traversing depth-first, of all parts in "bodyStructure"
+
that satisfy either of the following conditions:
+
* not of type "multipart/*" and not included in "textBody" or
+
* of type "image/*", "audio/*", or "video/*" and not in both
+
"textBody" and "htmlBody"
+
None of these parts include subParts, including "message/*" types.
+
Attached messages may be fetched using the "Email/parse" method
+
Note that a "text/html" body part [HTML] may reference image parts
+
in attachments by using "cid:" links to reference the Content-Id,
+
as defined in [RFC2392], or by referencing the Content-Location.
+
o hasAttachment: "Boolean" (immutable; server-set)
+
This is true if there are one or more parts in the message that a
+
client UI should offer as downloadable. A server SHOULD set
+
hasAttachment to true if the "attachments" list contains at least
+
one item that does not have "Content-Disposition: inline". The
+
server MAY ignore parts in this list that are processed
+
automatically in some way or are referenced as embedded images in
+
one of the "text/html" parts of the message.
+
The server MAY set hasAttachment based on implementation-defined
+
or site-configurable heuristics.
+
Jenkins & Newman Standards Track [Page 38]
+
RFC 8621 JMAP Mail August 2019
+
o preview: "String" (immutable; server-set)
+
A plaintext fragment of the message body. This is intended to be
+
shown as a preview line when listing messages in the mail store
+
and may be truncated when shown. The server may choose which part
+
of the message to include in the preview; skipping quoted sections
+
and salutations and collapsing white space can result in a more
+
This MUST NOT be more than 256 characters in length.
+
As this is derived from the message content by the server, and the
+
algorithm for doing so could change over time, fetching this for
+
an Email a second time MAY return a different result. However,
+
the previous value is not considered incorrect, and the change
+
SHOULD NOT cause the Email object to be considered as changed by
+
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 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 ) ) &&
+
Jenkins & Newman Standards Track [Page 39]
+
RFC 8621 JMAP Mail August 2019
+
// 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
+
( multipartType != "related" &&
+
( isInlineMediaType( part.type ) || !part.name ) ) );
+
let subMultiType = part.type.split( '/' )[1];
+
parseStructure( part.subParts, subMultiType,
+
inAlternative || ( subMultiType == 'alternative' ),
+
htmlBody, textBody, attachments );
+
} else if ( isInline ) {
+
if ( multipartType == 'alternative' ) {
+
attachments.push( part );
+
} else if ( inAlternative ) {
+
if ( part.type == 'text/plain' ) {
+
if ( part.type == 'text/html' ) {
+
if ( ( !textBody || !htmlBody ) &&
+
isInlineMediaType( part.type ) ) {
+
attachments.push( part );
+
attachments.push( part );
+
Jenkins & Newman Standards Track [Page 40]
+
RFC 8621 JMAP Mail August 2019
+
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] );
+
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:
+
text/plain, content-disposition=inline - A
+
text/plain, content-disposition=inline - B
+
image/jpeg, content-disposition=inline - C
+
text/plain, content-disposition=inline - D
+
image/jpeg, content-disposition=attachment - G
+
application/x-excel - H
+
text/plain, content-disposition=inline - K
+
Jenkins & Newman Standards Track [Page 41]
+
RFC 8621 JMAP Mail August 2019
+
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 ]
+
This is a standard "/get" method as described in [RFC8620],
+
Section 5.1 with the following additional request arguments:
+
o bodyProperties: "String[]"
+
A list of properties to fetch for each EmailBodyPart returned. If
+
omitted, this defaults to:
+
[ "partId", "blobId", "size", "name", "type", "charset",
+
"disposition", "cid", "language", "location" ]
+
o fetchTextBodyValues: "Boolean" (default: false)
+
If true, the "bodyValues" property includes any "text/*" part in
+
the "textBody" property.
+
o fetchHTMLBodyValues: "Boolean" (default: false)
+
If true, the "bodyValues" property includes any "text/*" part in
+
the "htmlBody" property.
+
o fetchAllBodyValues: "Boolean" (default: false)
+
If true, the "bodyValues" property includes any "text/*" part in
+
the "bodyStructure" property.
+
o maxBodyValueBytes: "UnsignedInt" (default: 0)
+
If greater than zero, the "value" property of any EmailBodyValue
+
object returned in "bodyValues" MUST be truncated if necessary so
+
it does not exceed this number of octets in size. If 0 (the
+
default), no truncation occurs.
+
The server MUST ensure the truncation results in valid UTF-8 and
+
does not occur mid-codepoint. If the part is of type "text/html",
+
the server SHOULD NOT truncate inside an HTML tag, e.g., in the
+
middle of "<a href="https://example.com">". There is no
+
requirement for the truncated form to be a balanced tree or valid
+
HTML (indeed, the original source may well be neither of these
+
Jenkins & Newman Standards Track [Page 42]
+
RFC 8621 JMAP Mail August 2019
+
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:
+
Jenkins & Newman Standards Track [Page 43]
+
RFC 8621 JMAP Mail August 2019
+
Clients SHOULD take care when fetching any other properties, as there
+
may be significantly longer latency in fetching and returning the
+
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.
+
"ids": [ "f123u456", "f123u457" ],
+
"properties": [ "threadId", "mailboxIds", "from", "subject",
+
"receivedAt", "header:List-POST:asURLs",
+
"htmlBody", "bodyValues" ],
+
"bodyProperties": [ "partId", "blobId", "size", "type" ],
+
"fetchHTMLBodyValues": true,
+
"maxBodyValueBytes": 256
+
"state": "41234123231",
+
"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"
+
"blobId": "B841623871",
+
Jenkins & Newman Standards Track [Page 44]
+
RFC 8621 JMAP Mail August 2019
+
"blobId": "B319437193",
+
"isEncodingProblem": false,
+
"value": "<html><body><p>Hello ..."
+
"isEncodingProblem": false,
+
"value": "-- Sent by your friendly mailing list ..."
+
"notFound": [ "f123u456" ]
+
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.
+
This is a standard "/query" method as described in [RFC8620],
+
Section 5.5 but with the following additional request arguments:
+
o collapseThreads: "Boolean" (default: false)
+
If true, Emails in the same Thread as a previous Email in the list
+
(given the filter and sort order) will be removed from the list.
+
This means only one Email at most will be included in the list for
+
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.
+
Jenkins & Newman Standards Track [Page 45]
+
RFC 8621 JMAP Mail August 2019
+
A *FilterCondition* object has the following properties, any of which
+
A Mailbox id. An Email must be in this Mailbox to match the
+
o inMailboxOtherThan: "Id[]"
+
A list of Mailbox ids. An Email must be in at least one Mailbox
+
not in this list to match the condition. This is to allow
+
messages solely in trash/spam to be easily excluded from a search.
+
The "receivedAt" date-time of the Email must be before this date-
+
time to match the condition.
+
The "receivedAt" date-time of the Email must be the same or after
+
this date-time to match the condition.
+
o minSize: "UnsignedInt"
+
The "size" property of the Email must be equal to or greater than
+
this number to match the condition.
+
o maxSize: "UnsignedInt"
+
The "size" property of the Email must be less than this number to
+
o allInThreadHaveKeyword: "String"
+
All Emails (including this one) in the same Thread as this Email
+
must have the given keyword to match the condition.
+
o someInThreadHaveKeyword: "String"
+
At least one Email (possibly this one) in the same Thread as this
+
Email must have the given keyword to match the condition.
+
Jenkins & Newman Standards Track [Page 46]
+
RFC 8621 JMAP Mail August 2019
+
o noneInThreadHaveKeyword: "String"
+
All Emails (including this one) in the same Thread as this Email
+
must *not* have the given keyword to match the condition.
+
This Email must have the given keyword to match the condition.
+
This Email must not have the given keyword to match the condition.
+
o hasAttachment: "Boolean"
+
The "hasAttachment" property of the Email must be identical to the
+
value given to match the condition.
+
Looks for the text in Emails. The server MUST look up text in the
+
From, To, Cc, Bcc, and Subject header fields of the message and
+
SHOULD look inside any "text/*" or other body parts that may be
+
converted to text by the server. The server MAY extend the search
+
to any additional textual property.
+
Looks for the text in the From header field of the message.
+
Looks for the text in the To header field of the message.
+
Looks for the text in the Cc header field of the message.
+
Looks for the text in the Bcc header field of the message.
+
Looks for the text in the Subject header field of the message.
+
Jenkins & Newman Standards Track [Page 47]
+
RFC 8621 JMAP Mail August 2019
+
Looks for the text in one of the body parts of the message. The
+
server MAY exclude MIME body parts with content media types other
+
than "text/*" and "message/*" from consideration in search
+
matching. Care should be taken to match based on the text content
+
actually presented to an end user by viewers for that media type
+
or otherwise identified as appropriate for search indexing.
+
Matching document metadata uninteresting to an end user (e.g.,
+
markup tag and attribute names) is undesirable.
+
The array MUST contain either one or two elements. The first
+
element is the name of the header field to match against. The
+
second (optional) element is the text to look for in the header
+
field value. If not supplied, the message matches simply if it
+
has a header field of the given name.
+
If zero properties are specified on the FilterCondition, the
+
condition MUST always evaluate to true. If multiple properties are
+
specified, ALL must apply for the condition to be true (it is
+
equivalent to splitting the object into one-property conditions and
+
making them all the child of an AND filter operator).
+
The exact semantics for matching "String" fields is *deliberately not
+
defined* to allow for flexibility in indexing implementation, subject
+
o Any syntactically correct encoded sections [RFC2047] of header
+
fields with a known encoding SHOULD be decoded before attempting
+
o When searching inside a "text/html" body part, any text considered
+
markup rather than content SHOULD be ignored, including HTML tags
+
and most attributes, anything inside the "<head>" tag, Cascading
+
Style Sheets (CSS), and JavaScript. Attribute content intended
+
for presentation to the user such as "alt" and "title" SHOULD be
+
considered in the search.
+
o Text SHOULD be matched in a case-insensitive manner.
+
o Text contained in either (but matched) single (') or double (")
+
quotes SHOULD be treated as a *phrase search*; that is, a match is
+
required for that exact word or sequence of words, excluding the
+
surrounding quotation marks.
+
Jenkins & Newman Standards Track [Page 48]
+
RFC 8621 JMAP Mail August 2019
+
Within a phrase, to match one of the following characters you MUST
+
escape it by prefixing it with a backslash (\):
+
o Outside of a phrase, white space SHOULD be treated as dividing
+
separate tokens that may be searched for separately but MUST all
+
be present for the Email to match the filter.
+
o Tokens (not part of a phrase) MAY be matched on a whole-word basis
+
using stemming (for example, a text search for "bus" would match
+
"buses" but not "business").
+
The following value for the "property" field on the Comparator object
+
MUST be supported for sorting:
+
o "receivedAt" - The "receivedAt" date as returned in the Email
+
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.
+
o "size" - The "size" as returned in the Email object.
+
o "from" - This is taken to be either the "name" property or if
+
null/empty, the "email" property of the *first* EmailAddress
+
object in the Email's "from" property. If still none, consider
+
the value to be the empty string.
+
o "to" - This is taken to be either the "name" property or if null/
+
empty, the "email" property of the *first* EmailAddress object in
+
the Email's "to" property. If still none, consider the value to
+
o "subject" - This is taken to be the base subject of the message,
+
as defined in Section 2.1 of [RFC5256].
+
o "sentAt" - The "sentAt" property on the Email object.
+
o "hasKeyword" - This value MUST be considered true if the Email has
+
the keyword given as an additional "keyword" property on the
+
Comparator object, or false otherwise.
+
Jenkins & Newman Standards Track [Page 49]
+
RFC 8621 JMAP Mail August 2019
+
o "allInThreadHaveKeyword" - This value MUST be considered true for
+
the Email if *all* of the Emails in the same Thread have the
+
keyword given as an additional "keyword" property on the
+
o "someInThreadHaveKeyword" - This value MUST be considered true for
+
the Email if *any* of the Emails in the same Thread have the
+
keyword given as an additional "keyword" property on the
+
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).
+
"property": "someInThreadHaveKeyword",
+
"collation": "i;ascii-casemap"
+
"property": "receivedAt",
+
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.
+
4.4.3. 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).
+
Jenkins & Newman Standards Track [Page 50]
+
RFC 8621 JMAP Mail August 2019
+
4.5. Email/queryChanges
+
This is a standard "/queryChanges" method as described in [RFC8620],
+
Section 5.6 with the following additional request argument:
+
o collapseThreads: "Boolean" (default: false)
+
The "collapseThreads" argument that was used with "Email/query".
+
This is a standard "/set" method as described in [RFC8620],
+
Section 5.3. The "Email/set" method encompasses:
+
o Changing the keywords of an Email (e.g., unread/flagged status)
+
o Adding/removing an Email to/from Mailboxes (moving a message)
+
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:
+
o The "headers" property MUST NOT be given on either the top-level
+
Email or an EmailBodyPart -- the client must set each header field
+
as an individual property.
+
o There MUST NOT be two properties that represent the same header
+
field (e.g., "header:from" and "from") within the Email or
+
particular EmailBodyPart.
+
o Header fields MUST NOT be specified in parsed forms that are
+
forbidden for that particular field.
+
o Header fields beginning with "Content-" MUST NOT be specified on
+
the Email object, only on EmailBodyPart objects.
+
Jenkins & Newman Standards Track [Page 51]
+
RFC 8621 JMAP Mail August 2019
+
o If a "bodyStructure" property is given, there MUST NOT be
+
"textBody", "htmlBody", or "attachments" properties.
+
o If given, the "bodyStructure" EmailBodyPart MUST NOT contain a
+
property representing a header field that is already defined on
+
the top-level Email object.
+
o If given, textBody MUST contain exactly one body part and it MUST
+
be of type "text/plain".
+
o If given, htmlBody MUST contain exactly one body part and it MUST
+
be of type "text/html".
+
o Within an EmailBodyPart:
+
* The client may specify a partId OR a blobId, but not both. If
+
a partId is given, this partId MUST be present in the
+
* The "charset" property MUST be omitted if a partId is given
+
(the part's content is included in bodyValues, and the server
+
may choose any appropriate encoding).
+
* The "size" property MUST be omitted if a partId is given. If a
+
blobId is given, it may be included but is ignored by the
+
server (the size is actually calculated from the blob content
+
* A Content-Transfer-Encoding header field MUST NOT be given.
+
o Within an EmailBodyValue object, isEncodingProblem and isTruncated
+
MUST be either false or omitted.
+
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).
+
Jenkins & Newman Standards Track [Page 52]
+
RFC 8621 JMAP Mail August 2019
+
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
+
The following extra SetError types are defined:
+
o "blobNotFound": At least one blob id given for an EmailBodyPart
+
doesn't exist. An extra "notFound" property of type "Id[]" MUST
+
be included in the SetError object containing every "blobId"
+
referenced by an EmailBodyPart that could not be found on the
+
For "create" and "update":
+
o "tooManyKeywords": The change to the Email's keywords would exceed
+
a server-defined maximum.
+
o "tooManyMailboxes": The change to the set of Mailboxes that this
+
Email is in would exceed a server-defined maximum.
+
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"
+
For successfully copied Email objects, the "created" response
+
contains the "id", "blobId", "threadId", and "size" properties of the
+
Jenkins & Newman Standards Track [Page 53]
+
RFC 8621 JMAP Mail August 2019
+
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:
+
The id of the account to use.
+
o ifInState: "String|null"
+
This is a state string as returned by the "Email/get" method. If
+
supplied, the string must match the current state of the account
+
referenced by the accountId; otherwise, the method will be aborted
+
and a "stateMismatch" error returned. If null, any changes will
+
be applied to the current state.
+
o emails: "Id[EmailImport]"
+
A map of creation id (client specified) to EmailImport objects.
+
An *EmailImport* object has the following properties:
+
The id of the blob containing the raw message [RFC5322].
+
o mailboxIds: "Id[Boolean]"
+
The ids of the Mailboxes to assign this Email to. At least one
+
o keywords: "String[Boolean]" (default: {})
+
The keywords to apply to the Email.
+
o receivedAt: "UTCDate" (default: time of most recent Received
+
header, or time of import on server if none)
+
The "receivedAt" date to set on the Email.
+
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.
+
Jenkins & Newman Standards Track [Page 54]
+
RFC 8621 JMAP Mail August 2019
+
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"
+
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 id of the account used for this call.
+
o oldState: "String|null"
+
The state string that would have been returned by "Email/get" on
+
this account before making the requested changes, or null if the
+
server doesn't know what the previous state string was.
+
The state string that will now be returned by "Email/get" on this
+
o created: "Id[Email]|null"
+
A map of the creation id to an object containing the "id",
+
"blobId", "threadId", and "size" properties for each successfully
+
imported Email, or null if none.
+
Jenkins & Newman Standards Track [Page 55]
+
RFC 8621 JMAP Mail August 2019
+
o notCreated: "Id[SetError]|null"
+
A map of the creation id to a SetError object for each Email that
+
failed to be created, or null if all successful. The possible
+
errors are defined above.
+
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.
+
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
+
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 id of the account to use.
+
The ids of the blobs to parse.
+
Jenkins & Newman Standards Track [Page 56]
+
RFC 8621 JMAP Mail August 2019
+
o properties: "String[]"
+
If supplied, only the properties listed in the array are returned
+
for each Email object. If omitted, defaults to:
+
[ "messageId", "inReplyTo", "references", "sender", "from", "to",
+
"cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment",
+
"preview", "bodyValues", "textBody", "htmlBody", "attachments" ]
+
o bodyProperties: "String[]"
+
A list of properties to fetch for each EmailBodyPart returned. If
+
omitted, defaults to the same value as the "Email/get"
+
"bodyProperties" default argument.
+
o fetchTextBodyValues: "Boolean" (default: false)
+
If true, the "bodyValues" property includes any "text/*" part in
+
the "textBody" property.
+
o fetchHTMLBodyValues: "Boolean" (default: false)
+
If true, the "bodyValues" property includes any "text/*" part in
+
the "htmlBody" property.
+
o fetchAllBodyValues: "Boolean" (default: false)
+
If true, the "bodyValues" property includes any "text/*" part in
+
the "bodyStructure" property.
+
o maxBodyValueBytes: "UnsignedInt" (default: 0)
+
If greater than zero, the "value" property of any EmailBodyValue
+
object returned in "bodyValues" MUST be truncated if necessary so
+
it does not exceed this number of octets in size. If 0 (the
+
default), no truncation occurs.
+
The server MUST ensure the truncation results in valid UTF-8 and
+
does not occur mid-codepoint. If the part is of type "text/html",
+
the server SHOULD NOT truncate inside an HTML tag, e.g., in the
+
middle of "<a href="https://example.com">". There is no
+
requirement for the truncated form to be a balanced tree or valid
+
HTML (indeed, the original source may well be neither of these
+
Jenkins & Newman Standards Track [Page 57]
+
RFC 8621 JMAP Mail August 2019
+
The response has the following arguments:
+
The id of the account used for the call.
+
o parsed: "Id[Email]|null"
+
A map of blob id to parsed Email representation for each
+
successfully parsed blob, or null if none.
+
o notParsable: "Id[]|null"
+
A list of ids given that corresponded to blobs that could not be
+
parsed as Emails, or null if none.
+
o notFound: "Id[]|null"
+
A list of blob ids given that could not be found, or null if none.
+
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.
+
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:
+
"accountId": "ue150411c",
+
"inMailbox": "fb666a55"
+
"property": "receivedAt"
+
"collapseThreads": true,
+
Jenkins & Newman Standards Track [Page 58]
+
RFC 8621 JMAP Mail August 2019
+
"accountId": "ue150411c",
+
"accountId": "ue150411c",
+
"path": "/list/*/threadId"
+
"accountId": "ue150411c",
+
"path": "/list/*/emailIds"
+
Jenkins & Newman Standards Track [Page 59]
+
RFC 8621 JMAP Mail August 2019
+
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
+
"1": Now we use a back-reference to fetch the Thread ids for each of
+
"2": Another back-reference fetches the Thread object for each of
+
"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
+
The response from the server may look something like this:
+
"accountId": "ue150411c",
+
"queryState": "09aa9a075588-780599:0",
+
"canCalculateChanges": true,
+
"ids": [ "Ma783e5cdf5f2deffbc97930a",
+
"M9bd17497e2a99cb345fc1d0a", ... ]
+
"accountId": "ue150411c",
+
"id": "Ma783e5cdf5f2deffbc97930a",
+
"threadId": "T36703c2cfe9bd5ed"
+
"id": "M9bd17497e2a99cb345fc1d0a",
+
"threadId": "T0a22ad76e9c097a1"
+
"accountId": "ue150411c",
+
"id": "T36703c2cfe9bd5ed",
+
"emailIds": [ "Ma783e5cdf5f2deffbc97930a" ]
+
Jenkins & Newman Standards Track [Page 60]
+
RFC 8621 JMAP Mail August 2019
+
"id": "T0a22ad76e9c097a1",
+
"emailIds": [ "M3b568670a63e5d100f518fa5",
+
"M9bd17497e2a99cb345fc1d0a" ]
+
"accountId": "ue150411c",
+
"id": "Ma783e5cdf5f2deffbc97930a",
+
"threadId": "T36703c2cfe9bd5ed",
+
"email": "jdoe@example.com",
+
"subject": "The Big Reveal",
+
"receivedAt": "2018-06-27T00:20:35Z",
+
"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..."
+
Jenkins & Newman Standards Track [Page 61]
+
RFC 8621 JMAP Mail August 2019
+
Now, on another device, the user marks the first Email as unread,
+
sending this API request:
+
"accountId": "ue150411c",
+
"Ma783e5cdf5f2deffbc97930a": {
+
The server applies this and sends the success response:
+
"accountId": "ue150411c",
+
"Ma783e5cdf5f2deffbc97930a": null
+
The user also deletes a few Emails, and then a new message arrives.
+
Jenkins & Newman Standards Track [Page 62]
+
RFC 8621 JMAP Mail August 2019
+
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:
+
"accountId": "ue150411c",
+
"sinceState": "780605",
+
[ "Email/queryChanges", {
+
"accountId": "ue150411c",
+
"inMailbox": "fb666a55"
+
"property": "receivedAt",
+
"collapseThreads": true,
+
"sinceQueryState": "09aa9a075588-780599:0",
+
"upToId": "Mc2781d5e856a908d8a35a564",
+
"accountId": "ue150411c",
+
"hasMoreChanges": false,
+
"created": [ "Me8de6c9f6de198239b982ea2" ],
+
"updated": [ "Ma783e5cdf5f2deffbc97930a" ],
+
"destroyed": [ "M9bd17497e2a99cb345fc1d0a", ... ]
+
[ "Email/queryChanges", {
+
"accountId": "ue150411c",
+
"oldQueryState": "09aa9a075588-780599:0",
+
"newQueryState": "e35e9facf117-780615:0",
+
"id": "Me8de6c9f6de198239b982ea2",
+
"removed": [ "M9bd17497e2a99cb345fc1d0a" ],
+
Jenkins & Newman Standards Track [Page 63]
+
RFC 8621 JMAP Mail August 2019
+
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 English so adds this metadata to the
+
body part. The user saves a draft while the composition is still in
+
progress. The client sends:
+
"accountId": "ue150411c",
+
"email": "joe@example.com"
+
"subject": "World domination",
+
"receivedAt": "2018-07-10T01:03:11Z",
+
"sentAt": "2018-07-10T11:03:11+10:00",
+
"header:Content-Language": "en"
+
"value": "I have the most brilliant plan. Let me tell
+
you all about it. What we do is, we",
+
Jenkins & Newman Standards Track [Page 64]
+
RFC 8621 JMAP Mail August 2019
+
The server creates the message and sends the success response:
+
"accountId": "ue150411c",
+
"id": "Mf40b5f831efa7233b9eb1c7f",
+
"blobId": "Gf40b5f831efa7233b9eb1c7f8f97d84eeeee64f7",
+
"threadId": "Td957e72e89f516dc",
+
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
+
Date: Tue, 10 Jul 2018 11:03:11 +1000
+
From: "Joe Bloggs" <joe@example.com>
+
Subject: World domination
+
Content-Type: text/plain
+
I have the most brilliant plan. Let me tell you all about it. What we
+
The user adds a recipient and converts the message to HTML so they
+
can add formatting, then saves an updated draft:
+
"accountId": "ue150411c",
+
"email": "joe@example.com"
+
Jenkins & Newman Standards Track [Page 65]
+
RFC 8621 JMAP Mail August 2019
+
"email": "john@example.com"
+
"subject": "World domination",
+
"receivedAt": "2018-07-10T01:05:08Z",
+
"sentAt": "2018-07-10T11:05:08+10:00",
+
"type": "multipart/alternative",
+
"header:Content-Language": "en"
+
"header:Content-Language": "en"
+
"value": "I have the most brilliant plan. Let me tell
+
you all about it. What we do is, we",
+
"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>
+
"destroy": [ "Mf40b5f831efa7233b9eb1c7f" ]
+
Jenkins & Newman Standards Track [Page 66]
+
RFC 8621 JMAP Mail August 2019
+
The server creates the new draft, deletes the old one, and sends the
+
"accountId": "ue150411c",
+
"id": "Md45b47b4877521042cec0938",
+
"blobId": "Ge8de6c9f6de198239b982ea214e0f3a704e4af74",
+
"threadId": "Td957e72e89f516dc",
+
"destroyed": [ "Mf40b5f831efa7233b9eb1c7f" ],
+
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:
+
"fromAccountId": "ue150411c",
+
"accountId": "u6c6c41ac",
+
"id": "Md45b47b4877521042cec0938",
+
"onSuccessDestroyOriginal": true
+
Jenkins & Newman Standards Track [Page 67]
+
RFC 8621 JMAP Mail August 2019
+
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:
+
"fromAccountId": "ue150411c",
+
"accountId": "u6c6c41ac",
+
"oldState": "7ee7e9263a6d",
+
"newState": "5a0d2447ed26",
+
"id": "M138f9954a5cd2423daeafa55",
+
"blobId": "G6b9fb047cba722c48c611e79233d057c6b0b74e8",
+
"threadId": "T2f242ea424a4079a",
+
"accountId": "ue150411c",
+
"destroyed": [ "Md45b47b4877521042cec0938" ],
+
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:
+
The Email id the snippet applies to.
+
Jenkins & Newman Standards Track [Page 68]
+
RFC 8621 JMAP Mail August 2019
+
o subject: "String|null"
+
If text from the filter matches the subject, this is the subject
+
of the Email with the following transformations:
+
1. Any instance of the following three characters MUST be
+
replaced by an appropriate HTML entity: & (ampersand), <
+
(less-than sign), and > (greater-than sign) [HTML]. Other
+
characters MAY also be replaced with an HTML entity form.
+
2. The matching words/phrases from the filter are wrapped in HTML
+
If the subject does not match text from the filter, this property
+
o preview: "String|null"
+
If text from the filter matches the plaintext or HTML body, this
+
is the relevant section of the body (converted to plaintext if
+
originally HTML), with the same transformations as the "subject"
+
property. It MUST NOT be bigger than 255 octets in size. If the
+
body does not contain a match for the text from the filter, this
+
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
+
The following JMAP method is supported.
+
To fetch search snippets, make a call to "SearchSnippet/get". It
+
takes the following arguments:
+
The id of the account to use.
+
o filter: "FilterOperator|FilterCondition|null"
+
The same filter as passed to "Email/query"; see the description of
+
this method in Section 4.4 for details.
+
Jenkins & Newman Standards Track [Page 69]
+
RFC 8621 JMAP Mail August 2019
+
The ids of the Emails to fetch snippets for.
+
The response has the following arguments:
+
The id of the account used for the call.
+
o list: "SearchSnippet[]"
+
An array of SearchSnippet objects for the requested Email ids.
+
This may not be in the same order as the ids that were in the
+
o notFound: "Id[]|null"
+
An array of Email ids requested that could not be found, or null
+
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
+
"unsupportedFilter": The server is unable to process the given
+
"filter" for any reason.
+
Jenkins & Newman Standards Track [Page 70]
+
RFC 8621 JMAP Mail August 2019
+
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",
+
"M44200ec123de277c0c1ce69c",
+
"M7bcbcb0b58d7729686e83d99",
+
"M28d12783a0969584b6deaac0",
+
[[ "SearchSnippet/get", {
+
"accountId": "ue150411c",
+
"emailId": "M44200ec123de277c0c1ce69c",
+
"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",
+
"preview": "...the <mark>Foo</mark>/bar method results often
+
returns <1 widget rather than the complete..."
+
Jenkins & Newman Standards Track [Page 71]
+
RFC 8621 JMAP Mail August 2019
+
An *Identity* object stores information about an email address or
+
domain the user may send from. It has the following properties:
+
o id: "Id" (immutable; server-set)
+
The id of the Identity.
+
o name: "String" (default: "")
+
The "From" name the client SHOULD use when creating a new Email
+
o email: "String" (immutable)
+
The "From" email address the client MUST use when creating a new
+
Email from this Identity. If the "mailbox" part of the address
+
(the section before the "@") is the single character "*" (e.g.,
+
"*@example.com"), the client may use any valid address ending in
+
that domain (e.g., "foo@example.com").
+
o replyTo: "EmailAddress[]|null" (default: null)
+
The Reply-To value the client SHOULD set when creating a new Email
+
o bcc: "EmailAddress[]|null" (default: null)
+
The Bcc value the client SHOULD set when creating a new Email from
+
o textSignature: "String" (default: "")
+
A signature the client SHOULD insert into new plaintext messages
+
that will be sent from this Identity. Clients MAY ignore this
+
and/or combine this with a client-specific signature preference.
+
o htmlSignature: "String" (default: "")
+
A signature the client SHOULD insert into new HTML messages that
+
will be sent from this Identity. This text MUST be an HTML
+
snippet to be inserted into the "<body></body>" section of the
+
HTML. Clients MAY ignore this and/or combine this with a client-
+
specific signature preference.
+
Jenkins & Newman Standards Track [Page 72]
+
RFC 8621 JMAP Mail August 2019
+
o mayDelete: "Boolean" (server-set)
+
Is the user allowed to delete this Identity? Servers may wish to
+
set this to false for the user's username or other default
+
address. Attempts to destroy an Identity with "mayDelete: false"
+
will be rejected with a standard "forbidden" SetError.
+
See the "Addresses" header form description in the Email object
+
(Section 4.1.2.3) 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.
+
This is a standard "/get" method as described in [RFC8620],
+
Section 5.1. The "ids" argument may be null to fetch all at once.
+
This is a standard "/changes" method as described in [RFC8620],
+
This is a standard "/set" method as described in [RFC8620],
+
Section 5.3. The following extra SetError types are defined:
+
o "forbiddenFrom": The user is not allowed to send from the address
+
given as the "email" property of the Identity.
+
Jenkins & Newman Standards Track [Page 73]
+
RFC 8621 JMAP Mail August 2019
+
"state": "99401312ae-11-333",
+
"id": "XD-3301-222-11_22AAz",
+
"email": "joe@example.com",
+
"email": "joe+archive@example.com"
+
"textSignature": "-- \nJoe Bloggs\nMaster of Email",
+
"htmlSignature": "<div><b>Joe Bloggs</b></div>
+
<div>Master of Email</div>",
+
"id": "XD-9911312-11_22AAz",
+
"email": "*@example.com",
+
An *EmailSubmission* object represents the submission of an Email for
+
delivery to one or more recipients. It has the following properties:
+
o id: "Id" (immutable; server-set)
+
The id of the EmailSubmission.
+
o identityId: "Id" (immutable)
+
The id of the Identity to associate with this submission.
+
Jenkins & Newman Standards Track [Page 74]
+
RFC 8621 JMAP Mail August 2019
+
o emailId: "Id" (immutable)
+
The id of the Email to send. The Email being sent does not have
+
to be a draft, for example, when "redirecting" an existing Email
+
to a different address.
+
o threadId: "Id" (immutable; server-set)
+
The Thread id of the Email to send. This is set by the server to
+
the "threadId" property of the Email referenced by the "emailId".
+
o envelope: "Envelope|null" (immutable)
+
Information for use when sending via SMTP. An *Envelope* object
+
has the following properties:
+
The email address to use as the return address in the SMTP
+
submission, plus any parameters to pass with the MAIL FROM
+
address. The JMAP server MAY allow the address to be the empty
+
When a JMAP server performs an SMTP message submission, it MAY
+
use the same id string for the ENVID parameter [RFC3461] and
+
the EmailSubmission object id. Servers that do this MAY
+
replace a client-provided value for ENVID with a server-
+
The email addresses to send the message to, and any RCPT TO
+
parameters to pass with the recipient.
+
An *Address* object has the following properties:
+
The email address being represented by the object. This is a
+
"Mailbox" as used in the Reverse-path or Forward-path of the
+
MAIL FROM or RCPT TO command in [RFC5321].
+
* parameters: "Object|null"
+
Any parameters to send with the email address (either mail-
+
parameter or rcpt-parameter as appropriate, as specified in
+
[RFC5321]). If supplied, each key in the object is a parameter
+
name, and the value is either the parameter value (type
+
Jenkins & Newman Standards Track [Page 75]
+
RFC 8621 JMAP Mail August 2019
+
"String") or null if the parameter does not take a value. For
+
both name and value, any xtext or unitext encodings are removed
+
(see [RFC3461] and [RFC6533]) and JSON string encoding is
+
If the "envelope" property is null or omitted on creation, the
+
server MUST generate this from the referenced Email as follows:
+
* "mailFrom": The email address in the Sender header field, if
+
present; otherwise, it's the email address in the From header
+
field, if present. In either case, no parameters are added.
+
If multiple addresses are present in one of these header
+
fields, or there is more than one Sender/From header field, the
+
server SHOULD reject the EmailSubmission as invalid; otherwise,
+
it MUST take the first address in the last Sender/From header
+
If the address found from this is not allowed by the Identity
+
associated with this submission, the "email" property from the
+
Identity MUST be used instead.
+
* "rcptTo": The deduplicated set of email addresses from the To,
+
Cc, and Bcc header fields, if present, with no parameters for
+
o sendAt: "UTCDate" (immutable; server-set)
+
The date the submission was/will be released for delivery. If the
+
client successfully used FUTURERELEASE [RFC4865] with the
+
submission, this MUST be the time when the server will release the
+
message; otherwise, it MUST be the time the EmailSubmission was
+
This represents whether the submission may be canceled. This is
+
server set on create and MUST be one of the following values:
+
* "pending": It may be possible to cancel this submission.
+
* "final": The message has been relayed to at least one recipient
+
in a manner that cannot be recalled. It is no longer possible
+
to cancel this submission.
+
* "canceled": The submission was canceled and will not be
+
delivered to any recipient.
+
Jenkins & Newman Standards Track [Page 76]
+
RFC 8621 JMAP Mail August 2019
+
On systems that do not support unsending, the value of this
+
property will always be "final". On systems that do support
+
canceling submission, it will start as "pending" and MAY
+
transition to "final" when the server knows it definitely cannot
+
recall the message, but it MAY just remain "pending". If in
+
pending state, a client can attempt to cancel the submission by
+
setting this property to "canceled"; if the update succeeds, the
+
submission was successfully canceled, and the message has not been
+
delivered to any of the original recipients.
+
o deliveryStatus: "String[DeliveryStatus]|null" (server-set)
+
This represents the delivery status for each of the submission's
+
recipients, if known. This property MAY not be supported by all
+
servers, in which case it will remain null. Servers that support
+
it SHOULD update the EmailSubmission object each time the status
+
of any of the recipients changes, even if some recipients are
+
This value is a map from the email address of each recipient to a
+
A *DeliveryStatus* object has the following properties:
+
The SMTP reply string returned for this recipient when the
+
server last tried to relay the message, or in a later Delivery
+
Status Notification (DSN, as defined in [RFC3464]) response for
+
the message. This SHOULD be the response to the RCPT TO stage,
+
unless this was accepted and the message as a whole was
+
rejected at the end of the DATA stage, in which case the DATA
+
stage reply SHOULD be used instead.
+
Multi-line SMTP responses should be concatenated to a single
+
+ The hyphen following the SMTP code on all but the last line
+
is replaced with a space.
+
+ Any prefix in common with the first line is stripped from
+
+ CRLF is replaced by a space.
+
Jenkins & Newman Standards Track [Page 77]
+
RFC 8621 JMAP Mail August 2019
+
550-5.7.1 Our system has detected that this message is
+
550 5.7.1 Our system has detected that this message is likely spam.
+
For messages relayed via an alternative to SMTP, the server MAY
+
generate a synthetic string representing the status instead.
+
If it does this, the string MUST be of the following form:
+
+ A 3-digit SMTP reply code, as defined in [RFC5321],
+
+ Then a single space character.
+
+ Then an SMTP Enhanced Mail System Status Code as defined in
+
[RFC3463], with a registry defined in [RFC5248].
+
+ Then a single space character.
+
+ Then an implementation-specific information string with a
+
human-readable explanation of the response.
+
Represents whether the message has been successfully delivered
+
to the recipient. This MUST be one of the following values:
+
+ "queued": The message is in a local mail queue and the
+
status will change once it exits the local mail queues. The
+
"smtpReply" property may still change.
+
+ "yes": The message was successfully delivered to the mail
+
store of the recipient. The "smtpReply" property is final.
+
+ "no": Delivery to the recipient permanently failed. The
+
"smtpReply" property is final.
+
+ "unknown": The final delivery status is unknown, (e.g., it
+
was relayed to an external machine and no further
+
information is available). The "smtpReply" property may
+
still change if a DSN arrives.
+
Jenkins & Newman Standards Track [Page 78]
+
RFC 8621 JMAP Mail August 2019
+
Note that successful relaying to an external SMTP server SHOULD
+
NOT be taken as an indication that the message has successfully
+
reached the final mail store. In this case though, the server
+
may receive a DSN response, if requested.
+
If a DSN is received for the recipient with Action equal to
+
"delivered", as per [RFC3464], Section 2.3.3, then the
+
"delivered" property SHOULD be set to "yes"; if the Action
+
equals "failed", the property SHOULD be set to "no". Receipt
+
of any other DSN SHOULD NOT affect this property.
+
The server MAY also set this property based on other feedback
+
Represents whether the message has been displayed to the
+
recipient. This MUST be one of the following values:
+
+ "unknown": The display status is unknown. This is the
+
+ "yes": The recipient's system claims the message content has
+
been displayed to the recipient. Note that there is no
+
guarantee that the recipient has noticed, read, or
+
understood the content.
+
If a Message Disposition Notification (MDN) is received for
+
this recipient with Disposition-Type (as per [RFC8098],
+
Section 3.2.6.2) equal to "displayed", this property SHOULD be
+
The server MAY also set this property based on other feedback
+
o dsnBlobIds: "Id[]" (server-set)
+
A list of blob ids for DSNs [RFC3464] received for this
+
submission, in order of receipt, oldest first. The blob is the
+
whole MIME message (with a top-level content-type of "multipart/
+
o mdnBlobIds: "Id[]" (server-set)
+
A list of blob ids for MDNs [RFC8098] received for this
+
submission, in order of receipt, oldest first. The blob is the
+
whole MIME message (with a top-level content-type of "multipart/
+
Jenkins & Newman Standards Track [Page 79]
+
RFC 8621 JMAP Mail August 2019
+
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
+
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.
+
7.1. EmailSubmission/get
+
This is a standard "/get" method as described in [RFC8620],
+
7.2. EmailSubmission/changes
+
This is a standard "/changes" method as described in [RFC8620],
+
7.3. EmailSubmission/query
+
This is a standard "/query" method as described in [RFC8620],
+
A *FilterCondition* object has the following properties, any of which
+
The EmailSubmission "identityId" property must be in this list to
+
The EmailSubmission "emailId" property must be in this list to
+
The EmailSubmission "threadId" property must be in this list to
+
Jenkins & Newman Standards Track [Page 80]
+
RFC 8621 JMAP Mail August 2019
+
The EmailSubmission "undoStatus" property must be identical to the
+
value given to match the condition.
+
The "sendAt" property of the EmailSubmission object must be before
+
this date-time to match the condition.
+
The "sendAt" property of the EmailSubmission object must be the
+
same as or after this date-time to match the condition.
+
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
+
7.4. EmailSubmission/queryChanges
+
This is a standard "/queryChanges" method as described in [RFC8620],
+
7.5. EmailSubmission/set
+
This is a standard "/set" method as described in [RFC8620],
+
Section 5.3 with the following two additional request arguments:
+
o onSuccessUpdateEmail: "Id[PatchObject]|null"
+
A map of EmailSubmission id to an object containing properties to
+
update on the Email object referenced by the EmailSubmission if
+
the create/update/destroy succeeds. (For references to
+
EmailSubmissions created in the same "/set" invocation, this is
+
equivalent to a creation-reference, so the id will be the creation
+
id prefixed with a "#".)
+
Jenkins & Newman Standards Track [Page 81]
+
RFC 8621 JMAP Mail August 2019
+
o onSuccessDestroyEmail: "Id[]|null"
+
A list of EmailSubmission ids for which the Email with the
+
corresponding "emailId" should be destroyed if the create/update/
+
destroy succeeds. (For references to EmailSubmission creations,
+
this is equivalent to a creation-reference, so the id will be the
+
creation id prefixed with a "#".)
+
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"
+
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
+
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
+
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 a 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.
+
Jenkins & Newman Standards Track [Page 82]
+
RFC 8621 JMAP Mail August 2019
+
The following extra SetError types are defined:
+
o "invalidEmail" - The Email to be sent is invalid in some way. The
+
SetError SHOULD contain a property called "properties" of type
+
"String[]" that lists *all* the properties of the Email that were
+
o "tooManyRecipients" - The envelope (supplied or generated) has
+
more recipients than the server allows. A "maxRecipients"
+
"UnsignedInt" property MUST also be present on the SetError
+
specifying the maximum number of allowed recipients.
+
o "noRecipients" - The envelope (supplied or generated) does not
+
have any rcptTo email addresses.
+
o "invalidRecipients" - The "rcptTo" property of the envelope
+
(supplied or generated) contains at least one rcptTo value, which
+
is not a valid email address for sending to. An
+
"invalidRecipients" "String[]" property MUST also be present on
+
the SetError, which is a list of the invalid addresses.
+
o "forbiddenMailFrom" - The server does not permit the user to send
+
a message with the envelope From address [RFC5321].
+
o "forbiddenFrom" - The server does not permit the user to send a
+
message with the From header field [RFC5322] of the message to be
+
o "forbiddenToSend" - The user does not have permission to send at
+
all right now for some reason. A "description" "String" property
+
MAY be present on the SetError object to display to the user why
+
they are not permitted.
+
o "cannotUnsend" - The client attempted to update the "undoStatus"
+
of a valid EmailSubmission object from "pending" to "canceled",
+
but the message cannot be unsent.
+
Jenkins & Newman Standards Track [Page 83]
+
RFC 8621 JMAP Mail August 2019
+
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-
+
[[ "EmailSubmission/set", {
+
"accountId": "ue411d190",
+
"identityId": "I64588216",
+
"emailId": "M7f6ed5bcfd7e2604d1753f6c",
+
"email": "john@example.com",
+
"email": "jane@example.com",
+
"onSuccessUpdateEmail": {
+
"mailboxIds/7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e": null,
+
"mailboxIds/73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6": true,
+
"keywords/$draft": null
+
Jenkins & Newman Standards Track [Page 84]
+
RFC 8621 JMAP Mail August 2019
+
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",
+
"id": "ES-3bab7f9a-623e-4acf-99a5-2e67facb02a0"
+
"accountId": "ue411d190",
+
"M7f6ed5bcfd7e2604d1753f6c": null
+
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
+
Jenkins & Newman Standards Track [Page 85]
+
RFC 8621 JMAP Mail August 2019
+
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",
+
"type": "forbiddenToSend",
+
"description": "Verzeihung, wegen verdaechtiger Aktivitaeten Ihres
+
Benutzerkontos haben wir den Versand von Nachrichten gesperrt.
+
Bitte wenden Sie sich fuer Hilfe an unser Support Team."
+
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
+
The *VacationResponse* object represents the state of vacation-
+
response-related settings for an account. It has the following
+
o id: "Id" (immutable; server-set)
+
The id of the object. There is only ever one VacationResponse
+
object, and its id is "singleton".
+
Should a vacation response be sent if a message arrives between
+
the "fromDate" and "toDate"?
+
Jenkins & Newman Standards Track [Page 86]
+
RFC 8621 JMAP Mail August 2019
+
o fromDate: "UTCDate|null"
+
If "isEnabled" is true, messages that arrive on or after this
+
date-time (but before the "toDate" if defined) should receive the
+
user's vacation response. If null, the vacation response is
+
o toDate: "UTCDate|null"
+
If "isEnabled" is true, messages that arrive before this date-time
+
(but on or after the "fromDate" if defined) should receive the
+
user's vacation response. If null, the vacation response is
+
effective indefinitely.
+
o subject: "String|null"
+
The subject that will be used by the message sent in response to
+
messages when the vacation response is enabled. If null, an
+
appropriate subject SHOULD be set by the server.
+
o textBody: "String|null"
+
The plaintext body to send in response to messages when the
+
vacation response is enabled. If this is null, the server SHOULD
+
generate a plaintext body part from the "htmlBody" when sending
+
vacation responses but MAY choose to send the response as HTML
+
only. If both "textBody" and "htmlBody" are null, an appropriate
+
default body SHOULD be generated for responses by the server.
+
o htmlBody: "String|null"
+
The HTML body to send in response to messages when the vacation
+
response is enabled. If this is null, the server MAY choose to
+
generate an HTML body part from the "textBody" when sending
+
vacation responses or MAY choose to send the response as plaintext
+
The following JMAP methods are supported.
+
8.1. VacationResponse/get
+
This is a standard "/get" method as described in [RFC8620],
+
There MUST only be exactly one VacationResponse object in an account.
+
It MUST have the id "singleton".
+
Jenkins & Newman Standards Track [Page 87]
+
RFC 8621 JMAP Mail August 2019
+
8.2. VacationResponse/set
+
This is a standard "/set" method as described in [RFC8620],
+
9. 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
+
9.1. 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
+
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
+
9.2. 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,
+
Jenkins & Newman Standards Track [Page 88]
+
RFC 8621 JMAP Mail August 2019
+
o Embedded JavaScript can rewrite the message to change its content
+
on subsequent opening, allowing users to be mislead. In webmail
+
systems, if run in the same origin as the interface, it can access
+
and exfiltrate all private data accessible to the user, including
+
all other messages and potentially contacts, calendar events,
+
settings, and credentials. It can also rewrite the interface to
+
undetectably phish passwords. A compromise is likely to be
+
persistent, not just for the duration of page load, due to
+
exfiltration of session credentials or installation of a service
+
worker that can intercept all subsequent network requests
+
(however, this would only be possible if blob downloads are also
+
available on the same origin, and the service worker script is
+
attached to the message).
+
o HTML documents may load content directly from the Internet rather
+
than just referencing attached resources. For example, you may
+
have an "<img>" tag with an external "src" attribute. This may
+
leak to the sender when a message is opened, as well as the IP
+
address of the recipient. Cookies may also be sent and set by the
+
server, allowing tracking between different messages and even
+
website visits and advertising profiles.
+
o In webmail systems, CSS can break the layout or create phishing
+
vulnerabilities. For example, the use of "position:fixed" can
+
allow a message to draw content outside of its normal bounds,
+
potentially clickjacking a real interface element.
+
o If in a webmail context and not inside a separate frame, any
+
styles defined in CSS rules will apply to interface elements as
+
well if the selector matches, allowing the interface to be
+
modified. Similarly, any interface styles that match elements in
+
the message will alter their appearance, potentially breaking the
+
o The link text in HTML has no necessary correlation with the actual
+
target of the link, which can be used to make phishing attacks
+
o Links opened from a message or embedded external content may leak
+
private info in the Referer header sent by default in most
+
o Forms can be used to mimic login boxes, providing a potent
+
phishing vector if allowed to submit directly from the message
+
Jenkins & Newman Standards Track [Page 89]
+
RFC 8621 JMAP Mail August 2019
+
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.
+
o HTML can be filtered before rendering, stripping potentially
+
malicious content. Sanitising HTML correctly is tricky, and
+
implementors are strongly recommended to use a well-tested library
+
with a carefully vetted whitelist-only approach. New features
+
with unexpected security characteristics may be added to HTML
+
rendering engines in the future; a blacklist approach is likely to
+
result in security issues.
+
Subtle differences in parsing of HTML can introduce security
+
flaws: to filter with 100% accuracy, you need to use the same
+
parser that the HTML rendering engine will use.
+
o Encapsulating the message in an "<iframe sandbox>", as defined in
+
[HTML], Section 4.7.6, can help mitigate a number of risks. This
+
* Disable form submission.
+
* Prevent drawing outside of its bounds or conflicts between
+
message CSS and interface CSS.
+
* Establish a unique anonymous origin, separate to the containing
+
o A strong Content Security Policy (see <https://www.w3.org/TR/
+
CSP3/>) can, among other things, block JavaScript and the loading
+
of external content should it manage to evade the filter.
+
o The leakage of information in the Referer header can be mitigated
+
with the use of a referrer policy (see <https://www.w3.org/TR/
+
o A "crossorigin=anonymous" attribute on tags that load remote
+
content can prevent cookies from being sent.
+
o If adding "target=_blank" to open links in new tabs, also add
+
"rel=noopener" to ensure the page that opens cannot change the URL
+
in the original tab to redirect the user to a phishing site.
+
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.
+
Jenkins & Newman Standards Track [Page 90]
+
RFC 8621 JMAP Mail August 2019
+
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.
+
9.3. 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].
+
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 [XCLIENT] can be used to do this, but use of an authenticated
+
channel is recommended to limit use of that extension to explicitly
+
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.
+
Jenkins & Newman Standards Track [Page 91]
+
RFC 8621 JMAP Mail August 2019
+
9.5. 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.
+
9.6. 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.
+
Jenkins & Newman Standards Track [Page 92]
+
RFC 8621 JMAP Mail August 2019
+
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.
+
10. IANA Considerations
+
10.1. 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
+
Change Controller: IETF
+
Security and privacy considerations: this document, Section 9
+
10.2. 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
+
Change Controller: IETF
+
Security and privacy considerations: this document, Section 9
+
Jenkins & Newman Standards Track [Page 93]
+
RFC 8621 JMAP Mail August 2019
+
10.3. JMAP Capability Registration for "vacationresponse"
+
IANA has registered the "vacationresponse" JMAP Capability as
+
Capability Name: urn:ietf:params:jmap:vacationresponse
+
Specification document: this document
+
Change Controller: IETF
+
Security and privacy considerations: this document, Section 9
+
10.4. IMAP and JMAP Keywords Registry
+
This document makes two changes to the IMAP keywords registry as
+
First, the name of the registry is changed to the "IMAP and JMAP
+
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.
+
Jenkins & Newman Standards Track [Page 94]
+
RFC 8621 JMAP Mail August 2019
+
10.4.1. Registration of JMAP Keyword "$draft"
+
This registers the "JMAP-only" keyword "$draft" in the "IMAP and JMAP
+
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 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>
+
Owner/Change controller: IESG
+
Jenkins & Newman Standards Track [Page 95]
+
RFC 8621 JMAP Mail August 2019
+
10.4.2. Registration of JMAP Keyword "$seen"
+
This registers the "JMAP-only" keyword "$seen" in the "IMAP and JMAP
+
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
+
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>
+
Owner/Change controller: IESG
+
Jenkins & Newman Standards Track [Page 96]
+
RFC 8621 JMAP Mail August 2019
+
10.4.3. Registration of JMAP Keyword "$flagged"
+
This registers the "JMAP-only" keyword "$flagged" in the "IMAP and
+
JMAP Keywords" registry.
+
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 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>
+
Owner/Change controller: IESG
+
Jenkins & Newman Standards Track [Page 97]
+
RFC 8621 JMAP Mail August 2019
+
10.4.4. Registration of JMAP Keyword "$answered"
+
This registers the "JMAP-only" keyword "$answered" in the "IMAP and
+
JMAP Keywords" registry.
+
Keyword name: $answered
+
Purpose (description): This is set when the message has been
+
Private or Shared on a server: BOTH
+
Is it an advisory keyword or may it cause an automatic action:
+
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 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>
+
Owner/Change controller: IESG
+
Jenkins & Newman Standards Track [Page 98]
+
RFC 8621 JMAP Mail August 2019
+
10.4.5. Registration of "$recent" Keyword
+
This registers the keyword "$recent" in the "IMAP and JMAP Keywords"
+
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
+
10.5. IMAP Mailbox Name Attributes Registry
+
10.5.1. Registration of "inbox" Role
+
This registers the "JMAP-only" "inbox" attribute in the "IMAP Mailbox
+
Name Attributes" registry, as established in [RFC8457].
+
Description: New mail is delivered here by default.
+
Reference: This document, Section 10.5.1
+
Jenkins & Newman Standards Track [Page 99]
+
RFC 8621 JMAP Mail August 2019
+
10.6. JMAP Error Codes Registry
+
The following subsections register several new error codes in the
+
"JMAP Error Codes" registry, as defined in [RFC8620].
+
10.6.1. mailboxHasChild
+
JMAP Error Code: mailboxHasChild
+
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.
+
10.6.2. mailboxHasEmail
+
JMAP Error Code: mailboxHasEmail
+
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.
+
JMAP Error Code: blobNotFound
+
Change controller: IETF
+
Reference: This document, Section 4.6
+
Description: At least one blob id referenced in the object doesn't
+
Jenkins & Newman Standards Track [Page 100]
+
RFC 8621 JMAP Mail August 2019
+
10.6.4. tooManyKeywords
+
JMAP Error Code: tooManyKeywords
+
Change controller: IETF
+
Reference: This document, Section 4.6
+
Description: The change to the Email's keywords would exceed a
+
server-defined maximum.
+
10.6.5. tooManyMailboxes
+
JMAP Error Code: tooManyMailboxes
+
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.
+
JMAP Error Code: invalidEmail
+
Change controller: IETF
+
Reference: This document, Section 7.5
+
Description: The Email to be sent is invalid in some way.
+
Jenkins & Newman Standards Track [Page 101]
+
RFC 8621 JMAP Mail August 2019
+
10.6.7. tooManyRecipients
+
JMAP Error Code: tooManyRecipients
+
Change controller: IETF
+
Reference: This document, Section 7.5
+
Description: The envelope [RFC5321] (supplied or generated) has more
+
recipients than the server allows.
+
JMAP Error Code: noRecipients
+
Change controller: IETF
+
Reference: This document, Section 7.5
+
Description: The envelope [RFC5321] (supplied or generated) does not
+
have any rcptTo email addresses.
+
10.6.9. invalidRecipients
+
JMAP Error Code: invalidRecipients
+
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.
+
Jenkins & Newman Standards Track [Page 102]
+
RFC 8621 JMAP Mail August 2019
+
10.6.10. forbiddenMailFrom
+
JMAP Error Code: forbiddenMailFrom
+
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].
+
JMAP Error Code: forbiddenFrom
+
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.
+
10.6.12. forbiddenToSend
+
JMAP Error Code: forbiddenToSend
+
Change controller: IETF
+
Reference: This document, Section 7.5
+
Description: The user does not have permission to send at all right
+
Jenkins & Newman Standards Track [Page 103]
+
RFC 8621 JMAP Mail August 2019
+
11.1. Normative References
+
[HTML] Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and
+
S. Moon, "HTML 5.2", World Wide Web Consortium
+
Recommendation REC-html52-20171214, December 2017,
+
<https://www.w3.org/TR/html52/>.
+
[RFC1870] Klensin, J., Freed, N., and K. Moore, "SMTP Service
+
Extension for Message Size Declaration", STD 10, RFC 1870,
+
DOI 10.17487/RFC1870, November 1995,
+
<https://www.rfc-editor.org/info/rfc1870>.
+
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+
Extensions (MIME) Part One: Format of Internet Message
+
Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
+
<https://www.rfc-editor.org/info/rfc2045>.
+
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
+
Part Three: Message Header Extensions for Non-ASCII Text",
+
RFC 2047, DOI 10.17487/RFC2047, November 1996,
+
<https://www.rfc-editor.org/info/rfc2047>.
+
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+
Requirement Levels", BCP 14, RFC 2119,
+
DOI 10.17487/RFC2119, March 1997,
+
<https://www.rfc-editor.org/info/rfc2119>.
+
[RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
+
Word Extensions: Character Sets, Languages, and
+
Continuations", RFC 2231, DOI 10.17487/RFC2231, November
+
1997, <https://www.rfc-editor.org/info/rfc2231>.
+
[RFC2369] Neufeld, G. and J. Baer, "The Use of URLs as Meta-Syntax
+
for Core Mail List Commands and their Transport through
+
Message Header Fields", RFC 2369, DOI 10.17487/RFC2369,
+
July 1998, <https://www.rfc-editor.org/info/rfc2369>.
+
[RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource
+
Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998,
+
<https://www.rfc-editor.org/info/rfc2392>.
+
[RFC2557] Palme, J., Hopmann, A., and N. Shelness, "MIME
+
Encapsulation of Aggregate Documents, such as HTML
+
(MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999,
+
<https://www.rfc-editor.org/info/rfc2557>.
+
Jenkins & Newman Standards Track [Page 104]
+
RFC 8621 JMAP Mail August 2019
+
[RFC2852] Newman, D., "Deliver By SMTP Service Extension", RFC 2852,
+
DOI 10.17487/RFC2852, June 2000,
+
<https://www.rfc-editor.org/info/rfc2852>.
+
[RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282,
+
DOI 10.17487/RFC3282, May 2002,
+
<https://www.rfc-editor.org/info/rfc3282>.
+
[RFC3461] Moore, K., "Simple Mail Transfer Protocol (SMTP) Service
+
Extension for Delivery Status Notifications (DSNs)",
+
RFC 3461, DOI 10.17487/RFC3461, January 2003,
+
<https://www.rfc-editor.org/info/rfc3461>.
+
[RFC3463] Vaudreuil, G., "Enhanced Mail System Status Codes",
+
RFC 3463, DOI 10.17487/RFC3463, January 2003,
+
<https://www.rfc-editor.org/info/rfc3463>.
+
[RFC3464] Moore, K. and G. Vaudreuil, "An Extensible Message Format
+
for Delivery Status Notifications", RFC 3464,
+
DOI 10.17487/RFC3464, January 2003,
+
<https://www.rfc-editor.org/info/rfc3464>.
+
[RFC3834] Moore, K., "Recommendations for Automatic Responses to
+
Electronic Mail", RFC 3834, DOI 10.17487/RFC3834, August
+
2004, <https://www.rfc-editor.org/info/rfc3834>.
+
[RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
+
RFC 4314, DOI 10.17487/RFC4314, December 2005,
+
<https://www.rfc-editor.org/info/rfc4314>.
+
[RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
+
Authentication and Security Layer (SASL)", RFC 4422,
+
DOI 10.17487/RFC4422, June 2006,
+
<https://www.rfc-editor.org/info/rfc4422>.
+
[RFC4616] Zeilenga, K., Ed., "The PLAIN Simple Authentication and
+
Security Layer (SASL) Mechanism", RFC 4616,
+
DOI 10.17487/RFC4616, August 2006,
+
<https://www.rfc-editor.org/info/rfc4616>.
+
[RFC4865] White, G. and G. Vaudreuil, "SMTP Submission Service
+
Extension for Future Message Release", RFC 4865,
+
DOI 10.17487/RFC4865, May 2007,
+
<https://www.rfc-editor.org/info/rfc4865>.
+
Jenkins & Newman Standards Track [Page 105]
+
RFC 8621 JMAP Mail August 2019
+
[RFC4954] Siemborski, R., Ed. and A. Melnikov, Ed., "SMTP Service
+
Extension for Authentication", RFC 4954,
+
DOI 10.17487/RFC4954, July 2007,
+
<https://www.rfc-editor.org/info/rfc4954>.
+
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
+
Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
+
<https://www.rfc-editor.org/info/rfc5198>.
+
[RFC5248] Hansen, T. and J. Klensin, "A Registry for SMTP Enhanced
+
Mail System Status Codes", BCP 138, RFC 5248,
+
DOI 10.17487/RFC5248, June 2008,
+
<https://www.rfc-editor.org/info/rfc5248>.
+
[RFC5256] Crispin, M. and K. Murchison, "Internet Message Access
+
Protocol - SORT and THREAD Extensions", RFC 5256,
+
DOI 10.17487/RFC5256, June 2008,
+
<https://www.rfc-editor.org/info/rfc5256>.
+
[RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
+
DOI 10.17487/RFC5321, October 2008,
+
<https://www.rfc-editor.org/info/rfc5321>.
+
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
+
DOI 10.17487/RFC5322, October 2008,
+
<https://www.rfc-editor.org/info/rfc5322>.
+
[RFC5788] Melnikov, A. and D. Cridland, "IMAP4 Keyword Registry",
+
RFC 5788, DOI 10.17487/RFC5788, March 2010,
+
<https://www.rfc-editor.org/info/rfc5788>.
+
[RFC6154] Leiba, B. and J. Nicolson, "IMAP LIST Extension for
+
Special-Use Mailboxes", RFC 6154, DOI 10.17487/RFC6154,
+
March 2011, <https://www.rfc-editor.org/info/rfc6154>.
+
[RFC6409] Gellens, R. and J. Klensin, "Message Submission for Mail",
+
STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011,
+
<https://www.rfc-editor.org/info/rfc6409>.
+
[RFC6532] Yang, A., Steele, S., and N. Freed, "Internationalized
+
Email Headers", RFC 6532, DOI 10.17487/RFC6532, February
+
2012, <https://www.rfc-editor.org/info/rfc6532>.
+
[RFC6533] Hansen, T., Ed., Newman, C., and A. Melnikov,
+
"Internationalized Delivery Status and Disposition
+
Notifications", RFC 6533, DOI 10.17487/RFC6533, February
+
2012, <https://www.rfc-editor.org/info/rfc6533>.
+
Jenkins & Newman Standards Track [Page 106]
+
RFC 8621 JMAP Mail August 2019
+
[RFC6710] Melnikov, A. and K. Carlberg, "Simple Mail Transfer
+
Protocol Extension for Message Transfer Priorities",
+
RFC 6710, DOI 10.17487/RFC6710, August 2012,
+
<https://www.rfc-editor.org/info/rfc6710>.
+
[RFC7677] Hansen, T., "SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple
+
Authentication and Security Layer (SASL) Mechanisms",
+
RFC 7677, DOI 10.17487/RFC7677, November 2015,
+
<https://www.rfc-editor.org/info/rfc7677>.
+
[RFC8098] Hansen, T., Ed. and A. Melnikov, Ed., "Message Disposition
+
Notification", STD 85, RFC 8098, DOI 10.17487/RFC8098,
+
February 2017, <https://www.rfc-editor.org/info/rfc8098>.
+
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
[RFC8314] Moore, K. and C. Newman, "Cleartext Considered Obsolete:
+
Use of Transport Layer Security (TLS) for Email Submission
+
and Access", RFC 8314, DOI 10.17487/RFC8314, January 2018,
+
<https://www.rfc-editor.org/info/rfc8314>.
+
[RFC8457] Leiba, B., Ed., "IMAP "$Important" Keyword and
+
"\Important" Special-Use Attribute", RFC 8457,
+
DOI 10.17487/RFC8457, September 2018,
+
<https://www.rfc-editor.org/info/rfc8457>.
+
[RFC8474] Gondwana, B., Ed., "IMAP Extension for Object
+
Identifiers", RFC 8474, DOI 10.17487/RFC8474, September
+
2018, <https://www.rfc-editor.org/info/rfc8474>.
+
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
+
Protocol", RFC 8620, DOI 10.17487/RFC8620, June 2019,
+
<https://www.rfc-editor.org/info/rfc8620>.
+
11.2. Informative References
+
[EFAIL] Poddebniak, D., Dresen, C., Mueller, J., Ising, F.,
+
Schinzel, S., Friedberger, S., Somorovsky, J., and J.
+
Schwenk, "Efail: Breaking S/MIME and OpenPGP Email
+
Encryption using Exfiltration Channels", August 2018,
+
<https://www.usenix.org/system/files/conference/
+
usenixsecurity18/sec18-poddebniak.pdf>.
+
[milter] Postfix, "Postfix before-queue Milter support", 2019,
+
<http://www.postfix.org/MILTER_README.html>.
+
Jenkins & Newman Standards Track [Page 107]
+
RFC 8621 JMAP Mail August 2019
+
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
+
4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
+
<https://www.rfc-editor.org/info/rfc3501>.
+
[RFC7489] Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based
+
Message Authentication, Reporting, and Conformance
+
(DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015,
+
<https://www.rfc-editor.org/info/rfc7489>.
+
[XCLIENT] Postfix, "Postfix XCLIENT Howto", 2019,
+
<http://www.postfix.org/XCLIENT_README.html>.
+
PO Box 234, Collins St. West
+
Email: neilj@fastmailteam.com
+
URI: https://www.fastmail.com
+
440 E. Huntington Dr., Suite 400
+
United States of America
+
Email: chris.newman@oracle.com
+
Jenkins & Newman Standards Track [Page 108]
anil.recoil.org