summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc8621.txt
diff options
context:
space:
mode:
authorThomas Voss <mail@thomasvoss.com> 2024-11-27 20:54:24 +0100
committerThomas Voss <mail@thomasvoss.com> 2024-11-27 20:54:24 +0100
commit4bfd864f10b68b71482b35c818559068ef8d5797 (patch)
treee3989f47a7994642eb325063d46e8f08ffa681dc /doc/rfc/rfc8621.txt
parentea76e11061bda059ae9f9ad130a9895cc85607db (diff)
doc: Add RFC documents
Diffstat (limited to 'doc/rfc/rfc8621.txt')
-rw-r--r--doc/rfc/rfc8621.txt6051
1 files changed, 6051 insertions, 0 deletions
diff --git a/doc/rfc/rfc8621.txt b/doc/rfc/rfc8621.txt
new file mode 100644
index 0000000..9add50e
--- /dev/null
+++ b/doc/rfc/rfc8621.txt
@@ -0,0 +1,6051 @@
+
+
+
+
+
+
+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
+
+Abstract
+
+ 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
+ in another client.
+
+Status of This Memo
+
+ 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 Notice
+
+ 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
+
+
+Table of Contents
+
+ 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
+
+1. Introduction
+
+ The JSON Meta Application Protocol (JMAP) [RFC8620] is a generic
+ protocol for synchronising data, such as mail, calendars, or contacts
+ between a client and a server. It is optimised for mobile and web
+ environments and aims to provide a consistent interface to different
+ data types.
+
+ This specification defines a data model for accessing a mail store
+ over JMAP, allowing you to query, read, organise, and submit mail for
+ sending.
+
+ The data model is designed to allow a server to provide consistent
+ access to the same data via IMAP [RFC3501] as well as JMAP. As in
+ IMAP, a message must belong to a mailbox; however, in JMAP, its id
+ does not change if you move it between mailboxes, and the server may
+ allow it to belong to multiple mailboxes simultaneously (often
+ exposed in a user agent as labels rather than folders).
+
+ As in IMAP, messages may also be assigned zero or more keywords:
+ short arbitrary strings. These are primarily intended to store
+ metadata to inform client display, such as unread status or whether a
+ message has been replied to. An IANA registry allows common
+ semantics to be shared between clients and extended easily in the
+ future.
+
+ A message and its replies are linked on the server by a common Thread
+ id. Clients may fetch the list of messages with a particular Thread
+ id to more easily present a threaded or conversational interface.
+
+ Permissions for message access happen on a per-mailbox basis.
+ Servers may give the user restricted permissions for certain
+ mailboxes, for example, if another user's inbox has been shared as
+ read-only with them.
+
+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
+ document.
+
+ Servers MUST support all properties specified for the new data types
+ defined in this document.
+
+1.2. Terminology
+
+ This document uses the same terminology as in the core JMAP
+ specification.
+
+ The terms Mailbox, Thread, Email, SearchSnippet, EmailSubmission and
+ VacationResponse (with that specific capitalisation) are used to
+ refer to the data types defined in this document and instances of
+ those data types.
+
+ The term message refers to a document in Internet Message Format, as
+ described in [RFC5322]. The Email data type represents messages in
+ the mail store and associated metadata.
+
+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
+ 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 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
+ no limit.
+
+ 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
+ servers allow more.
+
+ 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-
+ defined limit).
+
+ 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
+ list.
+
+
+
+
+
+
+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
+ Mailbox.)
+
+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]
+
+ * SIZE [RFC1870]
+
+ * DSN [RFC3461]
+
+ * DELIVERYBY [RFC2852]
+
+
+
+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.
+
+1.5. Push
+
+ Servers MUST support the JMAP push mechanisms, as specified in
+ [RFC8620], Section 7, to receive notifications when the state changes
+ for any of the types defined in this specification.
+
+ In addition, servers that implement the "urn:ietf:params:jmap:mail"
+ capability MUST support pushing state changes for a type called
+ "EmailDelivery". There are no methods to act on this type; it only
+ exists as part of the push mechanism. The state string for this MUST
+ change whenever a new Email is added to the store, but it SHOULD NOT
+ change upon any other change to the Email objects, for example, if
+ one is marked as read or deleted.
+
+ Clients in battery-constrained environments may wish to delay
+ fetching changes initiated by the user but fetch new Emails
+ immediately so they can notify the user. To do this, they can
+ register for pushes for the EmailDelivery type rather than the Email
+ type (as defined in Section 4).
+
+
+
+Jenkins & Newman Standards Track [Page 8]
+
+RFC 8621 JMAP Mail August 2019
+
+
+1.5.1. Example
+
+ The client has registered for push notifications (see [RFC8620]) just
+ for the EmailDelivery type. The user marks an Email as read on
+ another device, causing the state string for the Email type to
+ change; however, as nothing new was added to the store, the
+ EmailDelivery state does not change and nothing is pushed to the
+ client. A new message arrives in the user's inbox, again causing the
+ Email state to change. This time, the EmailDelivery state also
+ changes, and a StateChange object is pushed to the client with the
+ new state string. The client may then resync to fetch the new Email
+ immediately.
+
+1.6. Ids
+
+ If a JMAP Mail server also provides an IMAP interface to the data and
+ supports IMAP Extension for Object Identifiers [RFC8474], the ids
+ SHOULD be the same for Mailbox, Thread, and Email objects in JMAP.
+
+2. Mailboxes
+
+ 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
+ Mailboxes.
+
+ A *Mailbox* object has the following properties:
+
+ o id: "Id" (immutable; server-set)
+
+ The id of the Mailbox.
+
+ o name: "String"
+
+ 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
+ MUST NOT be a loop.
+
+ 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
+ localised).
+
+ 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
+ roles.
+
+ 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
+ this Mailbox.
+
+ 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
+ Mailboxes.
+
+ 2. Emails that are *not* in the trash are ignored when
+ calculating the "unreadThreads" count for the trash Mailbox.
+
+ The result of this is that Emails in the trash are treated as
+ though they are in a separate Thread for the purposes of unread
+ counts. It is expected that clients will hide Emails in the trash
+ when viewing a Thread in another Mailbox, and vice versa. This
+ allows you to delete a single Email to the trash out of a Thread.
+
+ 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
+
+
+ * mayRename: "Boolean"
+
+ 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).
+
+ * mayDelete: "Boolean"
+
+ The user may delete the Mailbox itself. Corresponds to IMAP
+ ACL "x" (although this covers both rename and delete
+ permissions).
+
+ * maySubmit: "Boolean"
+
+ 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
+ a shared account).
+
+ 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
+
+
+2.1. Mailbox/get
+
+ This is a standard "/get" method as described in [RFC8620],
+ Section 5.1. The "ids" argument may be "null" to fetch all at once.
+
+2.2. Mailbox/changes
+
+ 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
+ MUST just be null.
+
+ Since counts frequently change but other properties are generally
+ only changed rarely, the server can help the client optimise data
+ transfer by keeping track of changes to Email/Thread counts separate
+ from other state changes. The "updatedProperties" array may be used
+ directly via a back-reference in a subsequent "Mailbox/get" call in
+ the same request, so only these properties are returned if nothing
+ else has changed.
+
+2.3. Mailbox/query
+
+ 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
+ and B:
+
+ * If A is an ancestor of B, it always comes first regardless of
+ the sort comparators. Similarly, if A is descendant of B, then
+ B always comes first.
+
+ * 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
+ comparators.
+
+
+
+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
+ may be omitted:
+
+ o parentId: "Id|null"
+
+ The Mailbox "parentId" property must match the given value
+ exactly.
+
+ o name: "String"
+
+ The Mailbox "name" property contains the given string.
+
+ o role: "String|null"
+
+ 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
+ "role" property.
+
+ 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:
+
+ o "sortOrder"
+
+ o "name"
+
+2.4. Mailbox/queryChanges
+
+ This is a standard "/queryChanges" method as described in [RFC8620],
+ Section 5.6.
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 15]
+
+RFC 8621 JMAP Mail August 2019
+
+
+2.5. Mailbox/set
+
+ 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
+ Mailbox is destroyed.
+
+ The following extra SetError types are defined:
+
+ For "destroy":
+
+ o "mailboxHasChild": The Mailbox still has at least one child
+ Mailbox. The client MUST remove these before it can delete the
+ parent Mailbox.
+
+ 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
+
+
+2.6. Example
+
+ Fetching all Mailboxes in an account:
+
+ [[ "Mailbox/get", {
+ "accountId": "u33084183",
+ "ids": null
+ }, "0" ]]
+
+ And the response:
+
+ [[ "Mailbox/get", {
+ "accountId": "u33084183",
+ "state": "78540",
+ "list": [{
+ "id": "MB23cfa8094c0f41e6",
+ "name": "Inbox",
+ "parentId": null,
+ "role": "inbox",
+ "sortOrder": 10,
+ "totalEmails": 16307,
+ "unreadEmails": 13905,
+ "totalThreads": 5833,
+ "unreadThreads": 5128,
+ "myRights": {
+ "mayAddItems": true,
+ "mayRename": false,
+ "maySubmit": true,
+ "mayDelete": false,
+ "maySetKeywords": true,
+ "mayRemoveItems": true,
+ "mayCreateChild": true,
+ "maySetSeen": true,
+ "mayReadItems": true
+ },
+ "isSubscribed": true
+ }, {
+ "id": "MB674cc24095db49ce",
+ "name": "Important mail",
+ ...
+ }, ... ],
+ "notFound": []
+ }, "0" ]]
+
+
+
+
+
+
+
+
+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
+ this:
+
+ [[ "Mailbox/changes", {
+ "accountId": "u33084183",
+ "sinceState": "78540"
+ }, "0" ],
+ [ "Mailbox/get", {
+ "accountId": "u33084183",
+ "#ids": {
+ "resultOf": "0",
+ "name": "Mailbox/changes",
+ "path": "/created"
+ }
+ }, "1" ],
+ [ "Mailbox/get", {
+ "accountId": "u33084183",
+ "#ids": {
+ "resultOf": "0",
+ "name": "Mailbox/changes",
+ "path": "/updated"
+ },
+ "#properties": {
+ "resultOf": "0",
+ "name": "Mailbox/changes",
+ "path": "/updatedProperties"
+ }
+ }, "2" ]]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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
+ something like this:
+
+ [[ "Mailbox/changes", {
+ "accountId": "u33084183",
+ "oldState": "78541",
+ "newState": "78542",
+ "hasMoreChanges": false,
+ "updatedProperties": [
+ "totalEmails", "unreadEmails",
+ "totalThreads", "unreadThreads"
+ ],
+ "created": [],
+ "updated": ["MB23cfa8094c0f41e6"],
+ "destroyed": []
+ }, "0" ],
+ [ "Mailbox/get", {
+ "accountId": "u33084183",
+ "state": "78542",
+ "list": [],
+ "notFound": []
+ }, "1" ],
+ [ "Mailbox/get", {
+ "accountId": "u33084183",
+ "state": "78542",
+ "list": [{
+ "id": "MB23cfa8094c0f41e6",
+ "totalEmails": 16307,
+ "unreadEmails": 13903,
+ "totalThreads": 5833,
+ "unreadThreads": 5127
+ }],
+ "notFound": []
+ }, "2" ]]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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
+ another:
+
+ [[ "Mailbox/set", {
+ "accountId": "u33084183",
+ "ifInState": "78542",
+ "update": {
+ "MB674cc24095db49ce": {
+ "name": "Maybe important mail"
+ }
+ },
+ "destroy": [ "MB23cfa8094c0f41e6" ]
+ }, "0" ]]
+
+ Suppose the rename succeeds, but we don't have permission to destroy
+ the Mailbox we tried to destroy; we might get back:
+
+ [[ "Mailbox/set", {
+ "accountId": "u33084183",
+ "oldState": "78542",
+ "newState": "78549",
+ "updated": {
+ "MB674cc24095db49ce": null
+ },
+ "notDestroyed": {
+ "MB23cfa8094c0f41e6": {
+ "type": "forbidden"
+ }
+ }
+ }, "0" ]]
+
+3. Threads
+
+ Replies are grouped together with the original message to form a
+ Thread. In JMAP, a Thread is simply a flat list of Emails, ordered
+ by date. Every Email MUST belong to a Thread, even if it is the only
+ Email in the Thread.
+
+ The exact algorithm for determining whether two Emails belong to the
+ same Thread is not mandated in this spec to allow for compatibility
+ with different existing systems. For new implementations, it is
+ suggested that two messages belong in the same Thread if both of the
+ following conditions apply:
+
+ 1. An identical message id [RFC5322] appears in both messages in any
+ of the Message-Id, In-Reply-To, and References header fields.
+
+
+
+
+
+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
+ conversation.
+
+ If messages are delivered out of order for some reason, a user may
+ have two Emails in the same Thread but without headers that associate
+ them with each other. The arrival of a third Email may provide the
+ missing references to join them all together into a single Thread.
+ Since the "threadId" of an Email is immutable, if the server wishes
+ to merge the Threads, it MUST handle this by deleting and reinserting
+ (with a new Email id) the Emails that change "threadId".
+
+ A *Thread* object has the following properties:
+
+ o id: "Id" (immutable; server-set)
+
+
+ The id of the Thread.
+
+ 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
+ id is recommended).
+
+ The following JMAP methods are supported.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 21]
+
+RFC 8621 JMAP Mail August 2019
+
+
+3.1. Thread/get
+
+ This is a standard "/get" method as described in [RFC8620],
+ Section 5.1.
+
+3.1.1. Example
+
+ Request:
+
+ [[ "Thread/get", {
+ "accountId": "acme",
+ "ids": ["f123u4", "f41u44"]
+ }, "#1" ]]
+
+ with response:
+
+ [[ "Thread/get", {
+ "accountId": "acme",
+ "state": "f6a7e214",
+ "list": [
+ {
+ "id": "f123u4",
+ "emailIds": [ "eaa623", "f782cbb"]
+ },
+ {
+ "id": "f41u44",
+ "emailIds": [ "82cf7bb" ]
+ }
+ ],
+ "notFound": []
+ }, "#1" ]]
+
+3.2. Thread/changes
+
+ This is a standard "/changes" method as described in [RFC8620],
+ Section 5.2.
+
+4. Emails
+
+ An *Email* object is a representation of a message [RFC5322], which
+ allows clients to avoid the complexities of MIME parsing, transfer
+ encoding, and character encoding.
+
+
+
+
+
+
+
+
+
+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
+ message per RFC 5322.
+
+ The body of a message is normally a MIME-encoded set of documents in
+ a tree structure. This may be arbitrarily nested, but the majority
+ of email clients present a flat model of a message body (normally
+ plaintext or HTML) with a set of attachments. Flattening the MIME
+ structure to form this model can be difficult and causes
+ inconsistency between clients. Therefore, in addition to the
+ "bodyStructure" property, which gives the full tree, the Email object
+ contains 3 alternate properties with flat lists of body parts:
+
+ 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
+ images.
+
+ 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.
+
+4.1.1. Metadata
+
+ 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
+ object MUST be true.
+
+
+
+
+
+
+
+
+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
+ attention.
+
+ * "$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
+ lowercase.
+
+ 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-
+ detection systems.
+
+ * "$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
+ server)
+
+ 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.
+
+4.1.2.1. Raw
+
+ Type: "String"
+
+ The raw octets of the header field value from the first octet
+ following the header field name terminating colon, up to but
+ excluding the header field terminating CRLF. Any standards-compliant
+ message MUST be either ASCII (RFC 5322) or UTF-8 (RFC 6532); however,
+ other encodings exist in the wild. A server SHOULD replace any octet
+ or octet run with the high bit set that violates UTF-8 syntax with
+ the unicode replacement character (U+FFFD). Any NUL octet MUST be
+ dropped.
+
+ This form will typically have a leading space, as most generated
+ messages insert a space after the colon that terminates the header
+ field name.
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 26]
+
+RFC 8621 JMAP Mail August 2019
+
+
+4.1.2.2. Text
+
+ Type: "String"
+
+ The header field value with:
+
+ 1. White space unfolded (as defined in [RFC5322], Section 2.2.3).
+
+ 2. The terminating CRLF at the end of the value removed.
+
+ 3. Any SP characters at the beginning of the value removed.
+
+ 4. Any syntactically correct encoded sections [RFC2047] with a known
+ character set decoded. Any NUL octets or control characters
+ encoded per [RFC2047] are dropped from the decoded value. Any
+ text that looks like syntax per [RFC2047] but violates placement
+ or white space rules per [RFC2047] MUST NOT be decoded.
+
+ 5. The resulting unicode converted to Normalization Form C (NFC)
+ form.
+
+ If any decodings fail, the parser SHOULD insert a unicode replacement
+ character (U+FFFD) and attempt to continue as much as possible.
+
+ To prevent obviously nonsense behaviour, which can lead to
+ interoperability issues, this form may only be fetched or set for the
+ following header fields:
+
+ o Subject
+
+ o Comments
+
+ o Keywords
+
+ o List-Id
+
+ o Any header field not defined in [RFC5322] or [RFC2369]
+
+4.1.2.3. Addresses
+
+ Type: "EmailAddress[]"
+
+ The header field is parsed as an "address-list" value, as specified
+ in [RFC5322], Section 3.4, into the "EmailAddress[]" type. There is
+ an EmailAddress item for each "mailbox" parsed from the "address-
+ list". Group and comment information is discarded.
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 27]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ An *EmailAddress* object has the following properties:
+
+ o name: "String|null"
+
+ The "display-name" of the "mailbox" [RFC5322]. If this is a
+ "quoted-string":
+
+ 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.
+
+ o email: "String"
+
+ 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?=
+ <john@example.com>;
+
+ would be parsed as:
+
+ [
+ { "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 From
+
+ o Sender
+
+ o Reply-To
+
+ o To
+
+ o Cc
+
+ o Bcc
+
+ o Resent-From
+
+ o Resent-Sender
+
+ o Resent-Reply-To
+
+ o Resent-To
+
+ o Resent-Cc
+
+ o Resent-Bcc
+
+ 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
+ uniform type.
+
+
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 29]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ An *EmailAddressGroup* object has the following properties:
+
+ o name: "String|null"
+
+ 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
+ EmailAddress objects.
+
+ 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?=
+ <john@example.com>;
+
+ would be parsed as:
+
+ [
+ { "name": null, "addresses": [
+ { "name": "James Smythe", "email": "james@example.com" }
+ ]},
+ { "name": "Friends", "addresses": [
+ { "name": null, "email": "jane@example.com" },
+ { "name": "John 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
+
+
+4.1.2.5. MessageIds
+
+ Type: "String[]|null"
+
+ The header field is parsed as a list of "msg-id" values, as specified
+ in [RFC5322], Section 3.6.4, into the "String[]" type. Comments and/
+ or folding white space (CFWS) and surrounding angle brackets ("<>")
+ are removed. If parsing fails, the value is null.
+
+ To prevent obviously nonsense behaviour, which can lead to
+ interoperability issues, this form may only be fetched or set for the
+ following header fields:
+
+ o Message-ID
+
+ o In-Reply-To
+
+ o References
+
+ o Resent-Message-ID
+
+ o Any header field not defined in [RFC5322] or [RFC2369]
+
+4.1.2.6. Date
+
+ Type: "Date|null"
+
+ The header field is parsed as a "date-time" value, as specified in
+ [RFC5322], Section 3.3, into the "Date" type. If parsing fails, the
+ value is null.
+
+ To prevent obviously nonsense behaviour, which can lead to
+ interoperability issues, this form may only be fetched or set for the
+ following header fields:
+
+ o Date
+
+ o Resent-Date
+
+ o Any header field not defined in [RFC5322] or [RFC2369]
+
+
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 31]
+
+RFC 8621 JMAP Mail August 2019
+
+
+4.1.2.7. URLs
+
+ Type: "String[]|null"
+
+ The header field is parsed as a list of URLs, as described in
+ [RFC2369], into the "String[]" type. Values do not include the
+ surrounding angle brackets or any comments in the header 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 List-Help
+
+ o List-Unsubscribe
+
+ o List-Subscribe
+
+ o List-Post
+
+ o List-Owner
+
+ o List-Archive
+
+ 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
+ following properties:
+
+ * name: "String"
+
+ The header "field name" as defined in [RFC5322], with the same
+ capitalization that it has in the message.
+
+ * value: "String"
+
+ 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:
+
+ o :as{header-form}
+
+ 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
+ value is in Raw form.
+
+ o :all
+
+ 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
+ insensitively).
+
+ 2. For each instance, parse the header field value in the Addresses
+ form.
+
+ 3. The result is of type "EmailAddress[][]" -- each item in the
+ array corresponds to the parsed value (which is itself an array)
+ of the Resent-To header field instance.
+
+
+
+Jenkins & Newman Standards Track [Page 33]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ The following convenience properties are also specified for the Email
+ object:
+
+ 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-
+ To:asMessageIds".
+
+ 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-
+ To:asAddresses".
+
+ 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
+ server time)
+
+ The value is identical to the value of "header:Date:asDate".
+
+4.1.4. Body Parts
+
+ 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
+ "multipart/*".
+
+ o blobId: "Id|null"
+
+ 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.
+
+ o size: "UnsignedInt"
+
+ 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.
+
+ o name: "String|null"
+
+ 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
+
+
+ o type: "String"
+
+ 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
+ are stripped.
+
+ o cid: "String|null"
+
+ 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
+ child.
+
+ 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
+ data of the message:
+
+ 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
+ "multipart/*".
+
+ 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
+ following properties:
+
+ * value: "String"
+
+ 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
+ encountered.
+
+ 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
+ EmailBodyPart.
+
+ * isEncodingProblem: "Boolean" (default: false)
+
+ This is true if malformed sections were found while decoding
+ the charset, the charset was unknown, or the content-transfer-
+ encoding was unknown.
+
+ * 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
+ charset.
+
+
+
+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
+ available.
+
+ 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
+ available.
+
+ 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
+ "htmlBody"
+
+ * 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
+ and the "blobId".
+
+ 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
+ useful preview.
+
+ 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 server.
+
+ The exact algorithm for decomposing bodyStructure into textBody,
+ htmlBody, and attachments part lists is not mandated, as this is a
+ quality-of-service implementation issue and likely to require
+ workarounds for malformed content discovered over time. However, the
+ following algorithm (expressed here in JavaScript) is suggested as a
+ starting point, based on real-world experience:
+
+ function isInlineMediaType ( type ) {
+ return type.startsWith( 'image/' ) ||
+ type.startsWith( 'audio/' ) ||
+ type.startsWith( 'video/' );
+ }
+
+ function parseStructure ( parts, multipartType, inAlternative,
+ htmlBody, textBody, attachments ) {
+
+ // For multipartType == alternative
+ let textLength = textBody ? textBody.length : -1;
+ let htmlLength = htmlBody ? htmlBody.length : -1;
+
+ for ( let i = 0; i < parts.length; i += 1 ) {
+ let part = parts[i];
+ let isMultipart = part.type.startsWith( 'multipart/' );
+ // Is this a body part rather than an attachment
+ let isInline = part.disposition != "attachment" &&
+ // Must be one of the allowed body types
+ ( part.type == "text/plain" ||
+ part.type == "text/html" ||
+ isInlineMediaType( part.type ) ) &&
+
+
+
+
+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
+ ( i === 0 ||
+ ( multipartType != "related" &&
+ ( isInlineMediaType( part.type ) || !part.name ) ) );
+
+ if ( isMultipart ) {
+ let subMultiType = part.type.split( '/' )[1];
+ parseStructure( part.subParts, subMultiType,
+ inAlternative || ( subMultiType == 'alternative' ),
+ htmlBody, textBody, attachments );
+ } else if ( isInline ) {
+ if ( multipartType == 'alternative' ) {
+ switch ( part.type ) {
+ case 'text/plain':
+ textBody.push( part );
+ break;
+ case 'text/html':
+ htmlBody.push( part );
+ break;
+ default:
+ attachments.push( part );
+ break;
+ }
+ continue;
+ } else if ( inAlternative ) {
+ if ( part.type == 'text/plain' ) {
+ htmlBody = null;
+ }
+ if ( part.type == 'text/html' ) {
+ textBody = null;
+ }
+ }
+ if ( textBody ) {
+ textBody.push( part );
+ }
+ if ( htmlBody ) {
+ htmlBody.push( part );
+ }
+ if ( ( !textBody || !htmlBody ) &&
+ isInlineMediaType( part.type ) ) {
+ attachments.push( part );
+ }
+ } else {
+ attachments.push( part );
+ }
+ }
+
+
+
+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] );
+ }
+ }
+ }
+ }
+
+ // Usage:
+ let htmlBody = [];
+ let textBody = [];
+ let attachments = [];
+
+ parseStructure( [ bodyStructure ], 'mixed', false,
+ htmlBody, textBody, attachments );
+
+ For instance, consider a message with both text and HTML versions
+ that has gone through a list software manager that attaches a header
+ and footer. It might have a MIME structure something like:
+
+ multipart/mixed
+ text/plain, content-disposition=inline - A
+ multipart/mixed
+ multipart/alternative
+ multipart/mixed
+ text/plain, content-disposition=inline - B
+ image/jpeg, content-disposition=inline - C
+ text/plain, content-disposition=inline - D
+ multipart/related
+ text/html - E
+ image/jpeg - F
+ image/jpeg, content-disposition=attachment - G
+ application/x-excel - H
+ message/rfc822 - J
+ text/plain, content-disposition=inline - K
+
+
+
+
+
+
+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 ]
+
+4.2. Email/get
+
+ 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
+ things).
+
+
+
+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:
+
+ o id
+
+ o blobId
+
+ o threadId
+
+ o mailboxIds
+
+ o keywords
+
+ o size
+
+ o receivedAt
+
+ o messageId
+
+ o inReplyTo
+
+ o sender
+
+ o from
+
+ o to
+
+ o cc
+
+ o bcc
+
+ o replyTo
+
+ o subject
+
+ o sentAt
+
+ o hasAttachment
+
+ o preview
+
+
+
+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
+ data.
+
+ As specified above, parsed forms of headers may only be used on
+ appropriate header fields. Attempting to fetch a form that is
+ forbidden (e.g., "header:From:asDate") MUST result in the method call
+ being rejected with an "invalidArguments" error.
+
+ Where a specific header field is requested as a property, the
+ capitalization of the property name in the response MUST be identical
+ to that used in the request.
+
+4.2.1. Example
+
+ Request:
+
+ [[ "Email/get", {
+ "ids": [ "f123u456", "f123u457" ],
+ "properties": [ "threadId", "mailboxIds", "from", "subject",
+ "receivedAt", "header:List-POST:asURLs",
+ "htmlBody", "bodyValues" ],
+ "bodyProperties": [ "partId", "blobId", "size", "type" ],
+ "fetchHTMLBodyValues": true,
+ "maxBodyValueBytes": 256
+ }, "#1" ]]
+
+ and response:
+
+ [[ "Email/get", {
+ "accountId": "abc",
+ "state": "41234123231",
+ "list": [
+ {
+ "id": "f123u457",
+ "threadId": "ef1314a",
+ "mailboxIds": { "f123": true },
+ "from": [{ "name": "Joe Bloggs", "email": "joe@example.com" }],
+ "subject": "Dinner on Thursday?",
+ "receivedAt": "2013-10-13T14:12:00Z",
+ "header:List-POST:asURLs": [
+ "mailto:partytime@lists.example.com"
+ ],
+ "htmlBody": [{
+ "partId": "1",
+ "blobId": "B841623871",
+ "size": 283331,
+ "type": "text/html"
+
+
+
+Jenkins & Newman Standards Track [Page 44]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ }, {
+ "partId": "2",
+ "blobId": "B319437193",
+ "size": 10343,
+ "type": "text/plain"
+ }],
+ "bodyValues": {
+ "1": {
+ "isEncodingProblem": false,
+ "isTruncated": true,
+ "value": "<html><body><p>Hello ..."
+ },
+ "2": {
+ "isEncodingProblem": false,
+ "isTruncated": false,
+ "value": "-- Sent by your friendly mailing list ..."
+ }
+ }
+ }
+ ],
+ "notFound": [ "f123u456" ]
+ }, "#1" ]]
+
+4.3. Email/changes
+
+ This is a standard "/changes" method as described in [RFC8620],
+ Section 5.2. If generating intermediate states for a large set of
+ changes, it is recommended that newer changes be returned first, as
+ these are generally of more interest to users.
+
+4.4. Email/query
+
+ 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
+ any given Thread.
+
+ 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
+
+
+4.4.1. Filtering
+
+ A *FilterCondition* object has the following properties, any of which
+ may be omitted:
+
+ o inMailbox: "Id"
+
+ A Mailbox id. An Email must be in this Mailbox to match the
+ condition.
+
+ 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.
+
+ o before: "UTCDate"
+
+ The "receivedAt" date-time of the Email must be before this date-
+ time to match the condition.
+
+ o after: "UTCDate"
+
+ 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
+ match the condition.
+
+ 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.
+
+ o hasKeyword: "String"
+
+ This Email must have the given keyword to match the condition.
+
+ o notKeyword: "String"
+
+ 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.
+
+ o text: "String"
+
+ 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.
+
+ o from: "String"
+
+ Looks for the text in the From header field of the message.
+
+ o to: "String"
+
+ Looks for the text in the To header field of the message.
+
+ o cc: "String"
+
+ Looks for the text in the Cc header field of the message.
+
+ o bcc: "String"
+
+ Looks for the text in the Bcc header field of the message.
+
+ o subject: "String"
+
+ Looks for the text in the Subject header field of the message.
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 47]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ o body: "String"
+
+ 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.
+
+ o header: "String[]"
+
+ 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
+ to the following:
+
+ o Any syntactically correct encoded sections [RFC2047] of header
+ fields with a known encoding SHOULD be decoded before attempting
+ to match text.
+
+ 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").
+
+4.4.2. Sorting
+
+ 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
+ object.
+
+ 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
+ be the empty string.
+
+ 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
+ Comparator object.
+
+ 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
+ Comparator object.
+
+ The server MAY support sorting based on other properties as well. A
+ client can discover which properties are supported by inspecting the
+ account's "capabilities" object (see Section 1.3).
+
+ Example sort:
+
+ [{
+ "property": "someInThreadHaveKeyword",
+ "keyword": "$flagged",
+ "isAscending": false
+ }, {
+ "property": "subject",
+ "collation": "i;ascii-casemap"
+ }, {
+ "property": "receivedAt",
+ "isAscending": false
+ }]
+
+ This would sort Emails in flagged Threads first (the Thread is
+ considered flagged if any Email within it is flagged), in subject
+ order second, and then from newest first for messages with the same
+ subject. If two Emails have identical values for all three
+ properties, then the order is server dependent but must be stable.
+
+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".
+
+4.6. Email/set
+
+ This is a standard "/set" method as described in [RFC8620],
+ Section 5.3. The "Email/set" method encompasses:
+
+ o Creating a draft
+
+ o Changing the keywords of an Email (e.g., unread/flagged status)
+
+ o Adding/removing an Email to/from Mailboxes (moving a message)
+
+ o Deleting Emails
+
+ 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
+ "bodyValues" property.
+
+ * 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
+ itself).
+
+ * 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
+ object.
+
+ The following extra SetError types are defined:
+
+ For "create":
+
+ 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
+ server.
+
+ 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.
+
+4.7. Email/copy
+
+ This is a standard "/copy" method as described in [RFC8620],
+ Section 5.4, except only the "mailboxIds", "keywords", and
+ "receivedAt" properties may be set during the copy. This method
+ cannot modify the message represented by the Email.
+
+ The server MAY forbid two Email objects with identical message
+ content [RFC5322], or even just with the same Message-ID [RFC5322],
+ to coexist within an account; if the target account already has the
+ Email, the copy will be rejected with a standard "alreadyExists"
+ error.
+
+ For successfully copied Email objects, the "created" response
+ contains the "id", "blobId", "threadId", and "size" properties of the
+ new object.
+
+
+
+
+Jenkins & Newman Standards Track [Page 53]
+
+RFC 8621 JMAP Mail August 2019
+
+
+4.8. Email/import
+
+ The "Email/import" method adds messages [RFC5322] to the set of
+ Emails in an account. The server MUST support messages with Email
+ Address Internationalization (EAI) headers [RFC6532]. The messages
+ must first be uploaded as blobs using the standard upload mechanism.
+ The method takes the following arguments:
+
+ o accountId: "Id"
+
+ 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:
+
+ o blobId: "Id"
+
+ 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
+ Mailbox MUST be given.
+
+ 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"
+ SetError.
+
+ If the blob referenced is not a valid message [RFC5322], the server
+ MAY modify the message to fix errors (such as removing NUL octets or
+ fixing invalid headers). If it does this, the "blobId" on the
+ response MUST represent the new representation and therefore be
+ different to the "blobId" on the EmailImport object. Alternatively,
+ the server MAY reject the import with an "invalidEmail" SetError.
+
+ The response has the following arguments:
+
+ o accountId: "Id"
+
+ 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.
+
+ o newState: "String"
+
+ The state string that will now be returned by "Email/get" on this
+ account.
+
+ 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.
+
+4.9. Email/parse
+
+ This method allows you to parse blobs as messages [RFC5322] to get
+ Email objects. The server MUST support messages with EAI headers
+ [RFC6532]. This can be used to parse and display attached messages
+ without having to import them as top-level Email objects in the mail
+ store in their own right.
+
+ The following metadata properties on the Email objects will be null
+ if requested:
+
+ o id
+
+ o mailboxIds
+
+ o keywords
+
+ o receivedAt
+
+ 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:
+
+ o accountId: "Id"
+
+ The id of the account to use.
+
+ o blobIds: "Id[]"
+
+ 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
+ things).
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 57]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ The response has the following arguments:
+
+ o accountId: "Id"
+
+ 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.
+
+4.10. Examples
+
+ A client logs in for the first time. It first fetches the set of
+ Mailboxes. Now it will display the inbox to the user, which we will
+ presume has Mailbox id "fb666a55". The inbox may be (very!) large,
+ but the user's screen is only so big, so the client can just load the
+ Threads it needs to fill the screen and then load in more only when
+ the user scrolls. The client sends this request:
+
+ [[ "Email/query",{
+ "accountId": "ue150411c",
+ "filter": {
+ "inMailbox": "fb666a55"
+ },
+ "sort": [{
+ "isAscending": false,
+ "property": "receivedAt"
+ }],
+ "collapseThreads": true,
+
+
+
+Jenkins & Newman Standards Track [Page 58]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ "position": 0,
+ "limit": 30,
+ "calculateTotal": true
+ }, "0" ],
+ [ "Email/get", {
+ "accountId": "ue150411c",
+ "#ids": {
+ "resultOf": "0",
+ "name": "Email/query",
+ "path": "/ids"
+ },
+ "properties": [
+ "threadId"
+ ]
+ }, "1" ],
+ [ "Thread/get", {
+ "accountId": "ue150411c",
+ "#ids": {
+ "resultOf": "1",
+ "name": "Email/get",
+ "path": "/list/*/threadId"
+ }
+ }, "2" ],
+ [ "Email/get", {
+ "accountId": "ue150411c",
+ "#ids": {
+ "resultOf": "2",
+ "name": "Thread/get",
+ "path": "/list/*/emailIds"
+ },
+ "properties": [
+ "threadId",
+ "mailboxIds",
+ "keywords",
+ "hasAttachment",
+ "from",
+ "subject",
+ "receivedAt",
+ "size",
+ "preview"
+ ]
+ }, "3" ]]
+
+
+
+
+
+
+
+
+
+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
+ unique Threads).
+
+ "1": Now we use a back-reference to fetch the Thread ids for each of
+ these Email ids.
+
+ "2": Another back-reference fetches the Thread object for each of
+ these Thread ids.
+
+ "3": Finally, we fetch the information we need to display the Mailbox
+ listing (but no more!) for every Email in each of these 30 Threads.
+ The client may aggregate this data for display, for example, by
+ showing the Thread as "flagged" if any of the Emails in it has the
+ "$flagged" keyword.
+
+ The response from the server may look something like this:
+
+ [[ "Email/query", {
+ "accountId": "ue150411c",
+ "queryState": "09aa9a075588-780599:0",
+ "canCalculateChanges": true,
+ "position": 0,
+ "total": 115,
+ "ids": [ "Ma783e5cdf5f2deffbc97930a",
+ "M9bd17497e2a99cb345fc1d0a", ... ]
+ }, "0" ],
+ [ "Email/get", {
+ "accountId": "ue150411c",
+ "state": "780599",
+ "list": [{
+ "id": "Ma783e5cdf5f2deffbc97930a",
+ "threadId": "T36703c2cfe9bd5ed"
+ }, {
+ "id": "M9bd17497e2a99cb345fc1d0a",
+ "threadId": "T0a22ad76e9c097a1"
+ }, ... ],
+ "notFound": []
+ }, "1" ],
+ [ "Thread/get", {
+ "accountId": "ue150411c",
+ "state": "22a8728b",
+ "list": [{
+ "id": "T36703c2cfe9bd5ed",
+ "emailIds": [ "Ma783e5cdf5f2deffbc97930a" ]
+
+
+
+Jenkins & Newman Standards Track [Page 60]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ }, {
+ "id": "T0a22ad76e9c097a1",
+ "emailIds": [ "M3b568670a63e5d100f518fa5",
+ "M9bd17497e2a99cb345fc1d0a" ]
+ }, ... ],
+ "notFound": []
+ }, "2" ],
+ [ "Email/get", {
+ "accountId": "ue150411c",
+ "state": "780599",
+ "list": [{
+ "id": "Ma783e5cdf5f2deffbc97930a",
+ "threadId": "T36703c2cfe9bd5ed",
+ "mailboxIds": {
+ "fb666a55": true
+ },
+ "keywords": {
+ "$seen": true,
+ "$flagged": true
+ },
+ "hasAttachment": true,
+ "from": [{
+ "email": "jdoe@example.com",
+ "name": "Jane Doe"
+ }],
+ "subject": "The Big Reveal",
+ "receivedAt": "2018-06-27T00:20:35Z",
+ "size": 175047,
+ "preview": "As you may be aware, we are required to prepare a
+ presentation where we wow a panel of 5 random members of the
+ public, on or before 30 June each year. We have drafted..."
+ },
+ ...
+ ],
+ "notFound": []
+ }, "3" ]]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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:
+
+ [[ "Email/set", {
+ "accountId": "ue150411c",
+ "update": {
+ "Ma783e5cdf5f2deffbc97930a": {
+ "keywords/$seen": null
+ }
+ }
+ }, "0" ]]
+
+ The server applies this and sends the success response:
+
+ [[ "Email/set", {
+ "accountId": "ue150411c",
+ "oldState": "780605",
+ "newState": "780606",
+ "updated": {
+ "Ma783e5cdf5f2deffbc97930a": null
+ },
+ ...
+ }, "0" ]]
+
+ The user also deletes a few Emails, and then a new message arrives.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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:
+
+ [[ "Email/changes", {
+ "accountId": "ue150411c",
+ "sinceState": "780605",
+ "maxChanges": 50
+ }, "3" ],
+ [ "Email/queryChanges", {
+ "accountId": "ue150411c",
+ "filter": {
+ "inMailbox": "fb666a55"
+ },
+ "sort": [{
+ "property": "receivedAt",
+ "isAscending": false
+ }],
+ "collapseThreads": true,
+ "sinceQueryState": "09aa9a075588-780599:0",
+ "upToId": "Mc2781d5e856a908d8a35a564",
+ "maxChanges": 25,
+ "calculateTotal": true
+ }, "11" ]]
+
+ The response:
+
+ [[ "Email/changes", {
+ "accountId": "ue150411c",
+ "oldState": "780605",
+ "newState": "780800",
+ "hasMoreChanges": false,
+ "created": [ "Me8de6c9f6de198239b982ea2" ],
+ "updated": [ "Ma783e5cdf5f2deffbc97930a" ],
+ "destroyed": [ "M9bd17497e2a99cb345fc1d0a", ... ]
+ }, "3" ],
+ [ "Email/queryChanges", {
+ "accountId": "ue150411c",
+ "oldQueryState": "09aa9a075588-780599:0",
+ "newQueryState": "e35e9facf117-780615:0",
+ "added": [{
+ "id": "Me8de6c9f6de198239b982ea2",
+ "index": 0
+ }],
+ "removed": [ "M9bd17497e2a99cb345fc1d0a" ],
+ "total": 115
+ }, "11" ]]
+
+
+
+
+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:
+
+ [[ "Email/set", {
+ "accountId": "ue150411c",
+ "create": {
+ "k192": {
+ "mailboxIds": {
+ "2ea1ca41b38e": true
+ },
+ "keywords": {
+ "$seen": true,
+ "$draft": true
+ },
+ "from": [{
+ "name": "Joe Bloggs",
+ "email": "joe@example.com"
+ }],
+ "subject": "World domination",
+ "receivedAt": "2018-07-10T01:03:11Z",
+ "sentAt": "2018-07-10T11:03:11+10:00",
+ "bodyStructure": {
+ "type": "text/plain",
+ "partId": "bd48",
+ "header:Content-Language": "en"
+ },
+ "bodyValues": {
+ "bd48": {
+ "value": "I have the most brilliant plan. Let me tell
+ you all about it. What we do is, we",
+ "isTruncated": false
+ }
+ }
+ }
+ }
+ }, "0" ]]
+
+
+
+Jenkins & Newman Standards Track [Page 64]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ The server creates the message and sends the success response:
+
+ [[ "Email/set", {
+ "accountId": "ue150411c",
+ "oldState": "780823",
+ "newState": "780839",
+ "created": {
+ "k192": {
+ "id": "Mf40b5f831efa7233b9eb1c7f",
+ "blobId": "Gf40b5f831efa7233b9eb1c7f8f97d84eeeee64f7",
+ "threadId": "Td957e72e89f516dc",
+ "size": 359
+ }
+ },
+ ...
+ }, "0" ]]
+
+ The message created on the server looks something like this:
+
+ Message-Id: <bbce0ae9-58be-4b24-ac82-deb840d58016@sloti7d1t02>
+ User-Agent: Cyrus-JMAP/3.1.6-736-gdfb8e44
+ Mime-Version: 1.0
+ Date: Tue, 10 Jul 2018 11:03:11 +1000
+ From: "Joe Bloggs" <joe@example.com>
+ Subject: World domination
+ Content-Language: en
+ Content-Type: text/plain
+
+ I have the most brilliant plan. Let me tell you all about it. What we
+ do is, we
+
+ The user adds a recipient and converts the message to HTML so they
+ can add formatting, then saves an updated draft:
+
+ [[ "Email/set", {
+ "accountId": "ue150411c",
+ "create": {
+ "k1546": {
+ "mailboxIds": {
+ "2ea1ca41b38e": true
+ },
+ "keywords": {
+ "$seen": true,
+ "$draft": true
+ },
+ "from": [{
+ "name": "Joe Bloggs",
+ "email": "joe@example.com"
+
+
+
+Jenkins & Newman Standards Track [Page 65]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ }],
+ "to": [{
+ "name": "John",
+ "email": "john@example.com"
+ }],
+ "subject": "World domination",
+ "receivedAt": "2018-07-10T01:05:08Z",
+ "sentAt": "2018-07-10T11:05:08+10:00",
+ "bodyStructure": {
+ "type": "multipart/alternative",
+ "subParts": [{
+ "partId": "a49d",
+ "type": "text/html",
+ "header:Content-Language": "en"
+ }, {
+ "partId": "bd48",
+ "type": "text/plain",
+ "header:Content-Language": "en"
+ }]
+ },
+ "bodyValues": {
+ "bd48": {
+ "value": "I have the most brilliant plan. Let me tell
+ you all about it. What we do is, we",
+ "isTruncated": false
+ },
+ "a49d": {
+ "value": "<!DOCTYPE html><html><head><title></title>
+ <style type=\"text/css\">div{font-size:16px}</style></head>
+ <body><div>I have the most <b>brilliant</b> plan. Let me
+ tell you all about it. What we do is, we</div></body>
+ </html>",
+ "isTruncated": false
+ }
+ }
+ }
+ },
+ "destroy": [ "Mf40b5f831efa7233b9eb1c7f" ]
+ }, "0" ]]
+
+
+
+
+
+
+
+
+
+
+
+
+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
+ success response:
+
+ [[ "Email/set", {
+ "accountId": "ue150411c",
+ "oldState": "780839",
+ "newState": "780842",
+ "created": {
+ "k1546": {
+ "id": "Md45b47b4877521042cec0938",
+ "blobId": "Ge8de6c9f6de198239b982ea214e0f3a704e4af74",
+ "threadId": "Td957e72e89f516dc",
+ "size": 11721
+ }
+ },
+ "destroyed": [ "Mf40b5f831efa7233b9eb1c7f" ],
+ ...
+ }, "0" ]]
+
+ The client moves this draft to a different account. The only way to
+ do this is via the "Email/copy" method. It MUST set a new
+ "mailboxIds" property, since the current value will not be valid
+ Mailbox ids in the destination account:
+
+ [[ "Email/copy", {
+ "fromAccountId": "ue150411c",
+ "accountId": "u6c6c41ac",
+ "create": {
+ "k45": {
+ "id": "Md45b47b4877521042cec0938",
+ "mailboxIds": {
+ "75a4c956": true
+ }
+ }
+ },
+ "onSuccessDestroyOriginal": true
+ }, "0" ]]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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:
+
+ [[ "Email/copy", {
+ "fromAccountId": "ue150411c",
+ "accountId": "u6c6c41ac",
+ "oldState": "7ee7e9263a6d",
+ "newState": "5a0d2447ed26",
+ "created": {
+ "k45": {
+ "id": "M138f9954a5cd2423daeafa55",
+ "blobId": "G6b9fb047cba722c48c611e79233d057c6b0b74e8",
+ "threadId": "T2f242ea424a4079a",
+ "size": 11721
+ }
+ },
+ "notCreated": null
+ }, "0" ],
+ [ "Email/set", {
+ "accountId": "ue150411c",
+ "oldState": "780842",
+ "newState": "780871",
+ "destroyed": [ "Md45b47b4877521042cec0938" ],
+ ...
+ }, "0" ]]
+
+5. Search Snippets
+
+ When doing a search on a "String" property, the client may wish to
+ show the relevant section of the body that matches the search as a
+ preview and to highlight any matching terms in both this and the
+ subject of the Email. Search snippets represent this data.
+
+ A *SearchSnippet* object has the following properties:
+
+ o emailId: "Id"
+
+ 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
+ "<mark></mark>" tags.
+
+ If the subject does not match text from the filter, this property
+ is null.
+
+ 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
+ property is null.
+
+ What is a relevant section of the body for preview is server defined.
+ If the server is unable to determine search snippets, it MUST return
+ null for both the "subject" and "preview" properties.
+
+ Note that unlike most data types, a SearchSnippet DOES NOT have a
+ property called "id".
+
+ The following JMAP method is supported.
+
+5.1. SearchSnippet/get
+
+ To fetch search snippets, make a call to "SearchSnippet/get". It
+ takes the following arguments:
+
+ o accountId: "Id"
+
+ 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
+
+
+ o emailIds: "Id[]"
+
+ The ids of the Emails to fetch snippets for.
+
+ The response has the following arguments:
+
+ o accountId: "Id"
+
+ 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
+ request.
+
+ o notFound: "Id[]|null"
+
+ An array of Email ids requested that could not be found, or null
+ if all ids were found.
+
+ As the search snippets are derived from the message content and the
+ algorithm for doing so could change over time, fetching the same
+ snippets a second time MAY return a different result. However, the
+ previous value is not considered incorrect, so there is no state
+ string or update mechanism needed.
+
+ The following additional errors may be returned instead of the
+ "SearchSnippet/get" response:
+
+ "requestTooLarge": The number of "emailIds" requested by the client
+ exceeds the maximum number the server is willing to process in a
+ single method call.
+
+ "unsupportedFilter": The server is unable to process the given
+ "filter" for any reason.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 70]
+
+RFC 8621 JMAP Mail August 2019
+
+
+5.2. Example
+
+ Here, we did an "Email/query" to search for any Email in the account
+ containing the word "foo"; now, we are fetching the search snippets
+ for some of the ids that were returned in the results:
+
+ [[ "SearchSnippet/get", {
+ "accountId": "ue150411c",
+ "filter": {
+ "text": "foo"
+ },
+ "emailIds": [
+ "M44200ec123de277c0c1ce69c",
+ "M7bcbcb0b58d7729686e83d99",
+ "M28d12783a0969584b6deaac0",
+ ...
+ ]
+ }, "0" ]]
+
+ Example response:
+
+ [[ "SearchSnippet/get", {
+ "accountId": "ue150411c",
+ "list": [{
+ "emailId": "M44200ec123de277c0c1ce69c",
+ "subject": null,
+ "preview": null
+ }, {
+ "emailId": "M7bcbcb0b58d7729686e83d99",
+ "subject": "The <mark>Foo</mark>sball competition",
+ "preview": "...year the <mark>foo</mark>sball competition will
+ be held in the Stadium de ..."
+ }, {
+ "emailId": "M28d12783a0969584b6deaac0",
+ "subject": null,
+ "preview": "...the <mark>Foo</mark>/bar method results often
+ returns &lt;1 widget rather than the complete..."
+ },
+ ...
+ ],
+ "notFound": null
+ }, "0" ]]
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 71]
+
+RFC 8621 JMAP Mail August 2019
+
+
+6. Identities
+
+ 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
+ from this Identity.
+
+ 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
+ from this Identity.
+
+ o bcc: "EmailAddress[]|null" (default: null)
+
+ The Bcc value the client SHOULD set when creating a new Email from
+ this Identity.
+
+ 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.
+
+6.1. Identity/get
+
+ This is a standard "/get" method as described in [RFC8620],
+ Section 5.1. The "ids" argument may be null to fetch all at once.
+
+6.2. Identity/changes
+
+ This is a standard "/changes" method as described in [RFC8620],
+ Section 5.2.
+
+6.3. Identity/set
+
+ This is a standard "/set" method as described in [RFC8620],
+ Section 5.3. The following extra SetError types are defined:
+
+ For "create":
+
+ o "forbiddenFrom": The user is not allowed to send from the address
+ given as the "email" property of the Identity.
+
+6.4. Example
+
+ Request:
+
+ [ "Identity/get", {
+ "accountId": "acme"
+ }, "0" ]
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 73]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ with response:
+
+ [ "Identity/get", {
+ "accountId": "acme",
+ "state": "99401312ae-11-333",
+ "list": [
+ {
+ "id": "XD-3301-222-11_22AAz",
+ "name": "Joe Bloggs",
+ "email": "joe@example.com",
+ "replyTo": null,
+ "bcc": [{
+ "name": null,
+ "email": "joe+archive@example.com"
+ }],
+ "textSignature": "-- \nJoe Bloggs\nMaster of Email",
+ "htmlSignature": "<div><b>Joe Bloggs</b></div>
+ <div>Master of Email</div>",
+ "mayDelete": false
+ },
+ {
+ "id": "XD-9911312-11_22AAz",
+ "name": "Joe B",
+ "email": "*@example.com",
+ "replyTo": null,
+ "bcc": null,
+ "textSignature": "",
+ "htmlSignature": "",
+ "mayDelete": true
+ }
+ ],
+ "notFound": []
+ }, "0" ]
+
+7. Email Submission
+
+ 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:
+
+ * mailFrom: "Address"
+
+ 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
+ string.
+
+ 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-
+ provided value.
+
+ * rcptTo: "Address[]"
+
+ 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:
+
+ * email: "String"
+
+ 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
+ applied.
+
+ 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
+ field.
+
+ 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
+ any of them.
+
+ 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
+ created.
+
+ o undoStatus: "String"
+
+ 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
+ still being retried.
+
+ This value is a map from the email address of each recipient to a
+ DeliveryStatus object.
+
+ A *DeliveryStatus* object has the following properties:
+
+ * smtpReply: "String"
+
+ 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
+ string as follows:
+
+ + 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
+ lines after the first.
+
+ + CRLF is replaced by a space.
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 77]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ For example:
+
+ 550-5.7.1 Our system has detected that this message is
+ 550 5.7.1 likely spam.
+
+ would become:
+
+ 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],
+ Section 4.2.3.
+
+ + 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.
+
+ * delivered: "String"
+
+ 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
+ channels.
+
+ * displayed: "String"
+
+ 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
+ initial value.
+
+ + "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
+ set to "yes".
+
+ The server MAY also set this property based on other feedback
+ channels.
+
+ 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/
+ report"), as received.
+
+ 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/
+ report"), as received.
+
+
+
+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
+ object.
+
+ For efficiency, a server MAY destroy EmailSubmission objects at any
+ time after the message is successfully sent or after it has finished
+ retrying to send the message. For very basic SMTP proxies, this MAY
+ be immediately after creation, as it has no way to assign a real id
+ and return the information again if fetched later.
+
+ The following JMAP methods are supported.
+
+7.1. EmailSubmission/get
+
+ This is a standard "/get" method as described in [RFC8620],
+ Section 5.1.
+
+7.2. EmailSubmission/changes
+
+ This is a standard "/changes" method as described in [RFC8620],
+ Section 5.2.
+
+7.3. EmailSubmission/query
+
+ This is a standard "/query" method as described in [RFC8620],
+ Section 5.5.
+
+ A *FilterCondition* object has the following properties, any of which
+ may be omitted:
+
+ o identityIds: "Id[]"
+
+ The EmailSubmission "identityId" property must be in this list to
+ match the condition.
+
+ o emailIds: "Id[]"
+
+ The EmailSubmission "emailId" property must be in this list to
+ match the condition.
+
+ o threadIds: "Id[]"
+
+ The EmailSubmission "threadId" property must be in this list to
+ match the condition.
+
+
+
+
+Jenkins & Newman Standards Track [Page 80]
+
+RFC 8621 JMAP Mail August 2019
+
+
+ o undoStatus: "String"
+
+ The EmailSubmission "undoStatus" property must be identical to the
+ value given to match the condition.
+
+ o before: "UTCDate"
+
+ The "sendAt" property of the EmailSubmission object must be before
+ this date-time to match the condition.
+
+ o after: "UTCDate"
+
+ 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
+ sorting:
+
+ o "emailId"
+
+ o "threadId"
+
+ o "sentAt"
+
+7.4. EmailSubmission/queryChanges
+
+ This is a standard "/queryChanges" method as described in [RFC8620],
+ Section 5.6.
+
+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"
+ response.
+
+ An Email is sent by creating an EmailSubmission object. When
+ processing each create, the server must check that the message is
+ valid, and the user has sufficient authorisation to send it. If the
+ creation succeeds, the message will be sent to the recipients given
+ in the envelope "rcptTo" parameter. The server MUST remove any Bcc
+ header field present on the message during delivery. The server MAY
+ add or remove other header fields from the submitted message or make
+ further alterations in accordance with the server's policy during
+ delivery.
+
+ If the referenced Email is destroyed at any point after the
+ EmailSubmission object is created, this MUST NOT change the behaviour
+ of the submission (i.e., it does not cancel a future send). The
+ "emailId" and "threadId" properties of the EmailSubmission object
+ remain, but trying to fetch them (with a standard "Email/get" call)
+ will return a "notFound" error if the corresponding objects have been
+ destroyed.
+
+ Similarly, destroying an EmailSubmission object MUST NOT affect the
+ deliveries it represents. It purely removes the record of the
+ submission. The server MAY automatically destroy EmailSubmission
+ objects after some time or in response to other triggers, and MAY
+ forbid the client from manually destroying EmailSubmission objects.
+
+ If the message to be sent is larger than the server supports sending,
+ a standard "tooLarge" SetError MUST be returned. A "maxSize"
+ "UnsignedInt" property MUST be present on the SetError specifying the
+ maximum size of 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:
+
+ For "create":
+
+ 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
+ invalid.
+
+ 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
+ sent.
+
+ 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.
+
+ For "update":
+
+ 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
+
+
+7.5.1. Example
+
+ The following example presumes a draft of the Email to be sent has
+ already been saved, and its Email id is "M7f6ed5bcfd7e2604d1753f6c".
+ This call then sends the Email immediately, and if successful,
+ removes the "$draft" flag and moves it from the drafts folder (which
+ has Mailbox id "7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e") to the sent
+ folder (which we presume has Mailbox id "73dbcb4b-bffc-48bd-8c2a-
+ a2e91ca672f6").
+
+ [[ "EmailSubmission/set", {
+ "accountId": "ue411d190",
+ "create": {
+ "k1490": {
+ "identityId": "I64588216",
+ "emailId": "M7f6ed5bcfd7e2604d1753f6c",
+ "envelope": {
+ "mailFrom": {
+ "email": "john@example.com",
+ "parameters": null
+ },
+ "rcptTo": [{
+ "email": "jane@example.com",
+ "parameters": null
+ },
+ ...
+ ]
+ }
+ }
+ },
+ "onSuccessUpdateEmail": {
+ "#k1490": {
+ "mailboxIds/7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e": null,
+ "mailboxIds/73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6": true,
+ "keywords/$draft": null
+ }
+ }
+ }, "0" ]]
+
+
+
+
+
+
+
+
+
+
+
+
+
+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",
+ "created": {
+ "k1490": {
+ "id": "ES-3bab7f9a-623e-4acf-99a5-2e67facb02a0"
+ }
+ }
+ }, "0" ],
+ [ "Email/set", {
+ "accountId": "ue411d190",
+ "oldState": "778193",
+ "newState": "778197",
+ "updated": {
+ "M7f6ed5bcfd7e2604d1753f6c": null
+ }
+ }, "0" ]]
+
+ Suppose instead an admin has removed sending rights for the user, so
+ the submission is rejected with a "forbiddenToSend" error. The
+ description argument of the error is intended for display to the
+ user, so it should be localised appropriately. Let's suppose the
+ request was sent with an Accept-Language header like this:
+
+ Accept-Language: de;q=0.9,en;q=0.8
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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",
+ "notCreated": {
+ "k1490": {
+ "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."
+ }
+ }
+}, "0" ]]
+
+8. Vacation Response
+
+ A vacation response sends an automatic reply when a message is
+ delivered to the mail store, informing the original sender that their
+ message may not be read for some time.
+
+ Automated message sending can produce undesirable behaviour. To
+ avoid this, implementors MUST follow the recommendations set forth in
+ [RFC3834].
+
+ The *VacationResponse* object represents the state of vacation-
+ response-related settings for an account. It has the following
+ properties:
+
+ o id: "Id" (immutable; server-set)
+
+ The id of the object. There is only ever one VacationResponse
+ object, and its id is "singleton".
+
+ o isEnabled: "Boolean"
+
+ 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
+ effective immediately.
+
+ 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
+ only.
+
+ The following JMAP methods are supported.
+
+8.1. VacationResponse/get
+
+ This is a standard "/get" method as described in [RFC8620],
+ Section 5.1.
+
+ There MUST only be exactly one VacationResponse object in an account.
+ It MUST have the id "singleton".
+
+
+
+
+
+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],
+ Section 5.3.
+
+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
+ following subsections.
+
+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
+ host.
+
+ Automatic conversion of charsets that allow hidden channels for ASCII
+ text, such as UTF-7, have been problematic for security filters in
+ the past, so server implementations can mitigate this risk by having
+ such conversions off-by-default and/or separately configurable.
+
+ To allow the client to restrict the volume of data it can receive in
+ response to a request, a maximum length may be requested for the data
+ returned for a textual body part. However, truncating the data may
+ change the semantic meaning, for example, truncating a URL changes
+ its location. Servers that scan for links to malicious sites should
+ take care to either ensure truncation is not at a semantically
+ significant point or rescan the truncated value for malicious content
+ before returning it.
+
+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,
+ including:
+
+
+
+
+
+
+
+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
+ layout of the message.
+
+ 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
+ more convincing.
+
+ o Links opened from a message or embedded external content may leak
+ private info in the Referer header sent by default in most
+ systems.
+
+ o Forms can be used to mimic login boxes, providing a potent
+ phishing vector if allowed to submit directly from the message
+ display.
+
+
+
+
+
+
+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
+ will:
+
+ * Disable JavaScript.
+
+ * 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
+ origin.
+
+ 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/
+ referrer-policy/>).
+
+ 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].
+
+9.4. Email Submission
+
+ SMTP submission servers [RFC6409] use a number of mechanisms to
+ mitigate damage caused by compromised user accounts and end-user
+ systems including rate limiting, anti-virus/anti-spam milters (mail
+ filters), and other technologies. The technologies work better when
+ they have more information about the client connection. If JMAP
+ email submission is implemented as a proxy to an SMTP submission
+ server, it is useful to communicate this information from the JMAP
+ proxy to the submission server. The de facto XCLIENT extension to
+ SMTP [XCLIENT] can be used to do this, but use of an authenticated
+ channel is recommended to limit use of that extension to explicitly
+ authorised proxies.
+
+ JMAP servers that proxy to an SMTP submission server SHOULD allow use
+ of the submissions port [RFC8314]. Implementation of a mechanism
+ similar to SMTP XCLIENT is strongly encouraged. While Simple
+ Authentication and Security Layer (SASL) PLAIN over TLS [RFC4616] is
+ presently the mandatory-to-implement mechanism for interoperability
+ with SMTP submission servers [RFC4954], a JMAP submission proxy
+ SHOULD implement and prefer a stronger mechanism for this use case
+ such as TLS client certificate authentication with SASL EXTERNAL
+ ([RFC4422], Appendix A) or Salted Challenge Response Authentication
+ Mechanism (SCRAM) [RFC7677].
+
+ In the event the JMAP server directly relays mail to SMTP servers in
+ other administrative domains, implementation of the de facto [milter]
+ protocol is strongly encouraged to integrate with third-party
+ products that address security issues including anti-virus/anti-spam,
+ reputation protection, compliance archiving, and data loss
+ prevention. Proxying to a local SMTP submission server may be a
+ simpler way to provide such security services.
+
+
+
+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
+
+ Intended use: common
+
+ 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
+
+ Intended use: common
+
+ 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
+ follows:
+
+ Capability Name: urn:ietf:params:jmap:vacationresponse
+
+ Specification document: this document
+
+ Intended use: common
+
+ Change Controller: IETF
+
+ Security and privacy considerations: this document, Section 9
+
+10.4. IMAP and JMAP Keywords Registry
+
+ This document makes two changes to the IMAP keywords registry as
+ defined in [RFC5788].
+
+ First, the name of the registry is changed to the "IMAP and JMAP
+ Keywords" registry.
+
+ Second, a scope column is added to the template and registry
+ indicating whether a keyword applies to "IMAP-only", "JMAP-only",
+ "both", or "reserved". All keywords already in the IMAP keyword
+ registry have been marked with a scope of "both". The "reserved"
+ status can be used to prevent future registration of a name that
+ would be confusing if registered. Registration of keywords with
+ scope "reserved" omit most fields in the registration template (see
+ registration of "$recent" below for an example); such registrations
+ are intended to be infrequent.
+
+ IMAP clients MAY silently ignore any keywords marked "JMAP-only" or
+ "reserved" in the event they appear in protocol. JMAP clients MAY
+ silently ignore any keywords marked "IMAP-only" or "reserved" in the
+ event they appear in protocol.
+
+ New "JMAP-only" keywords are registered in the following subsections.
+ These keywords correspond to IMAP system keywords and are thus not
+ appropriate for use in IMAP. These keywords cannot be subsequently
+ registered for use in IMAP except via standards action.
+
+
+
+
+
+
+
+
+
+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
+ Keywords" registry.
+
+ Keyword name: $draft
+
+ Scope: JMAP-only
+
+ Purpose (description): This is set when the user wants to treat the
+ message as a draft the user is composing. This is the JMAP
+ equivalent of the IMAP \Draft flag.
+
+ Private or Shared on a server: BOTH
+
+ Is it an advisory keyword or may it cause an automatic action:
+ Automatic. If the account has an IMAP mailbox marked with the
+ \Drafts special use attribute [RFC6154], setting this flag MAY cause
+ the message to appear in that mailbox automatically. Certain JMAP
+ computed values such as "unreadEmails" will change as a result of
+ changing this flag. In addition, mail clients will typically present
+ draft messages in a composer window rather than a viewer window.
+
+ When/by whom the keyword is set/cleared: This is typically set by a
+ JMAP client when referring to a draft message. One model for draft
+ Emails would result in clearing this flag in an "EmailSubmission/set"
+ operation with an "onSuccessUpdateEmail" argument. In a mail store
+ shared by JMAP and IMAP, this is also set and cleared as necessary so
+ it matches the IMAP \Draft flag.
+
+ Related keywords: None
+
+ Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]
+
+ Security Considerations: A server implementing this keyword as a
+ shared keyword may disclose that a user considers the message a draft
+ message. This information would be exposed to other users with read
+ permission for the Mailbox keywords.
+
+ Published specification: this document
+
+ Person & email address to contact for further information:
+ JMAP mailing list <jmap@ietf.org>
+
+ Intended usage: COMMON
+
+ Owner/Change controller: IESG
+
+
+
+
+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
+ Keywords" registry.
+
+ Keyword name: $seen
+
+ Scope: JMAP-only
+
+ Purpose (description): This is set when the user wants to treat the
+ message as read. This is the JMAP equivalent of the IMAP \Seen flag.
+
+ Private or Shared on a server: BOTH
+
+ Is it an advisory keyword or may it cause an automatic action:
+ Advisory. However, certain JMAP computed values such as
+ "unreadEmails" will change as a result of changing this flag.
+
+ When/by whom the keyword is set/cleared: This is set by a JMAP client
+ when it presents the message content to the user; clients often offer
+ an option to clear this flag. In a mail store shared by JMAP and
+ IMAP, this is also set and cleared as necessary so it matches the
+ IMAP \Seen flag.
+
+ Related keywords: None
+
+ Related IMAP/JMAP Capabilities: None
+
+ Security Considerations: A server implementing this keyword as a
+ shared keyword may disclose that a user considers the message to have
+ been read. This information would be exposed to other users with
+ read permission for the Mailbox keywords.
+
+ Published specification: this document
+
+ Person & email address to contact for further information:
+ JMAP mailing list <jmap@ietf.org>
+
+ Intended usage: COMMON
+
+ Owner/Change controller: IESG
+
+
+
+
+
+
+
+
+
+
+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.
+
+ Keyword name: $flagged
+
+ Scope: JMAP-only
+
+ Purpose (description): This is set when the user wants to treat the
+ message as flagged for urgent/special attention. This is the JMAP
+ equivalent of the IMAP \Flagged flag.
+
+ Private or Shared on a server: BOTH
+
+ Is it an advisory keyword or may it cause an automatic action:
+ Automatic. If the account has an IMAP mailbox marked with the
+ \Flagged special use attribute [RFC6154], setting this flag MAY cause
+ the message to appear in that mailbox automatically.
+
+ When/by whom the keyword is set/cleared: JMAP clients typically allow
+ a user to set/clear this flag as desired. In a mail store shared by
+ JMAP and IMAP, this is also set and cleared as necessary so it
+ matches the IMAP \Flagged flag.
+
+ Related keywords: None
+
+ Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]
+
+ Security Considerations: A server implementing this keyword as a
+ shared keyword may disclose that a user considers the message as
+ flagged for urgent/special attention. This information would be
+ exposed to other users with read permission for the Mailbox keywords.
+
+ Published specification: this document
+
+ Person & email address to contact for further information:
+ JMAP mailing list <jmap@ietf.org>
+
+ Intended usage: COMMON
+
+ Owner/Change controller: IESG
+
+
+
+
+
+
+
+
+
+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
+
+ Scope: JMAP-only
+
+ Purpose (description): This is set when the message has been
+ answered.
+
+ Private or Shared on a server: BOTH
+
+ Is it an advisory keyword or may it cause an automatic action:
+ Advisory.
+
+ When/by whom the keyword is set/cleared: JMAP clients typically set
+ this when submitting a reply or answer to the message. It may be set
+ by the "EmailSubmission/set" operation with an "onSuccessUpdateEmail"
+ argument. In a mail store shared by JMAP and IMAP, this is also set
+ and cleared as necessary so it matches the IMAP \Answered flag.
+
+ Related keywords: None
+
+ Related IMAP/JMAP Capabilities: None
+
+ Security Considerations: A server implementing this keyword as a
+ shared keyword may disclose that a user has replied to a message.
+ This information would be exposed to other users with read permission
+ for the Mailbox keywords.
+
+ Published specification: this document
+
+ Person & email address to contact for further information:
+ JMAP mailing list <jmap@ietf.org>
+
+ Intended usage: COMMON
+
+ Owner/Change controller: IESG
+
+
+
+
+
+
+
+
+
+
+
+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"
+ registry.
+
+ Keyword name: $recent
+
+ Scope: reserved
+
+ Purpose (description): This keyword is not used to avoid confusion
+ with the IMAP \Recent system flag.
+
+ Published specification: this document
+
+ Person & email address to contact for further information:
+ JMAP mailing list <jmap@ietf.org>
+
+ Owner/Change controller: IESG
+
+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].
+
+ Attribute Name: Inbox
+
+ Description: New mail is delivered here by default.
+
+ Reference: This document, Section 10.5.1
+
+ Usage Notes: JMAP only
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 2.5
+
+ Description: The Mailbox still has at least one child Mailbox. The
+ client MUST remove these before it can delete the parent Mailbox.
+
+10.6.2. mailboxHasEmail
+
+ JMAP Error Code: mailboxHasEmail
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 2.5
+
+ Description: The Mailbox has at least one message assigned to it, and
+ the onDestroyRemoveEmails argument was false.
+
+10.6.3. blobNotFound
+
+ JMAP Error Code: blobNotFound
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 4.6
+
+ Description: At least one blob id referenced in the object doesn't
+ exist.
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 100]
+
+RFC 8621 JMAP Mail August 2019
+
+
+10.6.4. tooManyKeywords
+
+ JMAP Error Code: tooManyKeywords
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 4.6
+
+ Description: The change to the Email's keywords would exceed a
+ server-defined maximum.
+
+10.6.5. tooManyMailboxes
+
+ JMAP Error Code: tooManyMailboxes
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 4.6
+
+ Description: The change to the set of Mailboxes that this Email is in
+ would exceed a server-defined maximum.
+
+10.6.6. invalidEmail
+
+ JMAP Error Code: invalidEmail
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 7.5
+
+ Description: The Email to be sent is invalid in some way.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 101]
+
+RFC 8621 JMAP Mail August 2019
+
+
+10.6.7. tooManyRecipients
+
+ JMAP Error Code: tooManyRecipients
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 7.5
+
+ Description: The envelope [RFC5321] (supplied or generated) has more
+ recipients than the server allows.
+
+10.6.8. noRecipients
+
+ JMAP Error Code: noRecipients
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 7.5
+
+ Description: The envelope [RFC5321] (supplied or generated) does not
+ have any rcptTo email addresses.
+
+10.6.9. invalidRecipients
+
+ JMAP Error Code: invalidRecipients
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 7.5
+
+ Description: The rcptTo property of the envelope [RFC5321] (supplied
+ or generated) contains at least one rcptTo value that is not a valid
+ email address for sending to.
+
+
+
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 102]
+
+RFC 8621 JMAP Mail August 2019
+
+
+10.6.10. forbiddenMailFrom
+
+ JMAP Error Code: forbiddenMailFrom
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 7.5
+
+ Description: The server does not permit the user to send a message
+ with this envelope From address [RFC5321].
+
+10.6.11. forbiddenFrom
+
+ JMAP Error Code: forbiddenFrom
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Sections 6.3 and 7.5
+
+ Description: The server does not permit the user to send a message
+ with the From header field [RFC5322] of the message to be sent.
+
+10.6.12. forbiddenToSend
+
+ JMAP Error Code: forbiddenToSend
+
+ Intended use: common
+
+ Change controller: IETF
+
+ Reference: This document, Section 7.5
+
+ Description: The user does not have permission to send at all right
+ now.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 103]
+
+RFC 8621 JMAP Mail August 2019
+
+
+11. References
+
+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>.
+
+Authors' Addresses
+
+ Neil Jenkins
+ Fastmail
+ PO Box 234, Collins St. West
+ Melbourne, VIC 8007
+ Australia
+
+ Email: neilj@fastmailteam.com
+ URI: https://www.fastmail.com
+
+
+ Chris Newman
+ Oracle
+ 440 E. Huntington Dr., Suite 400
+ Arcadia, CA 91006
+ United States of America
+
+ Email: chris.newman@oracle.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jenkins & Newman Standards Track [Page 108]
+