draft-ietf-jmap-mail-16.txt   rfc8621.txt 
JMAP N. Jenkins Internet Engineering Task Force (IETF) N. Jenkins
Internet-Draft FastMail Request for Comments: 8621 Fastmail
Updates: 5788 (if approved) C. Newman Updates: 5788 C. Newman
Intended status: Standards Track Oracle Category: Standards Track Oracle
Expires: September 9, 2019 March 8, 2019 ISSN: 2070-1721 August 2019
JMAP (JSON Meta Application Protocol) for Mail The JSON Meta Application Protocol (JMAP) for Mail
draft-ietf-jmap-mail-16
Abstract Abstract
This document specifies a data model for synchronising email data This document specifies a data model for synchronising email data
with a server using JMAP (the JSON Meta Application Protocol). with a server using the JSON Meta Application Protocol (JMAP).
Clients can use this to efficiently search, access, organise and send Clients can use this to efficiently search, access, organise, and
messages, and get pushed notifications for fast resynchronisation send messages, and to get push notifications for fast
when new messages are delivered or a change is made in another resynchronisation when new messages are delivered or a change is made
client. in another client.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on September 9, 2019. 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 Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational conventions . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
1.3. Additions to the capabilities object . . . . . . . . . . 5 1.3. Additions to the Capabilities Object . . . . . . . . . . 5
1.3.1. urn:ietf:params:jmap:mail . . . . . . . . . . . . . . 5 1.3.1. urn:ietf:params:jmap:mail . . . . . . . . . . . . . . 5
1.3.2. urn:ietf:params:jmap:submission . . . . . . . . . . . 6 1.3.2. urn:ietf:params:jmap:submission . . . . . . . . . . . 7
1.3.3. urn:ietf:params:jmap:vacationresponse . . . . . . . . 7 1.3.3. urn:ietf:params:jmap:vacationresponse . . . . . . . . 8
1.4. Data type support in different accounts . . . . . . . . . 7 1.4. Data Type Support in Different Accounts . . . . . . . . . 8
1.5. Push . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.5. Push . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 8 1.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 9
1.6. Ids . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.6. Ids . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2. Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2. Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1. Mailbox/get . . . . . . . . . . . . . . . . . . . . . . . 12 2.1. Mailbox/get . . . . . . . . . . . . . . . . . . . . . . . 14
2.2. Mailbox/changes . . . . . . . . . . . . . . . . . . . . . 12 2.2. Mailbox/changes . . . . . . . . . . . . . . . . . . . . . 14
2.3. Mailbox/query . . . . . . . . . . . . . . . . . . . . . . 13 2.3. Mailbox/query . . . . . . . . . . . . . . . . . . . . . . 14
2.4. Mailbox/queryChanges . . . . . . . . . . . . . . . . . . 14 2.4. Mailbox/queryChanges . . . . . . . . . . . . . . . . . . 15
2.5. Mailbox/set . . . . . . . . . . . . . . . . . . . . . . . 14 2.5. Mailbox/set . . . . . . . . . . . . . . . . . . . . . . . 16
2.6. Example . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6. Example . . . . . . . . . . . . . . . . . . . . . . . . . 17
3. Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 3. Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.1. Thread/get . . . . . . . . . . . . . . . . . . . . . . . 19 3.1. Thread/get . . . . . . . . . . . . . . . . . . . . . . . 22
3.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 19 3.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 22
3.2. Thread/changes . . . . . . . . . . . . . . . . . . . . . 19 3.2. Thread/changes . . . . . . . . . . . . . . . . . . . . . 22
4. Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4. Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.1. Properties of the Email object . . . . . . . . . . . . . 20 4.1. Properties of the Email Object . . . . . . . . . . . . . 23
4.1.1. Metadata . . . . . . . . . . . . . . . . . . . . . . 21 4.1.1. Metadata . . . . . . . . . . . . . . . . . . . . . . 24
4.1.2. Header fields parsed forms . . . . . . . . . . . . . 23 4.1.2. Header Fields Parsed Forms . . . . . . . . . . . . . 26
4.1.3. Header fields properties . . . . . . . . . . . . . . 28 4.1.3. Header Fields Properties . . . . . . . . . . . . . . 32
4.1.4. Body parts . . . . . . . . . . . . . . . . . . . . . 30 4.1.4. Body Parts . . . . . . . . . . . . . . . . . . . . . 35
4.2. Email/get . . . . . . . . . . . . . . . . . . . . . . . . 36 4.2. Email/get . . . . . . . . . . . . . . . . . . . . . . . . 42
4.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 38 4.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 44
4.3. Email/changes . . . . . . . . . . . . . . . . . . . . . . 39 4.3. Email/changes . . . . . . . . . . . . . . . . . . . . . . 45
4.4. Email/query . . . . . . . . . . . . . . . . . . . . . . . 40 4.4. Email/query . . . . . . . . . . . . . . . . . . . . . . . 45
4.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 40 4.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 46
4.4.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 42 4.4.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 49
4.4.3. Thread collapsing . . . . . . . . . . . . . . . . . . 44 4.4.3. Thread Collapsing . . . . . . . . . . . . . . . . . . 50
4.5. Email/queryChanges . . . . . . . . . . . . . . . . . . . 44 4.5. Email/queryChanges . . . . . . . . . . . . . . . . . . . 51
4.6. Email/set . . . . . . . . . . . . . . . . . . . . . . . . 44 4.6. Email/set . . . . . . . . . . . . . . . . . . . . . . . . 51
4.7. Email/copy . . . . . . . . . . . . . . . . . . . . . . . 47 4.7. Email/copy . . . . . . . . . . . . . . . . . . . . . . . 53
4.8. Email/import . . . . . . . . . . . . . . . . . . . . . . 47 4.8. Email/import . . . . . . . . . . . . . . . . . . . . . . 54
4.9. Email/parse . . . . . . . . . . . . . . . . . . . . . . . 49 4.9. Email/parse . . . . . . . . . . . . . . . . . . . . . . . 56
4.10. Examples . . . . . . . . . . . . . . . . . . . . . . . . 51 4.10. Examples . . . . . . . . . . . . . . . . . . . . . . . . 58
5. Search snippets . . . . . . . . . . . . . . . . . . . . . . . 58 5. Search Snippets . . . . . . . . . . . . . . . . . . . . . . . 68
5.1. SearchSnippet/get . . . . . . . . . . . . . . . . . . . . 59 5.1. SearchSnippet/get . . . . . . . . . . . . . . . . . . . . 69
5.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 60 5.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 71
6. Identities . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.1. Identity/get . . . . . . . . . . . . . . . . . . . . . . 62 6. Identities . . . . . . . . . . . . . . . . . . . . . . . . . 72
6.2. Identity/changes . . . . . . . . . . . . . . . . . . . . 62 6.1. Identity/get . . . . . . . . . . . . . . . . . . . . . . 73
6.3. Identity/set . . . . . . . . . . . . . . . . . . . . . . 62 6.2. Identity/changes . . . . . . . . . . . . . . . . . . . . 73
6.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 63 6.3. Identity/set . . . . . . . . . . . . . . . . . . . . . . 73
7. Email submission . . . . . . . . . . . . . . . . . . . . . . 63 6.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.1. EmailSubmission/get . . . . . . . . . . . . . . . . . . . 68 7. Email Submission . . . . . . . . . . . . . . . . . . . . . . 74
7.2. EmailSubmission/changes . . . . . . . . . . . . . . . . . 68 7.1. EmailSubmission/get . . . . . . . . . . . . . . . . . . . 80
7.3. EmailSubmission/query . . . . . . . . . . . . . . . . . . 68 7.2. EmailSubmission/changes . . . . . . . . . . . . . . . . . 80
7.4. EmailSubmission/queryChanges . . . . . . . . . . . . . . 69 7.3. EmailSubmission/query . . . . . . . . . . . . . . . . . . 80
7.5. EmailSubmission/set . . . . . . . . . . . . . . . . . . . 69 7.4. EmailSubmission/queryChanges . . . . . . . . . . . . . . 81
7.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 71 7.5. EmailSubmission/set . . . . . . . . . . . . . . . . . . . 81
8. Vacation response . . . . . . . . . . . . . . . . . . . . . . 74 7.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 84
8.1. VacationResponse/get . . . . . . . . . . . . . . . . . . 75 8. Vacation Response . . . . . . . . . . . . . . . . . . . . . . 86
8.2. VacationResponse/set . . . . . . . . . . . . . . . . . . 75 8.1. VacationResponse/get . . . . . . . . . . . . . . . . . . 87
9. Security considerations . . . . . . . . . . . . . . . . . . . 75 8.2. VacationResponse/set . . . . . . . . . . . . . . . . . . 88
9.1. EmailBodyPart value . . . . . . . . . . . . . . . . . . . 75 9. Security Considerations . . . . . . . . . . . . . . . . . . . 88
9.2. HTML email display . . . . . . . . . . . . . . . . . . . 76 9.1. EmailBodyPart Value . . . . . . . . . . . . . . . . . . . 88
9.3. Multiple part display . . . . . . . . . . . . . . . . . . 78 9.2. HTML Email Display . . . . . . . . . . . . . . . . . . . 88
9.4. Email submission . . . . . . . . . . . . . . . . . . . . 78 9.3. Multiple Part Display . . . . . . . . . . . . . . . . . . 91
9.5. Partial account access . . . . . . . . . . . . . . . . . 79 9.4. Email Submission . . . . . . . . . . . . . . . . . . . . 91
9.6. Permission to send from an address . . . . . . . . . . . 79 9.5. Partial Account Access . . . . . . . . . . . . . . . . . 92
10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 80 9.6. Permission to Send from an Address . . . . . . . . . . . 92
10.1. JMAP capability registration for "mail" . . . . . . . . 80 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 93
10.2. JMAP capability registration for "submission" . . . . . 80 10.1. JMAP Capability Registration for "mail" . . . . . . . . 93
10.3. JMAP capability registration for "vacationresponse" . . 81 10.2. JMAP Capability Registration for "submission" . . . . . 93
10.4. IMAP and JMAP keywords registry . . . . . . . . . . . . 81 10.3. JMAP Capability Registration for "vacationresponse" . . 94
10.4.1. Registration of JMAP keyword '$draft' . . . . . . . 81 10.4. IMAP and JMAP Keywords Registry . . . . . . . . . . . . 94
10.4.2. Registration of JMAP keyword '$seen' . . . . . . . . 82 10.4.1. Registration of JMAP Keyword "$draft" . . . . . . . 95
10.4.3. Registration of JMAP keyword '$flagged' . . . . . . 83 10.4.2. Registration of JMAP Keyword "$seen" . . . . . . . . 96
10.4.4. Registration of JMAP keyword '$answered' . . . . . . 84 10.4.3. Registration of JMAP Keyword "$flagged" . . . . . . 97
10.4.5. Registration of '$recent' keyword . . . . . . . . . 85 10.4.4. Registration of JMAP Keyword "$answered" . . . . . . 98
10.5. Registration of "inbox" role in . . . . . . . . . . . . 85 10.4.5. Registration of "$recent" Keyword . . . . . . . . . 99
10.6. JMAP Error Codes registry . . . . . . . . . . . . . . . 86 10.5. IMAP Mailbox Name Attributes Registry . . . . . . . . . 99
10.6.1. mailboxHasChild . . . . . . . . . . . . . . . . . . 86 10.5.1. Registration of "inbox" Role . . . . . . . . . . . . 99
10.6.2. mailboxHasEmail . . . . . . . . . . . . . . . . . . 86 10.6. JMAP Error Codes Registry . . . . . . . . . . . . . . . 100
10.6.3. blobNotFound . . . . . . . . . . . . . . . . . . . . 86 10.6.1. mailboxHasChild . . . . . . . . . . . . . . . . . . 100
10.6.4. tooManyKeywords . . . . . . . . . . . . . . . . . . 87 10.6.2. mailboxHasEmail . . . . . . . . . . . . . . . . . . 100
10.6.5. tooManyMailboxes . . . . . . . . . . . . . . . . . . 87 10.6.3. blobNotFound . . . . . . . . . . . . . . . . . . . . 100
10.6.6. invalidEmail . . . . . . . . . . . . . . . . . . . . 87 10.6.4. tooManyKeywords . . . . . . . . . . . . . . . . . . 101
10.6.7. tooManyRecipients . . . . . . . . . . . . . . . . . 87 10.6.5. tooManyMailboxes . . . . . . . . . . . . . . . . . . 101
10.6.8. noRecipients . . . . . . . . . . . . . . . . . . . . 88 10.6.6. invalidEmail . . . . . . . . . . . . . . . . . . . . 101
10.6.9. invalidRecipients . . . . . . . . . . . . . . . . . 88 10.6.7. tooManyRecipients . . . . . . . . . . . . . . . . . 102
10.6.10. forbiddenMailFrom . . . . . . . . . . . . . . . . . 88 10.6.8. noRecipients . . . . . . . . . . . . . . . . . . . . 102
10.6.11. forbiddenFrom . . . . . . . . . . . . . . . . . . . 89 10.6.9. invalidRecipients . . . . . . . . . . . . . . . . . 102
10.6.12. forbiddenToSend . . . . . . . . . . . . . . . . . . 89 10.6.10. forbiddenMailFrom . . . . . . . . . . . . . . . . . 103
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 89 10.6.11. forbiddenFrom . . . . . . . . . . . . . . . . . . . 103
11.1. Normative References . . . . . . . . . . . . . . . . . . 89 10.6.12. forbiddenToSend . . . . . . . . . . . . . . . . . . 103
11.2. Informative References . . . . . . . . . . . . . . . . . 93
11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 93 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 104
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 94 11.1. Normative References . . . . . . . . . . . . . . . . . . 104
11.2. Informative References . . . . . . . . . . . . . . . . . 107
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 108
1. Introduction 1. Introduction
JMAP ([I-D.ietf-jmap-core] - JSON Meta Application Protocol) is a The JSON Meta Application Protocol (JMAP) [RFC8620] is a generic
generic protocol for synchronising data, such as mail, calendars or protocol for synchronising data, such as mail, calendars, or contacts
contacts, between a client and a server. It is optimised for mobile between a client and a server. It is optimised for mobile and web
and web environments, and aims to provide a consistent interface to environments and aims to provide a consistent interface to different
different data types. data types.
This specification defines a data model for accessing a mail store This specification defines a data model for accessing a mail store
over JMAP, allowing you to query, read, organise and submit mail for over JMAP, allowing you to query, read, organise, and submit mail for
sending. sending.
The data model is designed to allow a server to provide consistent 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 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 IMAP, a message must belong to a mailbox; however, in JMAP, its id
not change if you move it between mailboxes, and the server may allow does not change if you move it between mailboxes, and the server may
it to belong to multiple mailboxes simultaneously (often exposed in a allow it to belong to multiple mailboxes simultaneously (often
user agent as labels rather than folders). exposed in a user agent as labels rather than folders).
As in IMAP, emails may also be assigned zero or more keywords: short As in IMAP, messages may also be assigned zero or more keywords:
arbitrary strings. These are primarily intended to store metadata to short arbitrary strings. These are primarily intended to store
inform client display, such as unread status or whether a message has metadata to inform client display, such as unread status or whether a
been replied to. An IANA registry allows common semantics to be message has been replied to. An IANA registry allows common
shared between clients and extended easily in the future. 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 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. Clients may fetch the list of messages with a particular Thread
id to more easily present a threaded or conversational interface. id to more easily present a threaded or conversational interface.
Permissions for message access happen on a per-mailbox basis. Permissions for message access happen on a per-mailbox basis.
Servers may give the user restricted permissions for certain Servers may give the user restricted permissions for certain
mailboxes, for example if another user's inbox has been shared read- mailboxes, for example, if another user's inbox has been shared as
only with them. read-only with them.
1.1. Notational conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Type signatures, examples and property descriptions in this document Type signatures, examples, and property descriptions in this document
follow the conventions established in section 1.1 of follow the conventions established in Section 1.1 of [RFC8620]. Data
[I-D.ietf-jmap-core]. Data types defined in the core specification types defined in the core specification are also used in this
are also used in this document. document.
Servers MUST support all properties specified for the new data types Servers MUST support all properties specified for the new data types
defined in this document. defined in this document.
1.2. Terminology 1.2. Terminology
The same terminology is used in this document as in the core JMAP This document uses the same terminology as in the core JMAP
specification. specification.
1.3. Additions to the capabilities object 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 The capabilities object is returned as part of the JMAP Session
object; see [I-D.ietf-jmap-core], section 2. object; see [RFC8620], Section 2.
This document defines three additional capability URIs. This document defines three additional capability URIs.
1.3.1. urn:ietf:params:jmap:mail 1.3.1. urn:ietf:params:jmap:mail
This represents support for the Mailbox, Thread, Email, and This represents support for the Mailbox, Thread, Email, and
SearchSnippet data types and associated API methods. The value of SearchSnippet data types and associated API methods. The value of
this property in the JMAP session _capabilities_ property is the this property in the JMAP session "capabilities" property is an empty
empty object. object.
The value of this property in an account's _accountCapabilities_ The value of this property in an account's "accountCapabilities"
property is an object which MUST contain the following information on property is an object that MUST contain the following information on
server capabilities and permissions for that account: server capabilities and permissions for that account:
o *maxMailboxesPerEmail*: "UnsignedInt|null" The maximum number of o maxMailboxesPerEmail: "UnsignedInt|null"
mailboxes 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).
o *maxMailboxDepth*: "UnsignedInt|null" The maximum depth of the The maximum number of Mailboxes (see Section 2) that can be can
mailbox hierarchy (i.e. one more than the maximum number of assigned to a single Email object (see Section 4). This MUST be
ancestors a mailbox may have), or "null" for no limit. an integer >= 1, or null for no limit (or rather, the limit is
always the number of Mailboxes in the account).
o *maxSizeMailboxName*: "UnsignedInt" The maximum length, in (UTF-8) o maxMailboxDepth: "UnsignedInt|null"
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 The maximum depth of the Mailbox hierarchy (i.e., one more than
of attachments, in octets, allowed for a single Email object. A the maximum number of ancestors a Mailbox may have), or null for
server MAY still reject import or creation of emails with a lower no limit.
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, 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, and 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 RFC5322 message, which will have attachments Base64 encoded
and message headers and bodies too. For example, suppose the
server advertises "maxSizeAttachmentsPerEmail: 50000000" (50 MB).
The enforced server limit may be for an RFC5322 size of 70000000
octets (70 MB). 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 o maxSizeMailboxName: "UnsignedInt"
server supports for the "property" field of the Comparator object
in an Email/query sort (see section 5.5). 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.
o *mayCreateTopLevelMailbox*: "Boolean" If "true", the user may The maximum length, in (UTF-8) octets, allowed for the name of a
create a mailbox (see section 2) in this account with a "null" Mailbox. This MUST be at least 100, although it is recommended
parentId. (Permission for creating a child of an existing mailbox servers allow more.
is given by the myRights property on that mailbox.)
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.
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 1.3.2. urn:ietf:params:jmap:submission
This represents support for the Identity and MessageSubmission data This represents support for the Identity and EmailSubmission data
types and associated API methods. The value of this property in the types and associated API methods. The value of this property in the
JMAP session _capabilities_ property is the empty object. JMAP session "capabilities" property is an empty object.
The value of this property in an account's _accountCapabilities_ The value of this property in an account's "accountCapabilities"
property is an object which MUST contain the following information on property is an object that MUST contain the following information on
server capabilities and permissions for that account: server capabilities and permissions for that account:
o *maxDelayedSend*: "UnsignedInt" The number in seconds of the o maxDelayedSend: "UnsignedInt"
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 The number in seconds of the maximum delay the server supports in
submission extensions supported by the server, which the client sending (see the EmailSubmission object description). This is 0
may use when creating an EmailSubmission object (see section 7). if the server does not support delayed send.
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
[RFC6409] server 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 are 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]) o submissionExtensions: "String[String[]]"
* SIZE ([RFC1870]) 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".
* DSN ([RFC3461]) 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).
* DELIVERYBY ([RFC2852]) Examples of Submission extensions to include:
* MT-PRIORITY ([RFC6710]) * FUTURERELEASE [RFC4865]
* SIZE [RFC1870]
* DSN [RFC3461]
* DELIVERYBY [RFC2852]
* MT-PRIORITY [RFC6710]
A JMAP server MAY advertise an extension and implement the A JMAP server MAY advertise an extension and implement the
semantics of that extension locally on the JMAP server even if a semantics of that extension locally on the JMAP server even if a
submission server used by JMAP doesn't implement it. The full submission server used by JMAP doesn't implement it.
IANA registry of submission extensions can be found at
<https://www.iana.org/assignments/mail-parameters/mail- The full IANA registry of submission extensions can be found at
parameters.xhtml#mail-parameters-2>. <https://www.iana.org/assignments/mail-parameters>.
1.3.3. urn:ietf:params:jmap:vacationresponse 1.3.3. urn:ietf:params:jmap:vacationresponse
This represents support for the VacationResponse data type and This represents support for the VacationResponse data type and
associated API methods. The value of this property is an empty associated API methods. The value of this property is an empty
object in both the JMAP session _capabilities_ property and an object in both the JMAP session "capabilities" property and an
account's _accountCapabilities_ property. account's "accountCapabilities" property.
1.4. Data type support in different accounts 1.4. Data Type Support in Different Accounts
The server MUST include the appropriate capability strings as keys in The server MUST include the appropriate capability strings as keys in
the _accountCapabilities_ property of any account with which the user the "accountCapabilities" property of any account with which the user
may use the data types represented by that URI. Supported data types may use the data types represented by that URI. Supported data types
may differ between accounts the user has access to. For example, in 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 the user's personal account, they may have access to all three sets
data, but in a shared account they may only have data for of data, but in a shared account, they may only have data for
"urn:ietf:params:jmap:mail". This means they can access "urn:ietf:params:jmap:mail". This means they can access
Mailbox/Thread/Email data in the shared account but are not allowed 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/ to send as that account (and so do not have access to Identity/
MessageSubmission objects) or view/set its vacation response. EmailSubmission objects) or view/set its VacationResponse.
1.5. Push 1.5. Push
Servers MUST support the JMAP push mechanisms, as specified in Servers MUST support the JMAP push mechanisms, as specified in
[I-D.ietf-jmap-core] section 7, to receive notifications when the [RFC8620], Section 7, to receive notifications when the state changes
state changes for any of the types defined in this specification. for any of the types defined in this specification.
In addition, servers that implement the "urn:ietf:params:jmap:mail" In addition, servers that implement the "urn:ietf:params:jmap:mail"
capability MUST support pushing state changes for a type called capability MUST support pushing state changes for a type called
"EmailDelivery". There are no methods to act on this type; it only "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 exists as part of the push mechanism. The state string for this MUST
change whenever a new Email is added to the store, but SHOULD NOT 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 change upon any other change to the Email objects, for example, if
is marked as read or deleted. one is marked as read or deleted.
Clients in battery constrained environments may wish to delay Clients in battery-constrained environments may wish to delay
fetching changes initiated by the user, but fetch new messages fetching changes initiated by the user but fetch new Emails
immediately so they can notify the user. To do this, they can immediately so they can notify the user. To do this, they can
register for pushes for the EmailDelivery type rather than the Email register for pushes for the EmailDelivery type rather than the Email
type (defined in section 4). type (as defined in Section 4).
1.5.1. Example 1.5.1. Example
The client has registered for push notifications (see The client has registered for push notifications (see [RFC8620]) just
[I-D.ietf-jmap-core]) just for the "EmailDelivery" type. The user for the EmailDelivery type. The user marks an Email as read on
marks an email as read on another device, causing the state string another device, causing the state string for the Email type to
for the "Email" type to change, however as nothing new was added to change; however, as nothing new was added to the store, the
the store the "EmailDelivery" state does not change and nothing is EmailDelivery state does not change and nothing is pushed to the
pushed to the client. A new message arrives in the user's inbox, client. A new message arrives in the user's inbox, again causing the
again causing the "Email" state to change. This time the Email state to change. This time, the EmailDelivery state also
"EmailDelivery" state also changes, and a StateChange object is changes, and a StateChange object is pushed to the client with the
pushed to the client with the new state string. The client may then new state string. The client may then resync to fetch the new Email
resync to fetch the new message immediately. immediately.
1.6. Ids 1.6. Ids
If a JMAP Mail server also provides an IMAP interface to the data and If a JMAP Mail server also provides an IMAP interface to the data and
supports [RFC8474] IMAP Extension for Object Identifiers, the ids supports IMAP Extension for Object Identifiers [RFC8474], the ids
SHOULD be the same for mailbox, thread, and email objects in JMAP. SHOULD be the same for Mailbox, Thread, and Email objects in JMAP.
2. Mailboxes 2. Mailboxes
A mailbox represents a named set of emails. This is the primary A Mailbox represents a named set of Email objects. This is the
mechanism for organising emails within an account. It is analogous primary mechanism for organising messages within an account. It is
to a folder or a label in other systems. A mailbox may perform a analogous to a folder or a label in other systems. A Mailbox may
certain role in the system; see below for more details. perform a certain role in the system; see below for more details.
For compatibility with IMAP, an email MUST belong to one or more For compatibility with IMAP, an Email MUST belong to one or more
mailboxes. The email id does not change if the email changes Mailboxes. The Email id does not change if the Email changes
mailboxes. Mailboxes.
A *Mailbox* object has the following properties: A *Mailbox* object has the following properties:
o *id*: "Id" (immutable; server-set) The id of the mailbox. o id: "Id" (immutable; server-set)
o *name*: "String" User-visible name for the mailbox, e.g. "Inbox". The id of the Mailbox.
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 slash (/) or
control characters).
o *parentId*: "Id|null" (default: null) The mailbox id for the o name: "String"
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 User-visible name for the Mailbox, e.g., "Inbox". This MUST be a
have a particular common purpose (e.g. the "inbox"), regardless of Net-Unicode string [RFC5198] of at least 1 character in length,
the _name_ (which may be localised). This value is shared with subject to the maximum size given in the capability object. There
IMAP (exposed in IMAP via the [RFC6154] SPECIAL-USE extension). MUST NOT be two sibling Mailboxes with both the same parent and
However, unlike in IMAP, a mailbox MUST only have a single role, the same name. Servers MAY reject names that violate server
and there MUST NOT be two mailboxes in the same account with the policy (e.g., names containing a slash (/) or control characters).
same role. Servers providing IMAP access to the same data are
encouraged to enforce these extra restrictions in IMAP as well.
Otherwise, it is implementation dependent how to modify the IMAP
attributes to ensure compliance when exposing the data over JMAP.
The value MUST be one of the mailbox attribute names listed in the
IANA IMAP Mailbox Name Attributes Registry [1], as established in
[RFC8457], converted to lower-case. 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 o parentId: "Id|null" (default: null)
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 The Mailbox id for the parent of this Mailbox, or null if this
this mailbox. 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 *unreadEmails*: "UnsignedInt" (server-set) The number of emails in o role: "String|null" (default: null)
this mailbox that have neither the "$seen" keyword nor the
"$draft" keyword.
o *totalThreads*: "UnsignedInt" (server-set) The number of threads Identifies Mailboxes that have a particular common purpose (e.g.,
where at least one email in the thread is in this mailbox. the "inbox"), regardless of the "name" property (which may be
localised).
o *unreadThreads*: "UnsignedInt" (server-set) An indication of the This value is shared with IMAP (exposed in IMAP via the SPECIAL-
number of "unread" threads in the mailbox. For compatibility with USE extension [RFC6154]). However, unlike in IMAP, a Mailbox MUST
existing implementations, the way "unread threads" is determined only have a single role, and there MUST NOT be two Mailboxes in
is not mandated in this document. The simplest solution to the same account with the same role. Servers providing IMAP
implement is simply the number of threads where at least one email access to the same data are encouraged to enforce these extra
in the thread is both in this mailbox and has neither the "$seen" restrictions in IMAP as well. Otherwise, modifying the IMAP
nor "$draft" keywords. However, a quality implementation will attributes to ensure compliance when exposing the data over JMAP
return the number of unread items the user would see if they is implementation dependent.
opened that mailbox. A thread is shown as unread if it contains
any unread messages 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, 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") is treated specially:
1. Emails that are *only* in the Trash (and no other mailbox) are 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.
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 ignored when calculating the "unreadThreads" count of other
mailboxes. Mailboxes.
2. Emails that are *not* in the Trash are ignored when 2. Emails that are *not* in the trash are ignored when
calculating the "unreadThreads" count for the Trash mailbox. calculating the "unreadThreads" count for the trash Mailbox.
The result of this is that emails in the Trash are treated as 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 though they are in a separate Thread for the purposes of unread
counts. It is expected that clients will hide emails in the Trash counts. It is expected that clients will hide Emails in the trash
when viewing a thread in another mailbox and vice versa. This 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. allows you to delete a single Email to the trash out of a Thread.
So for example, suppose you have an account where the entire
contents is a single 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.
o *myRights*: "MailboxRights" (server-set) The set of rights (ACLs) For example, suppose you have an account where the entire contents
the user has in relation to this mailbox. These are backwards is a single Thread with 2 Emails: an unread Email in the trash and
compatible with IMAP ACLs, as defined in [RFC4314]. A a read Email in the inbox. The "unreadThreads" count would be 1
_MailboxRights_ object has the following properties: for the trash and 0 for the inbox.
* *mayReadItems*: "Boolean" If true, the user may use this o myRights: "MailboxRights" (server-set)
mailbox as part of a filter in a _Email/query_ call and the
mailbox may be included in the _mailboxIds_ set 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 The set of rights (Access Control Lists (ACLs)) the user has in
(by either creating a new email or moving an existing one). relation to this Mailbox. These are backwards compatible with
Corresponds to IMAP ACL "i". IMAP ACLs, as defined in [RFC4314]. A *MailboxRights* object has
the following properties:
* *mayRemoveItems*: "Boolean" The user may remove mail from this * mayReadItems: "Boolean"
mailbox (by either changing the mailboxes of an email or
deleting it). 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" If true, the user may use this Mailbox as part of a filter in
keyword to/from an email. If an email belongs to multiple an "Email/query" call, and the Mailbox may be included in the
mailboxes, the user may only modify "$seen" if they have this "mailboxIds" property of Email objects. Email objects may be
permission for *all* of the mailboxes. Corresponds to IMAP ACL fetched if they are in *at least one* Mailbox with this
"s". 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).
* *maySetKeywords*: "Boolean" The user may add or remove any * mayAddItems: "Boolean"
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 The user may add mail to this Mailbox (by either creating a new
this mailbox as its parent. Corresponds to IMAP ACL "k". Email or moving an existing one). Corresponds to IMAP ACL "i".
* *mayRename*: "Boolean" The user may rename the mailbox or make * mayRemoveItems: "Boolean"
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. The user may remove mail from this Mailbox (by either changing
Corresponds to IMAP ACL "x" (although this covers both rename the Mailboxes of an Email or destroying the Email).
and delete permissions). Corresponds to IMAP ACLs "te" (if mapping from IMAP, both are
required for this to be true).
* *maySubmit*: "Boolean" Messages may be submitted directly to * maySetSeen: "Boolean"
this mailbox. Corresponds to IMAP ACL "p".
o *isSubscribed*: "Boolean" Has the user indicated they wish to see The user may add or remove the "$seen" keyword to/from an
this mailbox in their client? This SHOULD default to "false" for Email. If an Email belongs to multiple Mailboxes, the user may
mailboxes in shared accounts the user has access to, and "true" only modify "$seen" if they have this permission for *all* of
for any new mailboxes created by the user themself. This MUST be the Mailboxes. Corresponds to IMAP ACL "s".
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 only to display mailboxes to the
user that have the "isSubscribed" property 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 * maySetKeywords: "Boolean"
mailbox SHOULD be treated by the client as existing in both places
(i.e. when emptying the trash, the client should just remove the
Trash mailbox and leave it in the other mailbox).
The following JMAP methods are supported: 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".
* 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.
2.1. Mailbox/get 2.1. Mailbox/get
Standard "/get" method as described in [I-D.ietf-jmap-core] section This is a standard "/get" method as described in [RFC8620],
5.1. The _ids_ argument may be "null" to fetch all at once. Section 5.1. The "ids" argument may be "null" to fetch all at once.
2.2. Mailbox/changes 2.2. Mailbox/changes
Standard "/changes" method as described in [I-D.ietf-jmap-core] This is a standard "/changes" method as described in [RFC8620],
section 5.2, but with one extra argument to the response: Section 5.2 but with one extra argument to the response:
o *updatedProperties*: "String[]|null" If only the mailbox counts o updatedProperties: "String[]|null"
(unread/total emails/threads) have changed since the old state,
this will be the list of properties that may have changed, i.e. If only the "totalEmails", "unreadEmails", "totalThreads", and/or
"["totalEmails", "unreadEmails", "totalThreads", "unreadThreads" Mailbox properties have changed since the old
"unreadThreads"]". If the server is unable to tell if only counts state, this will be the list of properties that may have changed.
have changed, it MUST just be "null". 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 Since counts frequently change but other properties are generally
only changed rarely, the server can help the client optimise data only changed rarely, the server can help the client optimise data
transfer by keeping track of changes to email/thread counts transfer by keeping track of changes to Email/Thread counts separate
separately to other state changes. The _updatedProperties_ array may from other state changes. The "updatedProperties" array may be used
be used directly via a back-reference in a subsequent Mailbox/get directly via a back-reference in a subsequent "Mailbox/get" call in
call in the same single request so only these properties are returned the same request, so only these properties are returned if nothing
if nothing else has changed. else has changed.
2.3. Mailbox/query 2.3. Mailbox/query
Standard "/query" method as described in [I-D.ietf-jmap-core] section This is a standard "/query" method as described in [RFC8620],
5.5, but with the following additional request argument: Section 5.5 but with the following additional request argument:
o *sortAsTree*: "Boolean" (default: false) If "true", when sorting o sortAsTree: "Boolean" (default: false)
the query results and comparing two mailboxes a and b:
* If a is an ancestor of b, it always comes first regardless of If true, when sorting the query results and comparing Mailboxes A
the _sort_ comparators. Similarly, if a is descendant of b, and B:
then b always comes first.
* Otherwise, if a and b do not share a _parentId_, find the * If A is an ancestor of B, it always comes first regardless of
nearest ancestors of each that do have the same _parentId_ and the sort comparators. Similarly, if A is descendant of B, then
compare the sort properties on those mailboxes instead. B always comes first.
The result of this is that the mailboxes are sorted as a tree * 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 according to the parentId properties, with each set of children
with a common parent sorted according to the standard sort with a common parent sorted according to the standard sort
comparators. comparators.
o *filterAsTree*: "Boolean" (default: false) If "true", a mailbox is o filterAsTree: "Boolean" (default: false)
only included in the query if all its ancestors are also included
in the query according to the filter. 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 A *FilterCondition* object has the following properties, any of which
may be omitted: may be omitted:
o *parentId*: "Id|null" The Mailbox _parentId_ property must match o parentId: "Id|null"
the given value exactly.
o *name*: "String" The Mailbox _name_ property contains the given The Mailbox "parentId" property must match the given value
string. exactly.
o *role*: "String|null" The Mailbox _role_ property must match the o name: "String"
given value exactly.
o *hasAnyRole*: "Boolean" If "true", a Mailbox matches if it has any The Mailbox "name" property contains the given string.
non-"null" value for its _role_ property.
o *isSubscribed*: "Boolean" The "isSubscribed" property of the o role: "String|null"
mailbox must be identical to the value given to match the
condition. 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 A Mailbox object matches the FilterCondition if and only if all of
the given conditions match. If zero properties are specified, it is the given conditions match. If zero properties are specified, it is
automatically "true" for all objects. automatically true for all objects.
The following Mailbox properties MUST be supported for sorting: The following Mailbox properties MUST be supported for sorting:
o "sortOrder" o "sortOrder"
o "name" o "name"
2.4. Mailbox/queryChanges 2.4. Mailbox/queryChanges
Standard "/queryChanges" method as described in [I-D.ietf-jmap-core] This is a standard "/queryChanges" method as described in [RFC8620],
section 5.6. Section 5.6.
2.5. Mailbox/set 2.5. Mailbox/set
Standard "/set" method as described in [I-D.ietf-jmap-core] section This is a standard "/set" method as described in [RFC8620],
5.3, but with the following additional request argument: Section 5.3 but with the following additional request argument:
o *onDestroyRemoveMessages*: "Boolean" (default: false) If "false", o onDestroyRemoveEmails: "Boolean" (default: false)
any attempt to destroy a mailbox that still has messages in it
will be rejected with a "mailboxHasEmail" SetError. If "true",
any messages that were in the mailbox will be removed from it, and
if in no other mailboxes will be destroyed when the mailbox is
destroyed.
The following extra _SetError_ types are defined: 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.
For *destroy*: The following extra SetError types are defined:
o "mailboxHasChild": The mailbox still has at least one child For "destroy":
mailbox. The client MUST remove these before it can delete the
parent mailbox.
o "mailboxHasEmail": The mailbox has at least one message assigned o "mailboxHasChild": The Mailbox still has at least one child
to it and the _onDestroyRemoveMessages_ argument was "false". 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.
2.6. Example 2.6. Example
Fetching all mailboxes in an account: Fetching all Mailboxes in an account:
[[ "Mailbox/get", { [[ "Mailbox/get", {
"accountId": "u33084183", "accountId": "u33084183",
"ids": null "ids": null
}, "0" ]] }, "0" ]]
And response: And the response:
[[ "Mailbox/get", { [[ "Mailbox/get", {
"accountId": "u33084183", "accountId": "u33084183",
"state": "78540", "state": "78540",
"list": [{ "list": [{
"id": "MB23cfa8094c0f41e6", "id": "MB23cfa8094c0f41e6",
"name": "Inbox", "name": "Inbox",
"parentId": null, "parentId": null,
"role": "inbox", "role": "inbox",
"sortOrder": 10, "sortOrder": 10,
skipping to change at page 15, line 38 skipping to change at page 18, line 5
}, },
"isSubscribed": true "isSubscribed": true
}, { }, {
"id": "MB674cc24095db49ce", "id": "MB674cc24095db49ce",
"name": "Important mail", "name": "Important mail",
... ...
}, ... ], }, ... ],
"notFound": [] "notFound": []
}, "0" ]] }, "0" ]]
Now suppose a message is marked read and we get a push update that 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 the Mailbox state has changed. You might fetch the updates like
this: this:
[[ "Mailbox/changes", { [[ "Mailbox/changes", {
"accountId": "u33084183", "accountId": "u33084183",
"sinceState": "78540" "sinceState": "78540"
}, "0" ], }, "0" ],
[ "Mailbox/get", { [ "Mailbox/get", {
"accountId": "u33084183", "accountId": "u33084183",
"#ids": { "#ids": {
skipping to change at page 16, line 31 skipping to change at page 19, line 5
"name": "Mailbox/changes", "name": "Mailbox/changes",
"path": "/updated" "path": "/updated"
}, },
"#properties": { "#properties": {
"resultOf": "0", "resultOf": "0",
"name": "Mailbox/changes", "name": "Mailbox/changes",
"path": "/updatedProperties" "path": "/updatedProperties"
} }
}, "2" ]] }, "2" ]]
This fetches the list of ids for created/updated/destroyed mailboxes, This fetches the list of ids for created/updated/destroyed Mailboxes,
then using back-references fetches the data for just the created/ then using back-references, it fetches the data for just the created/
updated mailboxes in the same request. The response may look updated Mailboxes in the same request. The response may look
something like this: something like this:
[[ "Mailbox/changes", { [[ "Mailbox/changes", {
"accountId": "u33084183", "accountId": "u33084183",
"oldState": "78541", "oldState": "78541",
"newState": "78542", "newState": "78542",
"hasMoreChanges": false, "hasMoreChanges": false,
"updatedProperties": [ "updatedProperties": [
"totalEmails", "unreadEmails", "totalEmails", "unreadEmails",
"totalThreads", "unreadThreads" "totalThreads", "unreadThreads"
skipping to change at page 17, line 37 skipping to change at page 20, line 5
"list": [{ "list": [{
"id": "MB23cfa8094c0f41e6", "id": "MB23cfa8094c0f41e6",
"totalEmails": 16307, "totalEmails": 16307,
"unreadEmails": 13903, "unreadEmails": 13903,
"totalThreads": 5833, "totalThreads": 5833,
"unreadThreads": 5127 "unreadThreads": 5127
}], }],
"notFound": [] "notFound": []
}, "2" ]] }, "2" ]]
Here's an example where we try to rename one mailbox and destroy Here's an example where we try to rename one Mailbox and destroy
another: another:
[[ "Mailbox/set", { [[ "Mailbox/set", {
"accountId": "u33084183", "accountId": "u33084183",
"ifInState": "78542", "ifInState": "78542",
"update": { "update": {
"MB674cc24095db49ce": { "MB674cc24095db49ce": {
"name": "Maybe important mail" "name": "Maybe important mail"
} }
}, },
"destroy": [ "MB23cfa8094c0f41e6" ] "destroy": [ "MB23cfa8094c0f41e6" ]
}, "0" ]] }, "0" ]]
Suppose the rename succeeds, but we don't have permission to destroy Suppose the rename succeeds, but we don't have permission to destroy
the mailbox we tried to destroy, we might get back: the Mailbox we tried to destroy; we might get back:
[[ "Mailbox/set", { [[ "Mailbox/set", {
"accountId": "u33084183", "accountId": "u33084183",
"oldState": "78542", "oldState": "78542",
"newState": "78549", "newState": "78549",
"updated": { "updated": {
"MB674cc24095db49ce": null "MB674cc24095db49ce": null
}, },
"notDestroyed": { "notDestroyed": {
"MB23cfa8094c0f41e6": { "MB23cfa8094c0f41e6": {
"type": "forbidden" "type": "forbidden"
} }
} }
}, "0" ]] }, "0" ]]
3. Threads 3. Threads
Replies are grouped together with the original message to form a Replies are grouped together with the original message to form a
thread. In JMAP, a thread is simply a flat list of emails, ordered 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 by date. Every Email MUST belong to a Thread, even if it is the only
email in the thread. Email in the Thread.
The exact algorithm for determining whether two emails belong to the The exact algorithm for determining whether two Emails belong to the
same thread is not mandated in this spec to allow for compatibility same Thread is not mandated in this spec to allow for compatibility
with different existing systems. For new implementations, it is with different existing systems. For new implementations, it is
suggested that two messages belong in the same thread if both of the suggested that two messages belong in the same Thread if both of the
following conditions apply: following conditions apply:
1. An identical RFC5322 message id appears in both messages in any 1. An identical message id [RFC5322] appears in both messages in any
of the Message-Id, In-Reply-To and References headers. of the Message-Id, In-Reply-To, and References header fields.
2. After stripping automatically added prefixes such as "Fwd:", 2. After stripping automatically added prefixes such as "Fwd:",
"Re:", "[List-Tag]" etc. and ignoring whitespace, the subjects "Re:", "[List-Tag]", etc., and ignoring white space, the subjects
are the same. This avoids the situation where a person replies are the same. This avoids the situation where a person replies
to an old message as a convenient way of finding the right to an old message as a convenient way of finding the right
recipient to send to, but changes the subject and starts a new recipient to send to but changes the subject and starts a new
conversation. conversation.
If emails are delivered out of order for some reason, a user may If messages are delivered out of order for some reason, a user may
receive two emails in the same thread but without headers that have two Emails in the same Thread but without headers that associate
associate them with each other. The arrival of a third email in the them with each other. The arrival of a third Email may provide the
thread may provide the missing references to join them all together missing references to join them all together into a single Thread.
into a single thread. Since the _threadId_ of an email is immutable, Since the "threadId" of an Email is immutable, if the server wishes
if the server wishes to merge the threads, it MUST handle this by to merge the Threads, it MUST handle this by deleting and reinserting
deleting and reinserting (with a new email id) the emails that change (with a new Email id) the Emails that change "threadId".
threadId.
A *Thread* object has the following properties: A *Thread* object has the following properties:
o *id*: "Id" (immutable; server-set) The id of the thread. o id: "Id" (immutable; server-set)
o *emailIds*: "Id[]" (server-set) The ids of the emails in the The id of the Thread.
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: 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.
3.1. Thread/get 3.1. Thread/get
Standard "/get" method as described in [I-D.ietf-jmap-core] section This is a standard "/get" method as described in [RFC8620],
5.1. Section 5.1.
3.1.1. Example 3.1.1. Example
Request: Request:
[[ "Thread/get", { [[ "Thread/get", {
"accountId": "acme", "accountId": "acme",
"ids": ["f123u4", "f41u44"] "ids": ["f123u4", "f41u44"]
}, "#1" ]] }, "#1" ]]
skipping to change at page 19, line 48 skipping to change at page 22, line 39
{ {
"id": "f41u44", "id": "f41u44",
"emailIds": [ "82cf7bb" ] "emailIds": [ "82cf7bb" ]
} }
], ],
"notFound": [] "notFound": []
}, "#1" ]] }, "#1" ]]
3.2. Thread/changes 3.2. Thread/changes
Standard "/changes" method as described in [I-D.ietf-jmap-core] This is a standard "/changes" method as described in [RFC8620],
section 5.2. Section 5.2.
4. Emails 4. Emails
The *Email* object is a representation of an [RFC5322] message, which An *Email* object is a representation of a message [RFC5322], which
allows clients to avoid the complexities of MIME parsing, transfer allows clients to avoid the complexities of MIME parsing, transfer
encoding and character encoding. encoding, and character encoding.
4.1. Properties of the Email object 4.1. Properties of the Email Object
Broadly, a message consists of two parts: a list of header fields, Broadly, a message consists of two parts: a list of header fields and
then a body. The JMAP Email object provides a way to access the full then a body. The Email data type provides a way to access the full
structure, or to use simplified properties and avoid some complexity structure or to use simplified properties and avoid some complexity
if this is sufficient for the client application. if this is sufficient for the client application.
While raw headers can be fetched and set, the vast majority of While raw headers can be fetched and set, the vast majority of
clients should use an appropriate parsed form for each of the headers clients should use an appropriate parsed form for each of the header
it wants to process, as this allows it to avoid the complexities of fields it wants to process, as this allows it to avoid the
various encodings that are required in a valid RFC5322 message. 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 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 a tree structure. This may be arbitrarily nested, but the majority
of email clients present a flat model of an email body (normally of email clients present a flat model of a message body (normally
plain text or HTML), with a set of attachments. Flattening the MIME plaintext or HTML) with a set of attachments. Flattening the MIME
structure to form this model can be difficult, and causes structure to form this model can be difficult and causes
inconsistency between clients. Therefore in addition to the inconsistency between clients. Therefore, in addition to the
_bodyStructure_ property, which gives the full tree, the Email object "bodyStructure" property, which gives the full tree, the Email object
contains 3 alternate properties with flat lists of body parts: contains 3 alternate properties with flat lists of body parts:
o _textBody_/_htmlBody_: These provide a list of parts that should o "textBody"/"htmlBody": These provide a list of parts that should
be rendered sequentially as the "body" of the message. This is a 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 list rather than a single part as messages may have headers and/or
footers appended/prepended as separate parts as they are footers appended/prepended as separate parts when they are
transmitted, and some clients send text and images intended to be transmitted, and some clients send text and images intended to be
displayed inline in the body (or even videos and sound clips) as displayed inline in the body (or even videos and sound clips) as
multiple parts rather than a single HTML part with referenced multiple parts rather than a single HTML part with referenced
images. images.
Because MIME allows for multiple representations of the same data Because MIME allows for multiple representations of the same data
(using "multipart/alternative"), there is a textBody property (which (using "multipart/alternative"), there is a "textBody" property
prefers a plain text representation) and an htmlBody property (which (which prefers a plaintext representation) and an "htmlBody"
prefers an HTML representation) to accommodate the two most common property (which prefers an HTML representation) to accommodate the
client requirements. The same part may appear in both lists where two most common client requirements. The same part may appear in
there is no alternative between the two. both lists where there is no alternative between the two.
o _attachments_: This provides a list of parts that should be o "attachments": This provides a list of parts that should be
presented as "attachments" to the message. Some images may be presented as "attachments" to the message. Some images may be
solely there for embedding within an HTML body part; clients may solely there for embedding within an HTML body part; clients may
wish to not present these as attachments in the user interface if wish to not present these as attachments in the user interface if
they are displaying the HTML with the embedded images directly. they are displaying the HTML with the embedded images directly.
Some parts may also be in htmlBody/textBody; again, clients may Some parts may also be in htmlBody/textBody; again, clients may
wish to not present these as attachments in the user interface if wish to not present these as attachments in the user interface if
rendered as part of the body. rendered as part of the body.
The _bodyValues_ property allows for clients to fetch the value of The "bodyValues" property allows for clients to fetch the value of
text parts directly without having to do a second request for the text parts directly without having to do a second request for the
blob, and have the server handle decoding the charset into unicode. blob and to have the server handle decoding the charset into unicode.
This data is in a separate property rather than on the EmailBodyPart This data is in a separate property rather than on the EmailBodyPart
object to avoid duplication of large amounts of data, as the same 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 part may be included twice if the client fetches more than one of
bodyStructure, textBody and htmlBody. bodyStructure, textBody, and htmlBody.
In the following subsections the common notational convention for In the following subsections, the common notational convention for
wildcards has been adopted for content types, so "foo/*" means any wildcards has been adopted for content types, so "foo/*" means any
content type that starts with "foo/". content type that starts with "foo/".
Due to the number of properties involved, the set of _Email_ Due to the number of properties involved, the set of Email properties
properties is specified over the following four sub-sections. This is specified over the following four subsections. This is purely for
is purely for readability; all properties are top-level peers. readability; all properties are top-level peers.
4.1.1. Metadata 4.1.1. Metadata
These properties represent metadata about the [RFC5322] message, and These properties represent metadata about the message in the mail
are not derived from parsing the message itself. store and are not derived from parsing the message itself.
o *id*: "Id" (immutable; server-set) The id of the Email object. o id: "Id" (immutable; server-set)
Note, this is the JMAP object id, NOT the [RFC5322] Message-ID
header field value.
o *blobId*: "Id" (immutable; server-set) The id representing the raw The id of the Email object. Note that this is the JMAP object id,
octets of the [RFC5322] message. This may be used to download the NOT the Message-ID header field value of the message [RFC5322].
raw original message, or to attach it directly to another Email
etc.
o *threadId*: "Id" (immutable; server-set) The id of the Thread to o blobId: "Id" (immutable; server-set)
which this Email belongs.
o *mailboxIds*: "Id[Boolean]" The set of Mailbox ids this email The id representing the raw octets of the message [RFC5322] for
belongs to. An email in the mail store MUST belong to one or more this Email. This may be used to download the raw original message
mailboxes at all times (until it is deleted). The set is or to attach it directly to another Email, etc.
represented as an object, with each key being a _Mailbox id_. The
value for each key in the object MUST be "true".
o *keywords*: "String[Boolean]" (default: {}) A set of keywords that o threadId: "Id" (immutable; server-set)
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 are treated specially. The following four
keywords have their first character changed from "\" in IMAP to
"$" in JMAP and have particular semantic meaning:
* "$draft": The email is a draft the user is composing. The id of the Thread to which this Email belongs.
* "$seen": The email has been read. o mailboxIds: "Id[Boolean]"
* "$flagged": The email has been flagged for urgent/special 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.
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. attention.
* "$answered": The email has been replied to. * "$answered": The Email has been replied to.
The IMAP "\Recent" keyword is not exposed via JMAP. The IMAP The IMAP "\Recent" keyword is not exposed via JMAP. The IMAP
"\Deleted" keyword is also not present: IMAP uses a delete+expunge "\Deleted" keyword is also not present: IMAP uses a delete+expunge
model, which JMAP does not. Any message with the "\Deleted" model, which JMAP does not. Any message with the "\Deleted"
keyword MUST NOT be visible via JMAP (including as part of any keyword MUST NOT be visible via JMAP (and so are not counted in
mailbox counts). Users may add arbitrary keywords to an email. the "totalEmails", "unreadEmails", "totalThreads", and
For compatibility with IMAP, a keyword is a case-insensitive "unreadThreads" Mailbox properties).
string of 1-255 characters in the ASCII subset %x21-%x7e (excludes
control chars and space), and MUST NOT include any of these
characters: "( ) { ] % * " \" Because JSON is case-sensitive,
servers MUST return keywords in lower-case. The IANA Keyword
Registry [2] 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. 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:
* "$phishing": The email is highly likely to be phishing. ( ) { ] % * " \
Clients SHOULD warn users to take care when viewing this email
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. and disable links and attachments.
* "$junk": The email is definitely spam. Clients SHOULD set this * "$junk": The Email is definitely spam. Clients SHOULD set this
flag when users report spam to help train automated spam- flag when users report spam to help train automated spam-
detection systems. detection systems.
* "$notjunk": The email is definitely not spam. Clients SHOULD * "$notjunk": The Email is definitely not spam. Clients SHOULD
set this flag when users indicate an email is legitimate, to set this flag when users indicate an Email is legitimate, to
help train automated spam-detection systems. help train automated spam-detection systems.
o *size*: "UnsignedInt" (immutable; server-set) The size, in octets, o size: "UnsignedInt" (immutable; server-set)
of the raw data for the [RFC5322] message (as referenced by the
_blobId_, i.e. the number of octets in the file the user would
download).
o *receivedAt*: "UTCDate" (immutable; default: time of creation on The size, in octets, of the raw data for the message [RFC5322] (as
server) The date the email was received by the message store. referenced by the "blobId", i.e., the number of octets in the file
This is the _internal date_ in IMAP ([RFC3501]). the user would download).
4.1.2. Header fields parsed forms o receivedAt: "UTCDate" (immutable; default: time of creation on
server)
Header field properties are derived from the [RFC5322] and [RFC6532] The date the Email was received by the message store. This is the
message header fields. All header fields may be fetched in a raw "internal date" in IMAP [RFC3501].
form. Some headers may also be fetched in a parsed form. The
structured form that may be fetched depends on the header. The 4.1.2. Header Fields Parsed Forms
following forms are defined:
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 4.1.2.1. Raw
Type: "String" Type: "String"
The raw octets of the header field value from the first octet The raw octets of the header field value from the first octet
following the header field name terminating colon, up to but following the header field name terminating colon, up to but
excluding the header field terminating CRLF. Any standards-compliant excluding the header field terminating CRLF. Any standards-compliant
message MUST be either ASCII (RFC5322) or UTF-8 (RFC6532), however 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 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 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 the unicode replacement character (U+FFFD). Any NUL octet MUST be
dropped. dropped.
This form will typically have a leading space, as most generated This form will typically have a leading space, as most generated
messages insert a space after the colon that terminates the header messages insert a space after the colon that terminates the header
field name. field name.
4.1.2.2. Text 4.1.2.2. Text
Type: "String" Type: "String"
The header field value with: The header field value with:
1. White space unfolded (as defined in [RFC5322] section 2.2.3). 1. White space unfolded (as defined in [RFC5322], Section 2.2.3).
2. The terminating CRLF at the end of the value removed. 2. The terminating CRLF at the end of the value removed.
3. Any SP characters at the beginning of the value removed. 3. Any SP characters at the beginning of the value removed.
4. Any syntactically correct [RFC2047] encoded sections with a known 4. Any syntactically correct encoded sections [RFC2047] with a known
character set decoded. Any [RFC2047] encoded NUL octets or character set decoded. Any NUL octets or control characters
control characters are dropped from the decoded value. Any text encoded per [RFC2047] are dropped from the decoded value. Any
that looks like [RFC2047] syntax but violates [RFC2047] placement text that looks like syntax per [RFC2047] but violates placement
or whitespace rules MUST NOT be decoded. or white space rules per [RFC2047] MUST NOT be decoded.
5. The resulting unicode converted to NFC form. 5. The resulting unicode converted to Normalization Form C (NFC)
form.
If any decodings fail, the parser SHOULD insert a unicode replacement If any decodings fail, the parser SHOULD insert a unicode replacement
character (U+FFFD) and attempt to continue as much as possible. character (U+FFFD) and attempt to continue as much as possible.
To prevent obviously nonsense behaviour, which can lead to To prevent obviously nonsense behaviour, which can lead to
interoperability issues, this form may only be fetched or set for the interoperability issues, this form may only be fetched or set for the
following header fields: following header fields:
o Subject o Subject
o Comments o Comments
o Keywords o Keywords
o List-Id o List-Id
o Any header not defined in [RFC5322] or [RFC2369] o Any header field not defined in [RFC5322] or [RFC2369]
4.1.2.3. Addresses 4.1.2.3. Addresses
Type: "EmailAddress[]" Type: "EmailAddress[]"
The header is parsed as an "address-list" value, as specified in The header field is parsed as an "address-list" value, as specified
[RFC5322] section 3.4, into the "EmailAddress[]" type. There is an in [RFC5322], Section 3.4, into the "EmailAddress[]" type. There is
EmailAddress item for each "mailbox" parsed from the "address-list". an EmailAddress item for each "mailbox" parsed from the "address-
Group and comment information is discarded. list". Group and comment information is discarded.
The *EmailAddress* object has the following properties: An *EmailAddress* object has the following properties:
o *name*: "String|null" The _display-name_ of the [RFC5322] o name: "String|null"
_mailbox_. If this is a _quoted-string_:
The "display-name" of the "mailbox" [RFC5322]. If this is a
"quoted-string":
1. The surrounding DQUOTE characters are removed. 1. The surrounding DQUOTE characters are removed.
2. Any _quoted-pair_ is decoded. 2. Any "quoted-pair" is decoded.
3. White-space is unfolded, and then any leading and trailing 3. White space is unfolded, and then any leading and trailing
white-space is removed. white space is removed.
If there is no _display-name_ but there is a _comment_ immediately If there is no "display-name" but there is a "comment" immediately
following the _addr-spec_, the value of this SHOULD be used following the "addr-spec", the value of this SHOULD be used
instead. Otherwise, this property is "null". instead. Otherwise, this property is null.
o *email*: "String" The _addr-spec_ of the [RFC5322] _mailbox_. o email: "String"
Any syntactically correct [RFC2047] encoded sections with a known The "addr-spec" of the "mailbox" [RFC5322].
encoding MUST be decoded, following the same rules as for the _Text_
form.
Parsing SHOULD be best-effort in the face of invalid structure to 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 accommodate invalid messages and semi-complete drafts. EmailAddress
objects MAY have an _email_ property that does not conform to the objects MAY have an "email" property that does not conform to the
_addr-spec_ form (for example, may not contain an @ symbol). "addr-spec" form (for example, may not contain an @ symbol).
For example, the following "address-list" string: For example, the following "address-list" string:
" James Smythe" <james@example.com>, Friends: " James Smythe" <james@example.com>, Friends:
jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?= jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?=
<john@example.com>; <john@example.com>;
would be parsed as: would be parsed as:
[ [
skipping to change at page 25, line 49 skipping to change at page 29, line 33
o Resent-Sender o Resent-Sender
o Resent-Reply-To o Resent-Reply-To
o Resent-To o Resent-To
o Resent-Cc o Resent-Cc
o Resent-Bcc o Resent-Bcc
o Any header not defined in [RFC5322] or [RFC2369] o Any header field not defined in [RFC5322] or [RFC2369]
4.1.2.4. GroupedAddresses 4.1.2.4. GroupedAddresses
Type: "EmailAddressGroup[]" Type: "EmailAddressGroup[]"
This is similar to the Addresses form but preserves group This is similar to the Addresses form but preserves group
information. The header is parsed as an "address-list" value, as information. The header field is parsed as an "address-list" value,
specified in [RFC5322] section 3.4, into the "GroupedAddresses[]" as specified in [RFC5322], Section 3.4, into the "GroupedAddresses[]"
type. Consecutive mailboxes that are not part of a group are still type. Consecutive "mailbox" values that are not part of a group are
collected under an EmailAddressGroup object to provide a uniform still collected under an EmailAddressGroup object to provide a
type. uniform type.
The *EmailAddressGroup* object has the following properties: An *EmailAddressGroup* object has the following properties:
o *name*: "String|null" The _display-name_ of the [RFC5322] _group_, o name: "String|null"
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_es that belong to this The "display-name" of the "group" [RFC5322], or null if the
group, represented as EmailAddress objects. 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.
Any syntactically correct [RFC2047] encoded sections with a known o addresses: "EmailAddress[]"
encoding MUST be decoded, following the same rules as for the _Text_
form.
Parsing SHOULD be best-effort in the face of invalid structure to 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. accommodate invalid messages and semi-complete drafts.
For example, the following "address-list" string: For example, the following "address-list" string:
" James Smythe" <james@example.com>, Friends: " James Smythe" <james@example.com>, Friends:
jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?= jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?=
<john@example.com>; <john@example.com>;
would be parsed as: would be parsed as:
skipping to change at page 27, line 7 skipping to change at page 30, line 45
{ "name": "James Smythe", "email": "james@example.com" } { "name": "James Smythe", "email": "james@example.com" }
]}, ]},
{ "name": "Friends", "addresses": [ { "name": "Friends", "addresses": [
{ "name": null, "email": "jane@example.com" }, { "name": null, "email": "jane@example.com" },
{ "name": "John Smith", "email": "john@example.com" } { "name": "John Smith", "email": "john@example.com" }
]} ]}
] ]
To prevent obviously nonsense behaviour, which can lead to To prevent obviously nonsense behaviour, which can lead to
interoperability issues, this form may only be fetched or set for the interoperability issues, this form may only be fetched or set for the
same header fields as the _Addresses_ form. same header fields as the Addresses form (see Section 4.1.2.3).
4.1.2.5. MessageIds 4.1.2.5. MessageIds
Type: "String[]|null" Type: "String[]|null"
The header is parsed as a list of "msg-id" values, as specified in The header field is parsed as a list of "msg-id" values, as specified
[RFC5322] section 3.6.4, into the "String[]" type. CFWS and in [RFC5322], Section 3.6.4, into the "String[]" type. Comments and/
surrounding angle brackets ("<>") are removed. If parsing fails, the or folding white space (CFWS) and surrounding angle brackets ("<>")
value is "null". are removed. If parsing fails, the value is null.
To prevent obviously nonsense behaviour, which can lead to To prevent obviously nonsense behaviour, which can lead to
interoperability issues, this form may only be fetched or set for the interoperability issues, this form may only be fetched or set for the
following header fields: following header fields:
o Message-ID o Message-ID
o In-Reply-To o In-Reply-To
o References o References
o Resent-Message-ID o Resent-Message-ID
o Any header not defined in [RFC5322] or [RFC2369] o Any header field not defined in [RFC5322] or [RFC2369]
4.1.2.6. Date 4.1.2.6. Date
Type: "Date|null" Type: "Date|null"
The header is parsed as a "date-time" value, as specified in 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 [RFC5322], Section 3.3, into the "Date" type. If parsing fails, the
value is "null". value is null.
To prevent obviously nonsense behaviour, which can lead to To prevent obviously nonsense behaviour, which can lead to
interoperability issues, this form may only be fetched or set for the interoperability issues, this form may only be fetched or set for the
following header fields: following header fields:
o Date o Date
o Resent-Date o Resent-Date
o Any header not defined in [RFC5322] or [RFC2369] o Any header field not defined in [RFC5322] or [RFC2369]
4.1.2.7. URLs 4.1.2.7. URLs
Type: "String[]|null" Type: "String[]|null"
The header is parsed as a list of URLs, as described in [RFC2369], The header field is parsed as a list of URLs, as described in
into the "String[]" type. Values do not include the surrounding [RFC2369], into the "String[]" type. Values do not include the
angle brackets or any comments in the header with the URLs. If surrounding angle brackets or any comments in the header field with
parsing fails, the value is "null". the URLs. If parsing fails, the value is null.
To prevent obviously nonsense behaviour, which can lead to To prevent obviously nonsense behaviour, which can lead to
interoperability issues, this form may only be fetched or set for the interoperability issues, this form may only be fetched or set for the
following header fields: following header fields:
o List-Help o List-Help
o List-Unsubscribe o List-Unsubscribe
o List-Subscribe o List-Subscribe
o List-Post o List-Post
o List-Owner o List-Owner
o List-Archive o List-Archive
o Any header not defined in [RFC5322] or [RFC2369] o Any header field not defined in [RFC5322] or [RFC2369]
4.1.3. Header fields properties 4.1.3. Header Fields Properties
The following low-level *Email* property is specified for complete The following low-level Email property is specified for complete
access to the header data of the message: access to the header data of the message:
o *headers*: "EmailHeader[]" (immutable) This is a list of all o headers: "EmailHeader[]" (immutable)
[RFC5322] header fields, 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 This is a list of all header fields [RFC5322], in the same order
[RFC5322], with the same capitalization that it has in the they appear in the message. An *EmailHeader* object has the
message. following properties:
* *value*: "String" The header _field value_ as defined in * name: "String"
[RFC5322], in _Raw_ form.
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.
In addition, the client may request/send properties representing In addition, the client may request/send properties representing
individual header fields of the form: individual header fields of the form:
header:{header-field-name} header:{header-field-name}
Where "{header-field-name}" means any series of one or more printable Where "{header-field-name}" means any series of one or more printable
ASCII characters (i.e. characters that have values between 33 and ASCII characters (i.e., characters that have values between 33 and
126, inclusive), except colon. The property may also have the 126, inclusive), except for colon (:). The property may also have
following suffixes: the following suffixes:
o *:as{header-form}* This means the value is in a parsed form, where o :as{header-form}
"{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 This means the value is in a parsed form, where "{header-form}" is
corresponding to each instance of the header field, in the order one of the parsed-form names specified above. If not given, the
they appear in the message. If this suffix is not used, the value is in Raw form.
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), o :all
or "null" if none.
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. If both suffixes are used, they MUST be specified in the order above.
Header field names are matched case-insensitively. The value is Header field names are matched case insensitively. The value is
typed according to the requested form, or an array of that type if 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 :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 requested name, the value is null if fetching a single instance or an
the empty array if requesting :all. empty array if requesting :all.
As a simple example, if the client requests a property called As a simple example, if the client requests a property called
"header:subject", this means find the _last_ header field in the "header:subject", this means find the *last* header field in the
message named "subject" (matched case-insensitively) and return the message named "subject" (matched case insensitively) and return the
value in _Raw_ form, or "null" if no header of this name is found. 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 For a more complex example, consider the client requesting a property
called "header:Resent-To:asAddresses:all". This means: called "header:Resent-To:asAddresses:all". This means:
1. Find _all_ header fields named Resent-To (matched case- 1. Find *all* header fields named Resent-To (matched case
insensitively). insensitively).
2. For each instance parse the header field value in the _Addresses_ 2. For each instance, parse the header field value in the Addresses
form. form.
3. The result is of type "EmailAddress[][]" - each item in the array 3. The result is of type "EmailAddress[][]" -- each item in the
corresponds to the parsed value (which is itself an array) of the array corresponds to the parsed value (which is itself an array)
Resent-To header field instance. of the Resent-To header field instance.
The following convenience properties are also specified for the The following convenience properties are also specified for the Email
*Email* object: object:
o *messageId*: "String[]|null" (immutable) The value is identical to o messageId: "String[]|null" (immutable)
the value of _header:Message-ID:asMessageIds_. For messages
conforming to RFC5322 this will be an array with a single entry.
o *inReplyTo*: "String[]|null" (immutable) The value is identical to The value is identical to the value of "header:Message-
the value of _header:In-Reply-To:asMessageIds_. ID:asMessageIds". For messages conforming to RFC 5322, this will
be an array with a single entry.
o *references*: "String[]|null" (immutable) The value is identical o inReplyTo: "String[]|null" (immutable)
to the value of _header:References:asMessageIds_.
o *sender*: "EmailAddress[]|null" (immutable) The value is identical The value is identical to the value of "header:In-Reply-
to the value of _header:Sender:asAddresses_. To:asMessageIds".
o *from*: "EmailAddress[]|null" (immutable) The value is identical o references: "String[]|null" (immutable)
to the value of _header:From:asAddresses_.
o *to*: "EmailAddress[]|null" (immutable) The value is identical to The value is identical to the value of
the value of _header:To:asAddresses_. "header:References:asMessageIds".
o *cc*: "EmailAddress[]|null" (immutable) The value is identical to o sender: "EmailAddress[]|null" (immutable)
the value of _header:Cc:asAddresses_.
o *bcc*: "EmailAddress[]|null" (immutable) The value is identical to The value is identical to the value of
the value of _header:Bcc:asAddresses_. "header:Sender:asAddresses".
o *replyTo*: "EmailAddress[]|null" (immutable) The value is o from: "EmailAddress[]|null" (immutable)
identical to the value of _header:Reply-To:asAddresses_.
o *subject*: "String|null" (immutable) The value is identical to the The value is identical to the value of "header:From:asAddresses".
value of _header:Subject:asText_.
o *sentAt*: "Date|null" (immutable; default on creation: current o to: "EmailAddress[]|null" (immutable)
server time) The value is identical to the value of
_header:Date:asDate_.
4.1.4. Body parts The value is identical to the value of "header:To:asAddresses".
These properties are derived from the [RFC5322] message body and its o cc: "EmailAddress[]|null" (immutable)
[RFC2045] MIME entities.
A *EmailBodyPart* object has the following properties: The value is identical to the value of "header:Cc:asAddresses".
o *partId*: "String|null" Identifies this part uniquely within the o bcc: "EmailAddress[]|null" (immutable)
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 The value is identical to the value of "header:Bcc:asAddresses".
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, 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 o replyTo: "EmailAddress[]|null" (immutable)
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 value is identical to the value of "header:Reply-
the part, in the order they appear in the message. The values are To:asAddresses".
in _Raw_ form.
o *name*: "String|null" This is the [RFC2231] decoded _filename_ o subject: "String|null" (immutable)
parameter of the _Content-Disposition_ header field, or (for
compatibility with existing systems) if not present then the
[RFC2047] decoded _name_ parameter of the _Content-Type_ header
field.
o *type*: "String" The value of the _Content-Type_ header field of The value is identical to the value of "header:Subject:asText".
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 o sentAt: "Date|null" (immutable; default on creation: current
_Content-Type_ header field, if present, or "null" if the header server time)
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- The value is identical to the value of "header:Date:asDate".
Disposition_ header field of the part, if present, otherwise
"null". CFWS is removed and any parameters are stripped.
o *cid*: "String|null" The value of the _Content-Id_ header field of 4.1.4. Body Parts
the part, if present, otherwise "null". CFWS and surrounding
angle brackets ("<>") are removed. This may be used to reference
the content from within an [HTML] body part using the "cid:"
protocol, as defined in [RFC2392].
o *language*: "String[]|null" The list of language tags, as defined These properties are derived from the message body [RFC5322] and its
in [RFC3282], in the _Content-Language_ header field of the part, MIME entities [RFC2045].
if present.
o *location*: "String|null" The URI, as defined in [RFC2557], in the An *EmailBodyPart* object has the following properties:
_Content-Location_ header field of the part, if present.
o *subParts*: "EmailBodyPart[]|null" If type is "multipart/*", this o partId: "String|null"
contains the body parts of each child.
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].
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 In addition, the client may request/send EmailBodyPart properties
representing individual header fields, following the same syntax and representing individual header fields, following the same syntax and
semantics as for the Email object, e.g. "header:Content-Type". semantics as for the Email object, e.g., "header:Content-Type".
The following *Email* properties are specified for access to the body The following Email properties are specified for access to the body
data of the message: data of the message:
o *bodyStructure*: "EmailBodyPart" (immutable) This is the full MIME o bodyStructure: "EmailBodyPart" (immutable)
structure of the message body, represented as an array of the
message's top-level MIME parts, 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 This is the full MIME structure of the message body, without
of _partId_ to an *EmailBodyValue* object for none, some or all recursing into "message/rfc822" or "message/global" parts. Note
"text/*" parts. Which parts are included and whether the value is that EmailBodyParts may have subParts if they are of type
truncated is determined by various arguments to _Email/get_ and "multipart/*".
_Email/parse_. An *EmailBodyValue* object has the following
properties:
* *value*: "String" The value of the body part after decoding o bodyValues: "String[EmailBodyValue]" (immutable)
_Content-Transfer-Encoding_ and decoding 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, or if no charset is given, or if it believes the
charset given is incorrect. Decoding is best-effort and 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" This is a map of "partId" to an EmailBodyValue object for none,
if malformed sections were found while decoding the charset, or some, or all "text/*" parts. Which parts are included and whether
the charset was unknown, or the content-transfer-encoding was the value is truncated is determined by various arguments to
unknown. "Email/get" and "Email/parse". An *EmailBodyValue* object has the
following properties:
* *isTruncated*: "Boolean" (default: false) This is "true" if the * value: "String"
_value_ has been truncated.
See the security considerations section for issues related to The value of the body part after decoding Content-Transfer-
truncation and heuristic determination of content-type and 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. charset.
o *textBody*: "EmailBodyPart[]" (immutable) A list of "text/plain", o textBody: "EmailBodyPart[]" (immutable)
"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", A list of "text/plain", "text/html", "image/*", "audio/*", and/or
"text/html", "image/*", "audio/*" and/or "video/*" parts to "video/*" parts to display (sequentially) as the message body,
display (sequentially) as the message body, with a preference for with a preference for "text/plain" when alternative versions are
"text/html" when alternative versions are available. available.
o *attachments*: "EmailBodyPart[]" (immutable) A list of all parts o htmlBody: "EmailBodyPart[]" (immutable)
in _bodyStructure_, traversing depth-first, which satisfy either
of the following conditions:
* not of type "multipart/*" and not included in _textBody_ or A list of "text/plain", "text/html", "image/*", "audio/*", and/or
_htmlBody_ "video/*" parts to display (sequentially) as the message body,
with a preference for "text/html" when alternative versions are
available.
* of type "image/*", "audio/*" or "video/*" and not in both o attachments: "EmailBodyPart[]" (immutable)
_textBody_ and _htmlBody_
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. None of these parts include subParts, including "message/*" types.
Attached messages may be fetched using the Email/parse method and Attached messages may be fetched using the "Email/parse" method
the blobId. Note, an [HTML] body part may reference image parts and the "blobId".
in attachments 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" Note that a "text/html" body part [HTML] may reference image parts
if there are one or more parts in the message that a client UI in attachments by using "cid:" links to reference the Content-Id,
should offer as downloadable. A server SHOULD set hasAttachment as defined in [RFC2392], or by referencing the Content-Location.
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.
o *preview*: "String" (immutable; server-set) A plain text fragment o hasAttachment: "Boolean" (immutable; server-set)
of the message body. This is intended to be shown as a preview
line on a mailbox listing, and may be truncated when shown. The This is true if there are one or more parts in the message that a
server may choose which part of the message to include in the client UI should offer as downloadable. A server SHOULD set
preview; skipping quoted sections and salutations and collapsing hasAttachment to true if the "attachments" list contains at least
white-space can result in a more useful preview. This MUST NOT be one item that does not have "Content-Disposition: inline". The
more than 256 characters in length. As this is derived from the server MAY ignore parts in this list that are processed
message content by the server, and the algorithm for doing so automatically in some way or are referenced as embedded images in
could change over time, fetching this for an email a second time one of the "text/html" parts of the message.
MAY return a different result. However, the previous value is not
considered incorrect, and the change SHOULD NOT cause the Email The server MAY set hasAttachment based on implementation-defined
object to be considered as changed by the server. or site-configurable heuristics.
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, The exact algorithm for decomposing bodyStructure into textBody,
htmlBody and attachments part lists is not mandated, as this is a htmlBody, and attachments part lists is not mandated, as this is a
quality-of-service implementation issue and likely to require quality-of-service implementation issue and likely to require
workarounds for malformed content discovered over time. However, the workarounds for malformed content discovered over time. However, the
following algorithm (expressed here in JavaScript) is suggested as a following algorithm (expressed here in JavaScript) is suggested as a
starting point, based on real-world experience: starting point, based on real-world experience:
function isInlineMediaType ( type ) { function isInlineMediaType ( type ) {
return type.startsWith( 'image/' ) || return type.startsWith( 'image/' ) ||
type.startsWith( 'audio/' ) || type.startsWith( 'audio/' ) ||
type.startsWith( 'video/' ); type.startsWith( 'video/' );
} }
skipping to change at page 35, line 34 skipping to change at page 41, line 4
htmlBody.push( part ); htmlBody.push( part );
} }
if ( ( !textBody || !htmlBody ) && if ( ( !textBody || !htmlBody ) &&
isInlineMediaType( part.type ) ) { isInlineMediaType( part.type ) ) {
attachments.push( part ); attachments.push( part );
} }
} else { } else {
attachments.push( part ); attachments.push( part );
} }
} }
if ( multipartType == 'alternative' && textBody && htmlBody ) { if ( multipartType == 'alternative' && textBody && htmlBody ) {
// Found HTML part only // Found HTML part only
if ( textLength == textBody.length && if ( textLength == textBody.length &&
htmlLength != htmlBody.length ) { htmlLength != htmlBody.length ) {
for ( let i = htmlLength; i < htmlBody.length; i += 1 ) { for ( let i = htmlLength; i < htmlBody.length; i += 1 ) {
textBody.push( htmlBody[i] ); textBody.push( htmlBody[i] );
} }
} }
// Found plain text part only // Found plaintext part only
if ( htmlLength == htmlBody.length && if ( htmlLength == htmlBody.length &&
textLength != textBody.length ) { textLength != textBody.length ) {
for ( let i = textLength; i < textBody.length; i += 1 ) { for ( let i = textLength; i < textBody.length; i += 1 ) {
htmlBody.push( textBody[i] ); htmlBody.push( textBody[i] );
} }
} }
} }
} }
// Usage: // Usage:
let htmlBody = []; let htmlBody = [];
let textBody = []; let textBody = [];
let attachments = []; let attachments = [];
parseStructure( [ bodyStructure ], 'mixed', false, parseStructure( [ bodyStructure ], 'mixed', false,
htmlBody, textBody, attachments ); htmlBody, textBody, attachments );
For instance, consider a message with both text and HTML versions For instance, consider a message with both text and HTML versions
that's then gone through a list software manager that attaches a that has gone through a list software manager that attaches a header
header/footer. It might have a MIME structure something like: and footer. It might have a MIME structure something like:
multipart/mixed multipart/mixed
text/plain, content-disposition=inline - A text/plain, content-disposition=inline - A
multipart/mixed multipart/mixed
multipart/alternative multipart/alternative
multipart/mixed multipart/mixed
text/plain, content-disposition=inline - B text/plain, content-disposition=inline - B
image/jpeg, content-disposition=inline - C image/jpeg, content-disposition=inline - C
text/plain, content-disposition=inline - D text/plain, content-disposition=inline - D
multipart/related multipart/related
skipping to change at page 36, line 40 skipping to change at page 42, line 13
text/plain, content-disposition=inline - K text/plain, content-disposition=inline - K
In this case, the above algorithm would decompose this to: In this case, the above algorithm would decompose this to:
textBody => [ A, B, C, D, K ] textBody => [ A, B, C, D, K ]
htmlBody => [ A, E, K ] htmlBody => [ A, E, K ]
attachments => [ C, F, G, H, J ] attachments => [ C, F, G, H, J ]
4.2. Email/get 4.2. Email/get
Standard "/get" method as described in [I-D.ietf-jmap-core] section This is a standard "/get" method as described in [RFC8620],
5.1, with the following additional request arguments: Section 5.1 with the following additional request arguments:
o *bodyProperties*: "String[]" A list of properties to fetch for o bodyProperties: "String[]"
each EmailBodyPart returned. If omitted, this defaults to:
A list of properties to fetch for each EmailBodyPart returned. If
omitted, this defaults to:
[ "partId", "blobId", "size", "name", "type", "charset", [ "partId", "blobId", "size", "name", "type", "charset",
"disposition", "cid", "language", "location" ] "disposition", "cid", "language", "location" ]
o *fetchTextBodyValues*: "Boolean" (default: false) If "true", the o fetchTextBodyValues: "Boolean" (default: false)
_bodyValues_ property includes any "text/*" part in the "textBody"
property.
o *fetchHTMLBodyValues*: "Boolean" (default: false) If "true", the If true, the "bodyValues" property includes any "text/*" part in
_bodyValues_ property includes any "text/*" part in the "htmlBody" the "textBody" property.
property.
o *fetchAllBodyValues*: "Boolean" (default: false) If "true", the o fetchHTMLBodyValues: "Boolean" (default: false)
_bodyValues_ property includes any "text/*" part in the
"bodyStructure" property.
o *maxBodyValueBytes*: "UnsignedInt" (default: 0) If greater than If true, the "bodyValues" property includes any "text/*" part in
zero, the _value_ property of any EmailBodyValue object returned the "htmlBody" property.
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).
If the standard _properties_ argument is omitted or "null", the 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).
If the standard "properties" argument is omitted or null, the
following default MUST be used instead of "all" properties: following default MUST be used instead of "all" properties:
[ "id", "blobId", "threadId", "mailboxIds", "keywords", "size", [ "id", "blobId", "threadId", "mailboxIds", "keywords", "size",
"receivedAt", "messageId", "inReplyTo", "references", "sender", "from", "receivedAt", "messageId", "inReplyTo", "references", "sender", "from",
"to", "cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment", "to", "cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment",
"preview", "bodyValues", "textBody", "htmlBody", "attachments" ] "preview", "bodyValues", "textBody", "htmlBody", "attachments" ]
The following properties are expected to be fast to fetch in a The following properties are expected to be fast to fetch in a
quality implementation: quality implementation:
skipping to change at page 38, line 23 skipping to change at page 44, line 4
o replyTo o replyTo
o subject o subject
o sentAt o sentAt
o hasAttachment o hasAttachment
o preview o preview
Clients SHOULD take care when fetching any other properties, as there Clients SHOULD take care when fetching any other properties, as there
may be significantly longer latency in fetching and returning the may be significantly longer latency in fetching and returning the
data. data.
As specified above, parsed forms of headers may only be used on As specified above, parsed forms of headers may only be used on
appropriate header fields. Attempting to fetch a form that is appropriate header fields. Attempting to fetch a form that is
forbidden (e.g. "header:From:asDate") MUST result in the method call forbidden (e.g., "header:From:asDate") MUST result in the method call
being rejected with an "invalidArguments" error. being rejected with an "invalidArguments" error.
Where a specific header is requested as a property, the Where a specific header field is requested as a property, the
capitalization of the property name in the response MUST be identical capitalization of the property name in the response MUST be identical
to that used in the request. to that used in the request.
4.2.1. Example 4.2.1. Example
Request: Request:
[[ "Email/get", { [[ "Email/get", {
"ids": [ "f123u456", "f123u457" ], "ids": [ "f123u456", "f123u457" ],
"properties": [ "threadId", "mailboxIds", "from", "subject", "properties": [ "threadId", "mailboxIds", "from", "subject",
skipping to change at page 39, line 49 skipping to change at page 45, line 30
"value": "-- Sent by your friendly mailing list ..." "value": "-- Sent by your friendly mailing list ..."
} }
} }
} }
], ],
"notFound": [ "f123u456" ] "notFound": [ "f123u456" ]
}, "#1" ]] }, "#1" ]]
4.3. Email/changes 4.3. Email/changes
Standard "/changes" method as described in [I-D.ietf-jmap-core] This is a standard "/changes" method as described in [RFC8620],
section 5.2. If generating intermediate states for a large set of Section 5.2. If generating intermediate states for a large set of
changes, it is recommended that newer changes are returned first, as changes, it is recommended that newer changes be returned first, as
these are generally of more interest to users. these are generally of more interest to users.
4.4. Email/query 4.4. Email/query
Standard "/query" method as described in [I-D.ietf-jmap-core] section This is a standard "/query" method as described in [RFC8620],
5.5, but with the following additional request arguments: Section 5.5 but with the following additional request arguments:
o *collapseThreads*: "Boolean" (default: false) If "true", emails in o collapseThreads: "Boolean" (default: false)
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 If true, Emails in the same Thread as a previous Email in the list
one email at most will be included in the list for any given (given the filter and sort order) will be removed from the list.
thread. 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 In quality implementations, the query "total" property is expected to
be fast to calculate when the filter consists solely of a single be fast to calculate when the filter consists solely of a single
"inMailbox" property, as it is the same as the totalEmails or "inMailbox" property, as it is the same as the totalEmails or
totalThreads properties (depending on whether collapseThreads is totalThreads properties (depending on whether collapseThreads is
true) of the associated Mailbox object. true) of the associated Mailbox object.
4.4.1. Filtering 4.4.1. Filtering
A *FilterCondition* object has the following properties, any of which A *FilterCondition* object has the following properties, any of which
may be omitted: may be omitted:
o *inMailbox*: "Id" A mailbox id. An email must be in this mailbox o inMailbox: "Id"
to match the condition.
o *inMailboxOtherThan*: "Id[]" A list of mailbox ids. An email must A Mailbox id. An Email must be in this Mailbox to match the
be in at least one mailbox not in this list to match the condition.
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 o inMailboxOtherThan: "Id[]"
be before this date-time to match the condition.
o *after*: "UTCDate" The _receivedAt_ date-time of the email must be A list of Mailbox ids. An Email must be in at least one Mailbox
the same or after this date-time to match the condition. 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 *minSize*: "UnsignedInt" The _size_ of the email in octets must be o before: "UTCDate"
equal to or greater than this number to match the condition.
o *maxSize*: "UnsignedInt" The _size_ of the email in octets must be The "receivedAt" date-time of the Email must be before this date-
less than this number to match the condition. time to match the condition.
o *allInThreadHaveKeyword*: "String" All emails (including this one) o after: "UTCDate"
in the same thread as this email must have the given keyword to
match the condition.
o *someInThreadHaveKeyword*: "String" At least one email (possibly The "receivedAt" date-time of the Email must be the same or after
this one) in the same thread as this email must have the given this date-time to match the condition.
keyword to match the condition.
o *noneInThreadHaveKeyword*: "String" All emails (including this o minSize: "UnsignedInt"
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 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. match the condition.
o *notKeyword*: "String" This email must not have the given keyword o allInThreadHaveKeyword: "String"
to match the condition.
o *hasAttachment*: "Boolean" The "hasAttachment" property of the All Emails (including this one) in the same Thread as this Email
email must be identical to the value given to match the condition. must have the given keyword to match the condition.
o *text*: "String" Looks for the text in emails. The server MUST o someInThreadHaveKeyword: "String"
look up text in the _from_, _to_, _cc_, _bcc_, _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 At least one Email (possibly this one) in the same Thread as this
the message. Email must have the given keyword to match the condition.
o *to*: "String" Looks for the text in the _To_ header field of the o noneInThreadHaveKeyword: "String"
message.
o *cc*: "String" Looks for the text in the _Cc_ header field of the All Emails (including this one) in the same Thread as this Email
message. must *not* have the given keyword to match the condition.
o *bcc*: "String" Looks for the text in the _Bcc_ header field of o hasKeyword: "String"
the message.
o *subject*: "String" Looks for the text in the _subject_ property This Email must have the given keyword to match the condition.
of the email.
o *body*: "String" Looks for the text in one of the body parts of o notKeyword: "String"
the email. 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 This Email must not have the given keyword to match the condition.
elements. The first element is the name of the header field to
match against. The second (optional) element is the text to look o hasAttachment: "Boolean"
for in the header field value. If not supplied, the message
matches simply if it _has_ a header field of the given name. 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.
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 If zero properties are specified on the FilterCondition, the
condition MUST always evaluate to "true". If multiple properties are condition MUST always evaluate to true. If multiple properties are
specified, ALL must apply for the condition to be "true" (it is specified, ALL must apply for the condition to be true (it is
equivalent to splitting the object into one-property conditions and equivalent to splitting the object into one-property conditions and
making them all the child of an AND filter operator). making them all the child of an AND filter operator).
The exact semantics for matching "String" fields is *deliberately not The exact semantics for matching "String" fields is *deliberately not
defined* to allow for flexibility in indexing implementation, subject defined* to allow for flexibility in indexing implementation, subject
to the following: to the following:
o Any syntactically correct [RFC2047] encoded sections of header o Any syntactically correct encoded sections [RFC2047] of header
fields with a known encoding SHOULD be decoded before attempting fields with a known encoding SHOULD be decoded before attempting
to match text. to match text.
o When searching inside a "text/html" body part, any text considered o When searching inside a "text/html" body part, any text considered
markup rather than content SHOULD be ignored, including HTML tags markup rather than content SHOULD be ignored, including HTML tags
and most attributes, anything inside the "<head>" tag, CSS and and most attributes, anything inside the "<head>" tag, Cascading
JavaScript. Attribute content intended for presentation to the Style Sheets (CSS), and JavaScript. Attribute content intended
user such as "alt" and "title" SHOULD be considered in the search. 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 SHOULD be matched in a case-insensitive manner.
o Text contained in either (but matched) single or double quotes o Text contained in either (but matched) single (') or double (")
SHOULD be treated as a *phrase search*, that is a match is quotes SHOULD be treated as a *phrase search*; that is, a match is
required for that exact word or sequence of words, excluding the required for that exact word or sequence of words, excluding the
surrounding quotation marks. Use "\"", "\'" and "\\" to match a surrounding quotation marks.
literal """, "'" and "\" respectively in a phrase.
o Outside of a phrase, white-space SHOULD be treated as dividing Within a phrase, to match one of the following characters you MUST
separate tokens that may be searched for separately, but MUST all escape it by prefixing it with a backslash (\):
be present for the email to match the filter.
' " \
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 o Tokens (not part of a phrase) MAY be matched on a whole-word basis
using stemming (so for example a text search for "bus" would match using stemming (for example, a text search for "bus" would match
"buses" but not "business"). "buses" but not "business").
4.4.2. Sorting 4.4.2. Sorting
The following value for the "property" field on the Comparator object The following value for the "property" field on the Comparator object
MUST be supported for sorting: MUST be supported for sorting:
o *receivedAt* - The _receivedAt_ date as returned in the Email o "receivedAt" - The "receivedAt" date as returned in the Email
object. object.
The following values for the "property" field on the Comparator The following values for the "property" field on the Comparator
object SHOULD be supported for sorting. When specifying a object SHOULD be supported for sorting. When specifying a
"hasKeyword", "allInThreadHaveKeyword" or "someInThreadHaveKeyword" "hasKeyword", "allInThreadHaveKeyword", or "someInThreadHaveKeyword"
sort, the Comparator object MUST also have a _keyword_ property. sort, the Comparator object MUST also have a "keyword" property.
o *size* - The _size_ as returned in the Email object. o "size" - The "size" as returned in the Email object.
o *from* - This is taken to be either the "name" part, or if o "from" - This is taken to be either the "name" property or if
"null"/empty then the "email" part, of the *first* EmailAddress null/empty, the "email" property of the *first* EmailAddress
object in the _from_ property. If still none, consider the value object in the Email's "from" property. If still none, consider
to be the empty string. the value to be the empty string.
o *to* - This is taken to be either the "name" part, or if o "to" - This is taken to be either the "name" property or if null/
"null"/empty then the "email" part, of the *first* EmailAddress empty, the "email" property of the *first* EmailAddress object in
object in the _to_ property. If still none, consider the value to the Email's "to" property. If still none, consider the value to
be the empty string. be the empty string.
o *subject* - This is taken to be the base subject of the email, as o "subject" - This is taken to be the base subject of the message,
defined in section 2.1 of [RFC5256]. as defined in Section 2.1 of [RFC5256].
o *sentAt* - The _sentAt_ property on the Email object. o "sentAt" - The "sentAt" property on the Email object.
o *hasKeyword* - This value MUST be considered "true" if the email o "hasKeyword" - This value MUST be considered true if the Email has
has the keyword given as an additional _keyword_ property on the the keyword given as an additional "keyword" property on the
_Comparator_ object, or "false" otherwise. Comparator object, or false otherwise.
o *allInThreadHaveKeyword* - This value MUST be considered "true" o "allInThreadHaveKeyword" - This value MUST be considered true for
for the email if *all* of the emails in the same thread the Email if *all* of the Emails in the same Thread have the
(regardless of mailbox) have the keyword given as an additional keyword given as an additional "keyword" property on the
_keyword_ property on the _Comparator_ object. Comparator object.
o *someInThreadHaveKeyword* - This value MUST be considered "true" o "someInThreadHaveKeyword" - This value MUST be considered true for
for the email if *any* of the emails in the same thread the Email if *any* of the Emails in the same Thread have the
(regardless of mailbox) have the keyword given as an additional keyword given as an additional "keyword" property on the
_keyword_ property on the _Comparator_ object. Comparator object.
The server MAY support sorting based on other properties as well. A The server MAY support sorting based on other properties as well. A
client can discover which properties are supported by inspecting the client can discover which properties are supported by inspecting the
server's _capabilities_ object (see section 1.3). account's "capabilities" object (see Section 1.3).
Example sort: Example sort:
[{ [{
"property": "someInThreadHaveKeyword", "property": "someInThreadHaveKeyword",
"keyword": "$flagged", "keyword": "$flagged",
"isAscending": false "isAscending": false
}, { }, {
"property": "subject", "property": "subject",
"collation": "i;ascii-casemap" "collation": "i;ascii-casemap"
}, { }, {
"property": "receivedAt", "property": "receivedAt",
"isAscending": false "isAscending": false
}] }]
This would sort emails in flagged threads first (the thread is This would sort Emails in flagged Threads first (the Thread is
considered flagged if any email within it is flagged), and then in considered flagged if any Email within it is flagged), in subject
subject order, then newest first for messages with the same subject. order second, and then from newest first for messages with the same
If two emails have both identical flagged status, subject and date, subject. If two Emails have identical values for all three
the order is server-dependent but must be stable. properties, then the order is server dependent but must be stable.
4.4.3. Thread collapsing 4.4.3. Thread Collapsing
When _collapseThreads_ is "true", then after filtering and sorting When "collapseThreads" is true, then after filtering and sorting the
the email list, the list is further winnowed by removing any emails Email list, the list is further winnowed by removing any Emails for a
for a thread id that has already been seen (when passing through the Thread id that has already been seen (when passing through the list
list sequentially). A thread will therefore only appear *once* in sequentially). A Thread will therefore only appear *once* in the
the result, at the position of the first email in the list that result, at the position of the first Email in the list that belongs
belongs to the thread (given the current sort/filter). to the Thread (given the current sort/filter).
4.5. Email/queryChanges 4.5. Email/queryChanges
Standard "/queryChanges" method as described in [I-D.ietf-jmap-core] This is a standard "/queryChanges" method as described in [RFC8620],
section 5.6, with the following additional request arguments: Section 5.6 with the following additional request argument:
o *collapseThreads*: "Boolean" (default: false) The o collapseThreads: "Boolean" (default: false)
_collapseThreads_ argument that was used with _Email/query_.
The "collapseThreads" argument that was used with "Email/query".
4.6. Email/set 4.6. Email/set
Standard "/set" method as described in [I-D.ietf-jmap-core] section This is a standard "/set" method as described in [RFC8620],
5.3. The _Email/set_ method encompasses: Section 5.3. The "Email/set" method encompasses:
o Creating a draft o Creating a draft
o Changing the keywords of an email (e.g. unread/flagged status) o Changing the keywords of an Email (e.g., unread/flagged status)
o Adding/removing an email to/from mailboxes (moving a message) o Adding/removing an Email to/from Mailboxes (moving a message)
o Deleting emails 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
[I-D.ietf-jmap-core], 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 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 are a number of ways to specify the same information. To ensure that
the RFC5322 email to create is unambiguous, the following constraints the message [RFC5322] to create is unambiguous, the following
apply to Email objects submitted for creation: constraints apply to Email objects submitted for creation:
o The _headers_ property MUST NOT be given, on either the top-level o The "headers" property MUST NOT be given on either the top-level
email or an EmailBodyPart - the client must set each header field Email or an EmailBodyPart -- the client must set each header field
as an individual property. as an individual property.
o There MUST NOT be two properties that represent the same header o There MUST NOT be two properties that represent the same header
field (e.g. "header:from" and "from") within the Email or field (e.g., "header:from" and "from") within the Email or
particular EmailBodyPart. particular EmailBodyPart.
o Header fields MUST NOT be specified in parsed forms that are o Header fields MUST NOT be specified in parsed forms that are
forbidden for that particular field. forbidden for that particular field.
o Header fields beginning "Content-" MUST NOT be specified on the o Header fields beginning with "Content-" MUST NOT be specified on
Email object, only on EmailBodyPart objects. the Email object, only on EmailBodyPart objects.
o If a bodyStructure property is given, there MUST NOT be textBody, o If a "bodyStructure" property is given, there MUST NOT be
htmlBody or attachments properties. "textBody", "htmlBody", or "attachments" properties.
o If given, the bodyStructure EmailBodyPart MUST NOT contain a o If given, the "bodyStructure" EmailBodyPart MUST NOT contain a
property representing a header field that is already defined on property representing a header field that is already defined on
the top-level Email object. the top-level Email object.
o If given, textBody MUST contain exactly one body part, of type o If given, textBody MUST contain exactly one body part and it MUST
"text/plain". be of type "text/plain".
o If given, htmlBody MUST contain exactly one body part, of type o If given, htmlBody MUST contain exactly one body part and it MUST
"text/html". be of type "text/html".
o Within an EmailBodyPart: o Within an EmailBodyPart:
* The client may specify a partId OR a blobId but not both. If a * The client may specify a partId OR a blobId, but not both. If
partId is given, this partId MUST be present in the bodyValues a partId is given, this partId MUST be present in the
property. "bodyValues" property.
* The charset property MUST be omitted if a partId is given (the * The "charset" property MUST be omitted if a partId is given
part's content is included in bodyValues and the server may (the part's content is included in bodyValues, and the server
choose any appropriate encoding). may choose any appropriate encoding).
* The size property MUST be omitted if a partId is given. If a * 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 blobId is given, it may be included but is ignored by the
server (the size is actually calculated from the blob content server (the size is actually calculated from the blob content
itself). itself).
* A "Content-Transfer-Encoding" header field MUST NOT be given. * A Content-Transfer-Encoding header field MUST NOT be given.
o Within an EmailBodyValue object, isEncodingProblem and isTruncated o Within an EmailBodyValue object, isEncodingProblem and isTruncated
MUST be either "false" or omitted. MUST be either false or omitted.
Creation attempts that violate any of this SHOULD be rejected with an Creation attempts that violate any of this SHOULD be rejected with an
"invalidProperties" error, however a server MAY choose to modify the "invalidProperties" error; however, a server MAY choose to modify the
Email (e.g. choose between conflicting headers, use a different Email (e.g., choose between conflicting headers, use a different
content-encoding etc.) to comply with its requirements instead. content-encoding, etc.) to comply with its requirements instead.
The server MAY also choose to set additional headers. If not The server MAY also choose to set additional headers. If not
included, the server MUST generate and set a "Message-ID" header included, the server MUST generate and set a Message-ID header field
field in conformance with [RFC5322] section 3.6.4, and a "Date" in conformance with [RFC5322], Section 3.6.4 and a Date header field
header field in conformance with section 3.6.1. in conformance with Section 3.6.1.
The final RFC5322 email generated may be invalid. For example, if it The final message generated may be invalid per RFC 5322. For
is a half-finished draft, the "To" field may have a value that does example, if it is a half-finished draft, the To header field may have
not conform to the required syntax for this header field. The a value that does not conform to the required syntax for this header.
message will be checked for strict conformance when submitted for The message will be checked for strict conformance when submitted for
sending (see the EmailSubmission object description). sending (see the EmailSubmission object description).
Destroying an email removes it from all mailboxes to which it Destroying an Email removes it from all Mailboxes to which it
belonged. To just delete an email to trash, simply change the belonged. To just delete an Email to trash, simply change the
"mailboxIds" property so it is now in the mailbox with "role == "mailboxIds" property, so it is now in the Mailbox with a "role"
"trash"", and remove all other mailbox ids. property equal to "trash", and remove all other Mailbox ids.
When emptying the trash, clients SHOULD NOT destroy emails which are When emptying the trash, clients SHOULD NOT destroy Emails that are
also in a mailbox other than trash. For those emails, they SHOULD also in a Mailbox other than trash. For those Emails, they SHOULD
just remove the Trash mailbox from the email. just remove the trash Mailbox from the Email.
For successfully created Email objects, the _created_ response For successfully created Email objects, the "created" response
contains the _id_, _blobId_, _threadId_ and _size_ properties of the contains the "id", "blobId", "threadId", and "size" properties of the
object. object.
The following extra _SetError_ types are defined: The following extra SetError types are defined:
For *create*: For "create":
o "blobNotFound": At least one blob id given for an EmailBodyPart o "blobNotFound": At least one blob id given for an EmailBodyPart
doesn't exist. An extra _notFound_ property of type "Id[]" MUST doesn't exist. An extra "notFound" property of type "Id[]" MUST
be included in the error object containing every _blobId_ be included in the SetError object containing every "blobId"
referenced by an EmailBodyPart that could not be found on the referenced by an EmailBodyPart that could not be found on the
server. server.
For *create* and *update*: For "create" and "update":
o "tooManyKeywords": The change to the email's keywords would exceed o "tooManyKeywords": The change to the Email's keywords would exceed
a server-defined maximum. a server-defined maximum.
o "tooManyMailboxes": The change to the email's mailboxes would o "tooManyMailboxes": The change to the set of Mailboxes that this
exceed a server-defined maximum. Email is in would exceed a server-defined maximum.
4.7. Email/copy 4.7. Email/copy
Standard "/copy" method as described in [I-D.ietf-jmap-core] section This is a standard "/copy" method as described in [RFC8620],
5.4, except only the _mailboxIds_, _keywords_ and _receivedAt_ Section 5.4, except only the "mailboxIds", "keywords", and
properties may be set during the copy. This method cannot modify the "receivedAt" properties may be set during the copy. This method
RFC5322 representation of an email. cannot modify the message represented by the Email.
The server MAY forbid two email objects with the same exact [RFC5322] The server MAY forbid two Email objects with identical message
content, or even just with the same [RFC5322] Message-ID, to coexist content [RFC5322], or even just with the same Message-ID [RFC5322],
within an account; if the target account already has the email the to coexist within an account; if the target account already has the
copy will be rejected with a standard "alreadyExists" error. Email, the copy will be rejected with a standard "alreadyExists"
error.
For successfully copied Email objects, the _created_ response For successfully copied Email objects, the "created" response
contains the _id_, _blobId_, _threadId_ and _size_ properties of the contains the "id", "blobId", "threadId", and "size" properties of the
new object. new object.
4.8. Email/import 4.8. Email/import
The _Email/import_ method adds [RFC5322] messages to the set of The "Email/import" method adds messages [RFC5322] to the set of
emails in an account. The server MUST support messages with Emails in an account. The server MUST support messages with Email
[RFC6532] EAI headers. The messages must first be uploaded as blobs Address Internationalization (EAI) headers [RFC6532]. The messages
using the standard upload mechanism. It takes the following must first be uploaded as blobs using the standard upload mechanism.
arguments: The method takes the following arguments:
o *accountId*: "Id" The id of the account to use. o accountId: "Id"
o *ifInState*: "String|null" This is a state string as returned by The id of the account to use.
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 o ifInState: "String|null"
specified) to EmailImport objects
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: An *EmailImport* object has the following properties:
o *blobId*: "Id" The id of the blob containing the raw [RFC5322] o blobId: "Id"
message.
o *mailboxIds*: "Id[Boolean]" The ids of the mailboxes to assign The id of the blob containing the raw message [RFC5322].
this email to. At least one mailbox MUST be given.
o *keywords*: "String[Boolean]" (default: {}) The keywords to apply o mailboxIds: "Id[Boolean]"
to the email.
o *receivedAt*: "UTCDate" (default: time of most recent Received The ids of the Mailboxes to assign this Email to. At least one
header, or time of import on server if none) The _receivedAt_ date Mailbox MUST be given.
to set on the email.
Each email to import is considered an atomic unit which may succeed o keywords: "String[Boolean]" (default: {})
or fail individually. Importing successfully creates a new email
object from the data referenced by the blobId and applies the given
mailboxes, keywords and receivedAt date.
The server MAY forbid two email objects with the same exact [RFC5322] The keywords to apply to the Email.
content, or even just with the same [RFC5322] Message-ID, to coexist
within an account. In this case, it MUST reject attempts to import
an email considered a duplicate with an "alreadyExists" SetError. An
_existingId_ property of type "Id" MUST be included on the error
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 o receivedAt: "UTCDate" (default: time of most recent Received
(e.g. missing, wrong type, id not found), the server MUST reject the 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.
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. import with an "invalidProperties" SetError.
If the email cannot be imported because it would take the account If the Email cannot be imported because it would take the account
over quota, the import should be rejected with an "overQuota" over quota, the import should be rejected with an "overQuota"
SetError. SetError.
If the blob referenced is not a valid [RFC5322] message, the server 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 MAY modify the message to fix errors (such as removing NUL octets or
fixing invalid headers). If it does this, the _blobId_ on the fixing invalid headers). If it does this, the "blobId" on the
response MUST represent the new representation and therefore be response MUST represent the new representation and therefore be
different to the _blobId_ on the EmailImport object. Alternatively, different to the "blobId" on the EmailImport object. Alternatively,
the server MAY reject the import with an "invalidEmail" SetError. the server MAY reject the import with an "invalidEmail" SetError.
The response has the following arguments: The response has the following arguments:
o *accountId*: "Id" The id of the account used for this call. o accountId: "Id"
o *oldState*: "String|null" The state string that would have been The id of the account used for this call.
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 o oldState: "String|null"
_Email/get_ on this account.
o *created*: "Id[Email]|null" A map of the creation id to an object The state string that would have been returned by "Email/get" on
containing the _id_, _blobId_, _threadId_ and _size_ properties this account before making the requested changes, or null if the
for each successfully imported Email, or "null" if none. server doesn't know what the previous state string was.
o *notCreated*: "Id[SetError]|null" A map of creation id to a o newState: "String"
SetError object for each Email that failed to be created, or
"null" if all successful. The possible errors are defined above. 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.
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 The following additional errors may be returned instead of the
_Email/import_ response: "Email/import" response:
"stateMismatch": An "ifInState" argument was supplied and it does not "stateMismatch": An "ifInState" argument was supplied, and it does
match the current state. not match the current state.
4.9. Email/parse 4.9. Email/parse
This method allows you to parse blobs as [RFC5322] messages to get This method allows you to parse blobs as messages [RFC5322] to get
Email objects. The server MUST support messages with [RFC6532] EAI Email objects. The server MUST support messages with EAI headers
headers. This can be used to parse and display attached emails [RFC6532]. This can be used to parse and display attached messages
without having to import them as top-level email objects in the mail without having to import them as top-level Email objects in the mail
store in their own right. store in their own right.
The following metadata properties on the Email objects will be "null" The following metadata properties on the Email objects will be null
if requested: if requested:
o id o id
o mailboxIds o mailboxIds
o keywords o keywords
o receivedAt o receivedAt
The _threadId_ property of the Email MAY be present if the server can 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 calculate which Thread the Email would be assigned to were it to be
imported. Otherwise, this too is "null" if fetched. imported. Otherwise, this too is null if fetched.
The _Email/parse_ method takes the following arguments: The "Email/parse" method takes the following arguments:
o *accountId*: "Id" The id of the account to use. o accountId: "Id"
o *blobIds*: "Id[]" The ids of the blobs to parse. The id of the account to use.
o *properties*: "String[]" If supplied, only the properties listed o blobIds: "Id[]"
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 The ids of the blobs to parse.
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 o properties: "String[]"
_bodyValues_ property includes any "text/*" part in the "textBody"
property.
o *fetchHTMLBodyValues*: "Boolean" (default: false) If "true", the If supplied, only the properties listed in the array are returned
_bodyValues_ property includes any "text/*" part in the "htmlBody" for each Email object. If omitted, defaults to:
property.
o *fetchAllBodyValues*: "Boolean" (default: false) If "true", the [ "messageId", "inReplyTo", "references", "sender", "from", "to",
_bodyValues_ property includes any "text/*" part in the "cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment",
"bodyStructure" property. "preview", "bodyValues", "textBody", "htmlBody", "attachments" ]
o *maxBodyValueBytes*: "UnsignedInt" (default: 0) If greater than o bodyProperties: "String[]"
zero, the _value_ property of any EmailBodyValue object returned
in _bodyValues_ MUST be truncated if necessary so it does not A list of properties to fetch for each EmailBodyPart returned. If
exceed this number of octets in size. If "0" (the default), no omitted, defaults to the same value as the "Email/get"
truncation occurs. The server MUST ensure the truncation results "bodyProperties" default argument.
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 o fetchTextBodyValues: "Boolean" (default: false)
tag, e.g. in the middle of "<a href="https://example.com">".
There is no requirement for the truncated form to be a balanced If true, the "bodyValues" property includes any "text/*" part in
tree or valid HTML (indeed, the original source may well be the "textBody" property.
neither of these things).
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).
The response has the following arguments: The response has the following arguments:
o *accountId*: "Id" The id of the account used for the call. o accountId: "Id"
o *parsed*: "Id[Email]|null" A map of blob id to parsed Email The id of the account used for the call.
representation for each successfully parsed blob, or "null" if
none.
o *notParsable*: "Id[]|null" A list of ids given that corresponded o parsed: "Id[Email]|null"
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 A map of blob id to parsed Email representation for each
found, or "null" if none. 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 As specified above, parsed forms of headers may only be used on
appropriate header fields. Attempting to fetch a form that is appropriate header fields. Attempting to fetch a form that is
forbidden (e.g. "header:From:asDate") MUST result in the method call forbidden (e.g., "header:From:asDate") MUST result in the method call
being rejected with an "invalidArguments" error. being rejected with an "invalidArguments" error.
Where a specific header is requested as a property, the Where a specific header field is requested as a property, the
capitalization of the property name in the response MUST be identical capitalization of the property name in the response MUST be identical
to that used in the request. to that used in the request.
4.10. Examples 4.10. Examples
A client logs in for the first time. It first fetches the set of 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 Mailboxes. Now it will display the inbox to the user, which we will
presume has mailbox id "fb666a55". The inbox may be (very!) large, presume has Mailbox id "fb666a55". The inbox may be (very!) large,
but the user's screen is only so big, so the client will just load but the user's screen is only so big, so the client can just load the
the start and then can load in more as necessary. The client sends Threads it needs to fill the screen and then load in more only when
this request: the user scrolls. The client sends this request:
[[ "Email/query",{ [[ "Email/query",{
"accountId": "ue150411c", "accountId": "ue150411c",
"filter": { "filter": {
"inMailbox": "fb666a55" "inMailbox": "fb666a55"
}, },
"sort": [{ "sort": [{
"isAscending": false, "isAscending": false,
"property": "receivedAt" "property": "receivedAt"
}], }],
skipping to change at page 52, line 30 skipping to change at page 60, line 8
"subject", "subject",
"receivedAt", "receivedAt",
"size", "size",
"preview" "preview"
] ]
}, "3" ]] }, "3" ]]
Let's break down the 4 method calls to see what they're doing: 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 "0": This asks the server for the ids of the first 30 Email objects
in the inbox, sorted newest first, ignoring messages from the same in the inbox, sorted newest first, ignoring Emails from the same
thread as a newer message in the mailbox (i.e. it is the first 30 Thread as a newer Email in the Mailbox (i.e., it is the first 30
unique threads). unique Threads).
"1": Now we use a back-reference to fetch the thread ids for each of "1": Now we use a back-reference to fetch the Thread ids for each of
these email ids. these Email ids.
"2": Another back-reference fetches the Thread object for each of "2": Another back-reference fetches the Thread object for each of
these thread ids. these Thread ids.
"3": Finally, we fetch the information we need to display the mailbox "3": Finally, we fetch the information we need to display the Mailbox
listing (but no more!) for every message in each of these 30 threads. listing (but no more!) for every Email in each of these 30 Threads.
The client may aggregate this data for display, for example showing The client may aggregate this data for display, for example, by
the thread as "flagged" if any of the messages in it contain the showing the Thread as "flagged" if any of the Emails in it has the
"$flagged" keyword. "$flagged" keyword.
The response from the server may look something like this: The response from the server may look something like this:
[[ "Email/query", { [[ "Email/query", {
"accountId": "ue150411c", "accountId": "ue150411c",
"queryState": "09aa9a075588-780599:0", "queryState": "09aa9a075588-780599:0",
"canCalculateChanges": true, "canCalculateChanges": true,
"position": 0, "position": 0,
"total": 115, "total": 115,
skipping to change at page 54, line 9 skipping to change at page 61, line 35
"hasAttachment": true, "hasAttachment": true,
"from": [{ "from": [{
"email": "jdoe@example.com", "email": "jdoe@example.com",
"name": "Jane Doe" "name": "Jane Doe"
}], }],
"subject": "The Big Reveal", "subject": "The Big Reveal",
"receivedAt": "2018-06-27T00:20:35Z", "receivedAt": "2018-06-27T00:20:35Z",
"size": 175047, "size": 175047,
"preview": "As you may be aware, we are required to prepare a "preview": "As you may be aware, we are required to prepare a
presentation where we wow a panel of 5 random members of the presentation where we wow a panel of 5 random members of the
public, on or before 30 June each year. We have drafted ..." public, on or before 30 June each year. We have drafted..."
}, },
... ...
], ],
"notFound": [] "notFound": []
}, "3" ]] }, "3" ]]
Now, on another device the user marks the first message as unread, Now, on another device, the user marks the first Email as unread,
sending this API request: sending this API request:
[[ "Email/set", { [[ "Email/set", {
"accountId": "ue150411c", "accountId": "ue150411c",
"update": { "update": {
"Ma783e5cdf5f2deffbc97930a": { "Ma783e5cdf5f2deffbc97930a": {
"keywords/$seen": null "keywords/$seen": null
} }
} }
}, "0" ]] }, "0" ]]
skipping to change at page 54, line 40 skipping to change at page 62, line 29
[[ "Email/set", { [[ "Email/set", {
"accountId": "ue150411c", "accountId": "ue150411c",
"oldState": "780605", "oldState": "780605",
"newState": "780606", "newState": "780606",
"updated": { "updated": {
"Ma783e5cdf5f2deffbc97930a": null "Ma783e5cdf5f2deffbc97930a": null
}, },
... ...
}, "0" ]] }, "0" ]]
The user also deletes a few messages, and then a new message arrives. The user also deletes a few Emails, and then a new message arrives.
Back on our original machine, we receive a push update that the state 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 string for Email is now "780800". As this does not match the
client's current state, it issues a request for the changes: client's current state, it issues a request for the changes:
[[ "Email/changes", { [[ "Email/changes", {
"accountId": "ue150411c", "accountId": "ue150411c",
"sinceState": "780605", "sinceState": "780605",
"maxChanges": 50 "maxChanges": 50
}, "3" ], }, "3" ],
skipping to change at page 56, line 4 skipping to change at page 64, line 8
"id": "Me8de6c9f6de198239b982ea2", "id": "Me8de6c9f6de198239b982ea2",
"index": 0 "index": 0
}], }],
"removed": [ "M9bd17497e2a99cb345fc1d0a" ], "removed": [ "M9bd17497e2a99cb345fc1d0a" ],
"total": 115 "total": 115
}, "11" ]] }, "11" ]]
The client can update its local cache of the query results by The client can update its local cache of the query results by
removing "M9bd17497e2a99cb345fc1d0a" and then splicing in removing "M9bd17497e2a99cb345fc1d0a" and then splicing in
"Me8de6c9f6de198239b982ea2" at position 0. As it does not have the "Me8de6c9f6de198239b982ea2" at position 0. As it does not have the
data for this new email, it will then fetch it (it also could have data for this new Email, it will then fetch it (it also could have
done this in the same request using back-references). done this in the same request using back-references).
It knows something has changed about "Ma783e5cdf5f2deffbc97930a", so It knows something has changed about "Ma783e5cdf5f2deffbc97930a", so
it will refetch the mailboxes and keywords (the only mutable it will refetch the Mailbox ids and keywords (the only mutable
properties) for this email too. properties) for this Email too.
The user composes a new message and saves a draft. The client sends: 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" ]]
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", { [[ "Email/set", {
"accountId": "ue150411c", "accountId": "ue150411c",
"create": { "create": {
"k1546": { "k1546": {
"mailboxIds": { "mailboxIds": {
"2ea1ca41b38e": true "2ea1ca41b38e": true
}, },
"keywords": { "keywords": {
"$seen": true, "$seen": true,
skipping to change at page 56, line 39 skipping to change at page 66, line 17
"name": "John", "name": "John",
"email": "john@example.com" "email": "john@example.com"
}], }],
"subject": "World domination", "subject": "World domination",
"receivedAt": "2018-07-10T01:05:08Z", "receivedAt": "2018-07-10T01:05:08Z",
"sentAt": "2018-07-10T11:05:08+10:00", "sentAt": "2018-07-10T11:05:08+10:00",
"bodyStructure": { "bodyStructure": {
"type": "multipart/alternative", "type": "multipart/alternative",
"subParts": [{ "subParts": [{
"partId": "a49d", "partId": "a49d",
"type": "text/html" "type": "text/html",
"header:Content-Language": "en"
}, { }, {
"partId": "bd48", "partId": "bd48",
"type": "text/plain" "type": "text/plain",
"header:Content-Language": "en"
}] }]
}, },
"bodyValues": { "bodyValues": {
"bd48": { "bd48": {
"value": "I have the most brilliant plan. Let me tell you "value": "I have the most brilliant plan. Let me tell
all about it. What we do is, we", you all about it. What we do is, we",
"isTruncated": false "isTruncated": false
}, },
"49db": { "a49d": {
"value": "<!DOCTYPE html><html><head><title></title> "value": "<!DOCTYPE html><html><head><title></title>
<style type=\"text/css\">div{font-size:16px}</style></head> <style type=\"text/css\">div{font-size:16px}</style></head>
<body><div>I have the most brilliant plan. Let me tell you <body><div>I have the most <b>brilliant</b> plan. Let me
all about it. What we do is, we</div></body></html>", tell you all about it. What we do is, we</div></body>
</html>",
"isTruncated": false "isTruncated": false
} }
} }
} }
} },
"destroy": [ "Mf40b5f831efa7233b9eb1c7f" ]
}, "0" ]] }, "0" ]]
The server creates the new draft, deletes the old one, and sends the
The server creates the message and sends the success response: success response:
[[ "Email/set", { [[ "Email/set", {
"accountId": "ue150411c", "accountId": "ue150411c",
"oldState": "780823", "oldState": "780839",
"newState": "780839", "newState": "780842",
"created": { "created": {
"k1546": { "k1546": {
"id": "Md45b47b4877521042cec0938", "id": "Md45b47b4877521042cec0938",
"blobId": "Ge8de6c9f6de198239b982ea214e0f3a704e4af74", "blobId": "Ge8de6c9f6de198239b982ea214e0f3a704e4af74",
"threadId": "Td957e72e89f516dc", "threadId": "Td957e72e89f516dc",
"size": 11721 "size": 11721
} }
}, },
"destroyed": [ "Mf40b5f831efa7233b9eb1c7f" ],
... ...
}, "0" ]] }, "0" ]]
The client moves this draft to a different account. The only way to The client moves this draft to a different account. The only way to
do this is via the "/copy" method. It MUST set a new mailboxIds do this is via the "Email/copy" method. It MUST set a new
property, since the current value will not be valid mailbox ids in "mailboxIds" property, since the current value will not be valid
the destination account: Mailbox ids in the destination account:
[[ "Email/copy", { [[ "Email/copy", {
"fromAccountId": "ue150411c", "fromAccountId": "ue150411c",
"accountId": "u6c6c41ac", "accountId": "u6c6c41ac",
"create": { "create": {
"k45": { "k45": {
"id": "Md45b47b4877521042cec0938", "id": "Md45b47b4877521042cec0938",
"mailboxIds": { "mailboxIds": {
"75a4c956": true "75a4c956": true
} }
} }
}, },
"onSuccessDestroyOriginal": true "onSuccessDestroyOriginal": true
}, "0" ]] }, "0" ]]
The server successfully copies the email and deletes the original. The server successfully copies the Email and deletes the original.
Due to the implicit call to "Email/set", there are two responses to Due to the implicit call to "Email/set", there are two responses to
the single method call, both with the same method call id: the single method call, both with the same method call id:
[[ "Email/copy", { [[ "Email/copy", {
"fromAccountId": "ue150411c", "fromAccountId": "ue150411c",
"accountId": "u6c6c41ac", "accountId": "u6c6c41ac",
"oldState": "7ee7e9263a6d", "oldState": "7ee7e9263a6d",
"newState": "5a0d2447ed26", "newState": "5a0d2447ed26",
"created": { "created": {
"k45": { "k45": {
"id": "M138f9954a5cd2423daeafa55", "id": "M138f9954a5cd2423daeafa55",
"blobId": "G6b9fb047cba722c48c611e79233d057c6b0b74e8", "blobId": "G6b9fb047cba722c48c611e79233d057c6b0b74e8",
"threadId": "T2f242ea424a4079a", "threadId": "T2f242ea424a4079a",
"size": 11721 "size": 11721
} }
}, },
"notCreated": null "notCreated": null
}, "0" ], }, "0" ],
[ "Email/set", { [ "Email/set", {
"accountId": "ue150411c", "accountId": "ue150411c",
"oldState": "780839", "oldState": "780842",
"newState": "780871", "newState": "780871",
"destroyed": [ "Md45b47b4877521042cec0938" ], "destroyed": [ "Md45b47b4877521042cec0938" ],
... ...
}, "0" ]] }, "0" ]]
5. Search snippets 5. Search Snippets
When doing a search on a "String" property, the client may wish to 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 show the relevant section of the body that matches the search as a
preview instead of the beginning of the message, and to highlight any preview and to highlight any matching terms in both this and the
matching terms in both this and the subject of the email. Search subject of the Email. Search snippets represent this data.
snippets represent this data.
A *SearchSnippet* object has the following properties: A *SearchSnippet* object has the following properties:
o *emailId*: "Id" The email id the snippet applies to. o emailId: "Id"
o *subject*: "String|null" If text from the filter matches the The Email id the snippet applies to.
subject, this is the subject of the email with the following
transformations: 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 1. Any instance of the following three characters MUST be
replaced by an appropriate [HTML] entity: & (ampersand), < replaced by an appropriate HTML entity: & (ampersand), <
(less-than sign), and > (greater-than sign). Other characters (less-than sign), and > (greater-than sign) [HTML]. Other
MAY also be replaced with an HTML entity form. characters MAY also be replaced with an HTML entity form.
2. The matching words/phrases from the filter are wrapped in HTML 2. The matching words/phrases from the filter are wrapped in HTML
"<mark></mark>" tags. "<mark></mark>" tags.
If the subject does not match text from the filter, this property If the subject does not match text from the filter, this property
is "null". is null.
o *preview*: "String|null" If text from the filter matches the o preview: "String|null"
plain-text or HTML body, this is the relevant section of the body
(converted to plain text 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".
It is server-defined what is a relevant section of the body for If text from the filter matches the plaintext or HTML body, this
preview. If the server is unable to determine search snippets, it is the relevant section of the body (converted to plaintext if
MUST return "null" for both the _subject_ and _preview_ properties. 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.
Note, unlike most data types, a SearchSnippet DOES NOT have a 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". property called "id".
The following JMAP method is supported: The following JMAP method is supported.
5.1. SearchSnippet/get 5.1. SearchSnippet/get
To fetch search snippets, make a call to "SearchSnippet/get". It To fetch search snippets, make a call to "SearchSnippet/get". It
takes the following arguments: takes the following arguments:
o *accountId*: "Id" The id of the account to use. o accountId: "Id"
o *filter*: "FilterOperator|FilterCondition|null" The same filter as The id of the account to use.
passed to Email/query; see the description of this method in
section 4.4 for details.
o *emailIds*: "Id[]" The ids of the emails to fetch snippets for. 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.
o emailIds: "Id[]"
The ids of the Emails to fetch snippets for.
The response has the following arguments: The response has the following arguments:
o *accountId*: "Id" The id of the account used for the call. o accountId: "Id"
o *list*: "SearchSnippet[]" An array of SearchSnippet objects for The id of the account used for the call.
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 which o list: "SearchSnippet[]"
could not be found, or "null" if all ids were found.
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 As the search snippets are derived from the message content and the
algorithm for doing so could change over time, fetching the same algorithm for doing so could change over time, fetching the same
snippets a second time MAY return a different result. However, the snippets a second time MAY return a different result. However, the
previous value is not considered incorrect, so there is no state previous value is not considered incorrect, so there is no state
string or update mechanism needed. string or update mechanism needed.
The following standard errors may be returned instead of the The following additional errors may be returned instead of the
_searchSnippets_ response: "SearchSnippet/get" response:
"requestTooLarge": The number of _emailIds_ requested by the client "requestTooLarge": The number of "emailIds" requested by the client
exceeds the maximum number the server is willing to process in a exceeds the maximum number the server is willing to process in a
single method call. single method call.
"unsupportedFilter": The server is unable to process the given "unsupportedFilter": The server is unable to process the given
_filter_ for any reason. "filter" for any reason.
5.2. Example 5.2. Example
Here we did an Email/query to search for any email in the account 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 containing the word "foo"; now, we are fetching the search snippets
for some of the ids that were returned in the results: for some of the ids that were returned in the results:
[[ "SearchSnippet/get", { [[ "SearchSnippet/get", {
"accountId": "ue150411c", "accountId": "ue150411c",
"filter": { "filter": {
"text": "foo" "text": "foo"
}, },
"emailIds": [ "emailIds": [
"M44200ec123de277c0c1ce69c", "M44200ec123de277c0c1ce69c",
"M7bcbcb0b58d7729686e83d99", "M7bcbcb0b58d7729686e83d99",
skipping to change at page 61, line 29 skipping to change at page 72, line 7
"preview": "...the <mark>Foo</mark>/bar method results often "preview": "...the <mark>Foo</mark>/bar method results often
returns &lt;1 widget rather than the complete..." returns &lt;1 widget rather than the complete..."
}, },
... ...
], ],
"notFound": null "notFound": null
}, "0" ]] }, "0" ]]
6. Identities 6. Identities
An *Identity* object stores information about an email address (or An *Identity* object stores information about an email address or
domain) the user may send from. It has the following properties: domain the user may send from. It has the following properties:
o *id*: "Id" (immutable; server-set) The id of the identity. o id: "Id" (immutable; server-set)
o *name*: "String" (default: "") The "From" _name_ the client SHOULD The id of the Identity.
use when creating a new message from this identity.
o *email*: "String" (immutable) The "From" email address the client o name: "String" (default: "")
MUST use when creating a new message from this identity. If the
mailbox part of the address (the section before the "@") is the
single character "*" (e.g. "*@example.com") then 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 The "From" name the client SHOULD use when creating a new Email
value the client SHOULD set when creating a new message from this from this Identity.
identity.
o *bcc*: "EmailAddress[]|null" (default: null) The Bcc value the o email: "String" (immutable)
client SHOULD set when creating a new message from this identity.
o *textSignature*: "String" (default: "") Signature the client The "From" email address the client MUST use when creating a new
SHOULD insert into new plain-text messages that will be sent from Email from this Identity. If the "mailbox" part of the address
this identity. Clients MAY ignore this and/or combine this with a (the section before the "@") is the single character "*" (e.g.,
client-specific signature preference. "*@example.com"), the client may use any valid address ending in
that domain (e.g., "foo@example.com").
o *htmlSignature*: "String" (default: "") Signature the client o replyTo: "EmailAddress[]|null" (default: null)
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 new email. Clients MAY ignore
this and/or combine this with a client-specific signature
preference.
o *mayDelete*: "Boolean" (server-set) Is the user allowed to delete The Reply-To value the client SHOULD set when creating a new Email
this identity? Servers may wish to set this to "false" for the from this Identity.
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 for o bcc: "EmailAddress[]|null" (default: null)
the definition of _EmailAddress_.
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.
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 Multiple identities with the same email address MAY exist, to allow
for different settings the user wants to pick between (for example for different settings the user wants to pick between (for example,
with different names/signatures). with different names/signatures).
The following JMAP methods are supported: The following JMAP methods are supported.
6.1. Identity/get 6.1. Identity/get
Standard "/get" method as described in [I-D.ietf-jmap-core] section This is a standard "/get" method as described in [RFC8620],
5.1. The _ids_ argument may be "null" to fetch all at once. Section 5.1. The "ids" argument may be null to fetch all at once.
6.2. Identity/changes 6.2. Identity/changes
Standard "/changes" method as described in [I-D.ietf-jmap-core] This is a standard "/changes" method as described in [RFC8620],
section 5.2. Section 5.2.
6.3. Identity/set 6.3. Identity/set
Standard "/set" method as described in [I-D.ietf-jmap-core] section This is a standard "/set" method as described in [RFC8620],
5.3. The following extra _SetError_ types are defined: Section 5.3. The following extra SetError types are defined:
For *create*: For "create":
o "forbiddenFrom": The user is not allowed to send from the address o "forbiddenFrom": The user is not allowed to send from the address
given as the _email_ property of the identity. given as the "email" property of the Identity.
6.4. Example 6.4. Example
Request: Request:
[ "Identity/get", { [ "Identity/get", {
"accountId": "acme" "accountId": "acme"
}, "0" ] }, "0" ]
with response: with response:
skipping to change at page 63, line 47 skipping to change at page 74, line 39
"replyTo": null, "replyTo": null,
"bcc": null, "bcc": null,
"textSignature": "", "textSignature": "",
"htmlSignature": "", "htmlSignature": "",
"mayDelete": true "mayDelete": true
} }
], ],
"notFound": [] "notFound": []
}, "0" ] }, "0" ]
7. Email submission 7. Email Submission
An *EmailSubmission* object represents the submission of an email for An *EmailSubmission* object represents the submission of an Email for
delivery to one or more recipients. It has the following properties: delivery to one or more recipients. It has the following properties:
o *id*: "Id" (immutable; server-set) The id of the email submission. o id: "Id" (immutable; server-set)
o *identityId*: "Id" (immutable) The id of the identity to associate The id of the EmailSubmission.
with this submission.
o *emailId*: "Id" (immutable) The id of the email to send. The o identityId: "Id" (immutable)
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 The id of the Identity to associate with this submission.
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 o emailId: "Id" (immutable)
sending via SMTP. An *Envelope* object has the following
properties:
* *mailFrom*: "Address" The email address to use as the return The id of the Email to send. The Email being sent does not have
address in the SMTP submission, plus any parameters to pass to be a draft, for example, when "redirecting" an existing Email
with the MAIL FROM address. The JMAP server MAY allow the to a different address.
address to be the empty string. When a JMAP server performs an
SMTP message submission, it MAY use the same id string for the
[RFC3461] ENVID parameter 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 o threadId: "Id" (immutable; server-set)
to, and any RCPT TO parameters to pass with the recipient.
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: An *Address* object has the following properties:
* *email*: "String" The email address being represented by the * email: "String"
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 The email address being represented by the object. This is a
email (either mail-parameter or rcpt-parameter as appropriate, "Mailbox" as used in the Reverse-path or Forward-path of the
as specified in [RFC5321]). If supplied, each key in the MAIL FROM or RCPT TO command in [RFC5321].
object is a parameter name, and the value either the parameter
value (type "String") or if the parameter does not take a value
then "null". For both name and value, any xtext or unitext
encodings are removed ([RFC3461], [RFC6533]) and JSON string
encoding applied.
If the _envelope_ property is "null" or omitted on creation, the * parameters: "Object|null"
server MUST generate this from the referenced email as follows:
* *mailFrom*: The email in the _Sender_ header, if present, Any parameters to send with the email address (either mail-
otherwise the _From_ header, if present, and no parameters. If parameter or rcpt-parameter as appropriate, as specified in
multiple addresses are present in one of these headers, or [RFC5321]). If supplied, each key in the object is a parameter
there is more than one _Sender_/_From_ header, the server name, and the value is either the parameter value (type
SHOULD reject the email as invalid but otherwise MUST take the "String") or null if the parameter does not take a value. For
first address in the last _Sender_/_From_ header in the both name and value, any xtext or unitext encodings are removed
[RFC5322] version of the message. If the address found from (see [RFC3461] and [RFC6533]) and JSON string encoding is
this is not allowed by the identity associated with this applied.
submission, the _email_ property from the identity MUST be used
instead.
* *rcptTo*: The deduplicated set of email addresses from the If the "envelope" property is null or omitted on creation, the
_To_, _Cc_ and _Bcc_ headers, if present, with no parameters server MUST generate this from the referenced Email as follows:
for any of them.
o *sendAt*: "UTCDate" (immutable; server-set) The date the email * "mailFrom": The email address in the Sender header field, if
was/will be released for delivery. If the client successfully present; otherwise, it's the email address in the From header
used [RFC4865] FUTURERELEASE with the email, this MUST be the time field, if present. In either case, no parameters are added.
when the server will release the email; otherwise it MUST be the
time the EmailSubmission was created.
o *undoStatus*: "String" This represents whether the submission may If multiple addresses are present in one of these header
be canceled. This is server set and MUST be one of the following fields, or there is more than one Sender/From header field, the
values: 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. * "pending": It may be possible to cancel this submission.
* "final": The email has been relayed to at least one recipient * "final": The message has been relayed to at least one recipient
in a manner that cannot be recalled. It is no longer possible in a manner that cannot be recalled. It is no longer possible
to cancel this submission. to cancel this submission.
* "canceled": The email submission was canceled and will not be * "canceled": The submission was canceled and will not be
delivered to any recipient. delivered to any recipient.
On systems that do not support unsending, the value of this On systems that do not support unsending, the value of this
property will always be "final". On systems that do support property will always be "final". On systems that do support
canceling submission, it will start as "pending", and MAY canceling submission, it will start as "pending" and MAY
transition to "final" when the server knows it definitely cannot transition to "final" when the server knows it definitely cannot
recall the email, but MAY just remain "pending". If in pending recall the message, but it MAY just remain "pending". If in
state, a client can attempt to cancel the submission by setting pending state, a client can attempt to cancel the submission by
this property to "canceled"; if the update succeeds, the setting this property to "canceled"; if the update succeeds, the
submission was successfully canceled and the email has not been submission was successfully canceled, and the message has not been
delivered to any of the original recipients. delivered to any of the original recipients.
o *deliveryStatus*: "String[DeliveryStatus]|null" (server-set) This o deliveryStatus: "String[DeliveryStatus]|null" (server-set)
represents the delivery status for each of the email'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 This represents the delivery status for each of the submission's
recipient when the server last tried to relay the email, or in recipients, if known. This property MAY not be supported by all
a later DSN (Delivery Status Notification, as defined in servers, in which case it will remain null. Servers that support
[RFC3464]) response for the email. This SHOULD be the response it SHOULD update the EmailSubmission object each time the status
to the RCPT TO stage, unless this was accepted and the email as of any of the recipients changes, even if some recipients are
a whole rejected at the end of the DATA stage, in which case still being retried.
the DATA stage reply SHOULD be used instead. Multi-line SMTP
responses should be concatenated to a single string as follows: 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 + The hyphen following the SMTP code on all but the last line
is replaced with a space. is replaced with a space.
+ Any prefix in common with the first line is stripped from + Any prefix in common with the first line is stripped from
lines after the first. lines after the first.
+ CRLF is replaced by a space. + CRLF is replaced by a space.
For example: For example:
550-5.7.1 Our system has detected that this message is 550-5.7.1 Our system has detected that this message is
550 5.7.1 likely spam. 550 5.7.1 likely spam.
would become: would become:
550 5.7.1 Our system has detected that this message is likely spam. 550 5.7.1 Our system has detected that this message is likely spam.
For emails relayed via an alternative to SMTP, the server MAY For messages relayed via an alternative to SMTP, the server MAY
generate a synthetic string representing the status instead. generate a synthetic string representing the status instead.
If it does this, the string MUST be of the following form: If it does this, the string MUST be of the following form:
+ A 3-digit SMTP reply code, as defined in [RFC5321], section + A 3-digit SMTP reply code, as defined in [RFC5321],
4.2.3. Section 4.2.3.
+ Then a single space character. + Then a single space character.
+ Then an SMTP Enhanced Mail System Status Code as defined in + Then an SMTP Enhanced Mail System Status Code as defined in
[RFC3463], with a registry defined in [RFC5248]. [RFC3463], with a registry defined in [RFC5248].
+ Then a single space character. + Then a single space character.
+ Then an implementation-specific information string with a + Then an implementation-specific information string with a
human readable explanation of the response. human-readable explanation of the response.
* *delivered*: "String" Represents whether the email has been * delivered: "String"
successfully delivered to the recipient. This MUST be one of
the following values:
+ "queued": The email is in a local mail queue and status will Represents whether the message has been successfully delivered
change once it exits the local mail queues. The _smtpReply_ to the recipient. This MUST be one of the following values:
property may still change.
+ "yes": The email was successfully delivered to the mailbox + "queued": The message is in a local mail queue and the
of the recipient. The _smtpReply_ property is final. 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 + "no": Delivery to the recipient permanently failed. The
_smtpReply_ property is final. "smtpReply" property is final.
+ "unknown": The final delivery status is unknown, (e.g. it + "unknown": The final delivery status is unknown, (e.g., it
was relayed to an external machine and no further was relayed to an external machine and no further
information is available). The _smtpReply_ property may information is available). The "smtpReply" property may
still change if a DSN arrives. still change if a DSN arrives.
Note, successful relaying to an external SMTP server SHOULD NOT Note that successful relaying to an external SMTP server SHOULD
be taken as an indication that the email has successfully NOT be taken as an indication that the message has successfully
reached the final mailbox. In this case though, the server may reached the final mail store. In this case though, the server
receive a DSN response, if requested. If a DSN is received for may receive a DSN response, if requested.
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 email has been If a DSN is received for the recipient with Action equal to
displayed to the recipient. This MUST be one of the following "delivered", as per [RFC3464], Section 2.3.3, then the
values: "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 + "unknown": The display status is unknown. This is the
initial value. initial value.
+ "yes": The recipient's system claims the email content has + "yes": The recipient's system claims the message content has
been displayed to the recipient. Note, there is no been displayed to the recipient. Note that there is no
guarantee that the recipient has noticed, read, or guarantee that the recipient has noticed, read, or
understood the content. understood the content.
If an MDN is received for this recipient with Disposition-Type If a Message Disposition Notification (MDN) is received for
(as per [RFC8098] section 3.2.6.2) equal to "displayed", this this recipient with Disposition-Type (as per [RFC8098],
property SHOULD be set to "yes". The server MAY also set this Section 3.2.6.2) equal to "displayed", this property SHOULD be
property based on other feedback channels. set to "yes".
o *dsnBlobIds*: "Id[]" (server-set) A list of blob ids for Delivery The server MAY also set this property based on other feedback
Status Notifications ([RFC3464]) received for this submission, in channels.
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 Message o dsnBlobIds: "Id[]" (server-set)
Disposition Notifications ([RFC8098]) received for this
A list of blob ids for DSNs [RFC3464] received for this
submission, in order of receipt, oldest first. The blob is the submission, in order of receipt, oldest first. The blob is the
whole MIME message (with a top-level content-type of multipart/ whole MIME message (with a top-level content-type of "multipart/
report), as received. 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.
JMAP servers MAY choose not to expose DSN and MDN responses as Email JMAP servers MAY choose not to expose DSN and MDN responses as Email
objects if they correlate to an EmailSubmission object. It SHOULD objects if they correlate to an EmailSubmission object. It SHOULD
only do this if it exposes them in the _dsnBlobIds_ and _mdnblobIds_ only do this if it exposes them in the "dsnBlobIds" and "mdnblobIds"
fields instead, and expects the user to be using clients capable of fields instead, and it expects the user to be using clients capable
fetching and displaying delivery status via the EmailSubmission of fetching and displaying delivery status via the EmailSubmission
object. object.
For efficiency, a server MAY destroy EmailSubmission objects a For efficiency, a server MAY destroy EmailSubmission objects at any
certain amount of time after the email is successfully sent or it has time after the message is successfully sent or after it has finished
finished retrying sending the email. For very basic SMTP proxies, retrying to send the message. For very basic SMTP proxies, this MAY
this MAY be immediately after creation, as it has no way to assign a be immediately after creation, as it has no way to assign a real id
real id and return the information again if fetched later. and return the information again if fetched later.
The following JMAP methods are supported: The following JMAP methods are supported.
7.1. EmailSubmission/get 7.1. EmailSubmission/get
Standard "/get" method as described in [I-D.ietf-jmap-core] section This is a standard "/get" method as described in [RFC8620],
5.1. Section 5.1.
7.2. EmailSubmission/changes 7.2. EmailSubmission/changes
Standard "/changes" method as described in [I-D.ietf-jmap-core] This is a standard "/changes" method as described in [RFC8620],
section 5.2. Section 5.2.
7.3. EmailSubmission/query 7.3. EmailSubmission/query
Standard "/query" method as described in [I-D.ietf-jmap-core] section This is a standard "/query" method as described in [RFC8620],
5.5. Section 5.5.
A *FilterCondition* object has the following properties, any of which A *FilterCondition* object has the following properties, any of which
may be omitted: may be omitted:
o *identityIds*: "Id[]" The EmailSubmission _identityId_ property o identityIds: "Id[]"
must be in this list to match the condition.
o *emailIds*: "Id[]" The EmailSubmission _emailId_ property must be The EmailSubmission "identityId" property must be in this list to
in this list to match the condition. match the condition.
o *threadIds*: "Id[]" The EmailSubmission _threadId_ property must o emailIds: "Id[]"
be in this list to match the condition.
o *undoStatus*: "String" The EmailSubmission _undoStatus_ property The EmailSubmission "emailId" property must be in this list to
must be identical to the value given to match the condition. match the condition.
o *before*: "UTCDate" The _sendAt_ property of the EmailSubmission o threadIds: "Id[]"
object must be before this date-time to match the condition.
o *after*: "UTCDate" The _sendAt_ property of the EmailSubmission The EmailSubmission "threadId" property must be in this list to
object must be the same as or after this date-time to match the match the condition.
condition.
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 An EmailSubmission object matches the FilterCondition if and only if
all of the given conditions match. If zero properties are specified, all of the given conditions match. If zero properties are specified,
it is automatically "true" for all objects. it is automatically true for all objects.
The following EmailSubmission properties MUST be supported for The following EmailSubmission properties MUST be supported for
sorting: sorting:
o "emailId" o "emailId"
o "threadId" o "threadId"
o "sentAt" o "sentAt"
7.4. EmailSubmission/queryChanges 7.4. EmailSubmission/queryChanges
Standard "/queryChanges" method as described in [I-D.ietf-jmap-core] This is a standard "/queryChanges" method as described in [RFC8620],
section 5.6. Section 5.6.
7.5. EmailSubmission/set 7.5. EmailSubmission/set
Standard "/set" method as described in [I-D.ietf-jmap-core] section This is a standard "/set" method as described in [RFC8620],
5.3, with the following two additional request arguments: Section 5.3 with the following two additional request arguments:
o *onSuccessUpdateEmail*: "Id[PatchObject]|null" A map of o onSuccessUpdateEmail: "Id[PatchObject]|null"
_EmailSubmission id_ to an object containing properties to update
on the Email object referenced by the EmailSubmission if the A map of EmailSubmission id to an object containing properties to
create/update/destroy succeeds. (For references 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 EmailSubmissions created in the same "/set" invocation, this is
equivalent to a creation-reference so the id will be the creation equivalent to a creation-reference, so the id will be the creation
id prefixed with a "#".) id prefixed with a "#".)
o *onSuccessDestroyEmail*: "Id[]|null" A list of _EmailSubmission o onSuccessDestroyEmail: "Id[]|null"
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 "#".)
A single implicit _Email/set_ call MUST be made after all A list of EmailSubmission ids for which the Email with the
EmailSubmissions cred in the same "/set" invocation/update/destroy corresponding "emailId" should be destroyed if the create/update/
requests have been processed to perform any changes requested in destroy succeeds. (For references to EmailSubmission creations,
these two arguments. The response to this MUST be returned after the this is equivalent to a creation-reference, so the id will be the
_EmailSubmission/set_ response. creation id prefixed with a "#".)
An email is sent by creating an EmailSubmission object. When After all create/update/destroy items in the "EmailSubmission/set"
processing each create, the server must check that the email is invocation have been processed, a single implicit "Email/set" call
valid, and the user has sufficient authorization to send it. If the MUST be made to perform any changes requested in these two arguments.
creation succeeds, the email will be sent to the recipients given in The response to this MUST be returned after the "EmailSubmission/set"
the envelope _rcptTo_ parameter. The server MUST remove any _Bcc_ response.
header present on the email during delivery. The server MAY add or
remove other headers from the submitted email, or make further
alterations in accordance with the server's policy during delivery.
If the referenced email is destroyed at any point after the 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 EmailSubmission object is created, this MUST NOT change the behaviour
of the email submission (i.e. it does not cancel a future send). The of the submission (i.e., it does not cancel a future send). The
_emailId_ and _threadId_ properties of the submission object remain, "emailId" and "threadId" properties of the EmailSubmission object
but trying to fetch them (with a standard Email/get call) will return remain, but trying to fetch them (with a standard "Email/get" call)
a "notFound" error if the corresponding objects have been destroyed. will return a "notFound" error if the corresponding objects have been
destroyed.
Similarly, destroying an EmailSubmission object MUST NOT affect the Similarly, destroying an EmailSubmission object MUST NOT affect the
deliveries it represents. It purely removes the record of the email deliveries it represents. It purely removes the record of the
submission. The server MAY automatically destroy EmailSubmission submission. The server MAY automatically destroy EmailSubmission
objects after a certain time or in response to other triggers, and objects after some time or in response to other triggers, and MAY
MAY forbid the client from manually destroying EmailSubmission forbid the client from manually destroying EmailSubmission objects.
objects.
If the email to be sent is larger than the server supports sending, a If the message to be sent is larger than the server supports sending,
standard "tooLarge" SetError MUST be returned. A _maxSize_ a standard "tooLarge" SetError MUST be returned. A "maxSize"
"UnsignedInt" property MUST be present on the SetError specifying the "UnsignedInt" property MUST be present on the SetError specifying the
maximum size of an email that may be sent, in octets. maximum size of a message that may be sent, in octets.
If the email or identity id given cannot be found, the submission If the Email or Identity id given cannot be found, the submission
creation is rejected with a standard "invalidProperties" SetError. creation is rejected with a standard "invalidProperties" SetError.
The following extra _SetError_ types are defined: The following extra SetError types are defined:
For *create*: For "create":
o "invalidEmail" - The email to be sent is invalid in some way. The o "invalidEmail" - The Email to be sent is invalid in some way. The
SetError SHOULD contain a property called _properties_ of type SetError SHOULD contain a property called "properties" of type
"String[]" that lists *all* the properties of the email that were "String[]" that lists *all* the properties of the Email that were
invalid. invalid.
o "tooManyRecipients" - The envelope (supplied or generated) has o "tooManyRecipients" - The envelope (supplied or generated) has
more recipients than the server allows. A _maxRecipients_ more recipients than the server allows. A "maxRecipients"
"UnsignedInt" property MUST also be present on the SetError "UnsignedInt" property MUST also be present on the SetError
specifying the maximum number of allowed recipients. specifying the maximum number of allowed recipients.
o "noRecipients" - The envelope (supplied or generated) does not o "noRecipients" - The envelope (supplied or generated) does not
have any rcptTo emails. have any rcptTo email addresses.
o "invalidRecipients" - The _rcptTo_ property of the envelope o "invalidRecipients" - The "rcptTo" property of the envelope
(supplied or generated) contains at least one rcptTo value which (supplied or generated) contains at least one rcptTo value, which
is not a valid email for sending to. An _invalidRecipients_ is not a valid email address for sending to. An
"String[]" property MUST also be present on the SetError, which is "invalidRecipients" "String[]" property MUST also be present on
a list of the invalid addresses. the SetError, which is a list of the invalid addresses.
o "forbiddenMailFrom" - The server does not permit the user to send o "forbiddenMailFrom" - The server does not permit the user to send
an email with the [RFC5321] envelope From. a message with the envelope From address [RFC5321].
o "forbiddenFrom" - The server does not permit the user to send an o "forbiddenFrom" - The server does not permit the user to send a
email with the [RFC5322] From header of the email to be sent. message with the From header field [RFC5322] of the message to be
sent.
o "forbiddenToSend" - The user does not have permission to send at o "forbiddenToSend" - The user does not have permission to send at
all right now for some reason. A _description_ "String" property all right now for some reason. A "description" "String" property
MAY be present on the SetError object to display to the user why MAY be present on the SetError object to display to the user why
they are not permitted. they are not permitted.
For *update*: For "update":
o "cannotUnsend": The client attempted to update the _undoStatus_ of o "cannotUnsend" - The client attempted to update the "undoStatus"
a valid EmailSubmission object from "pending" to "canceled", but of a valid EmailSubmission object from "pending" to "canceled",
the email cannot be unsent. but the message cannot be unsent.
7.5.1. Example 7.5.1. Example
The following example presumes a draft of the message to be sent has The following example presumes a draft of the Email to be sent has
already been saved, and its Email id is "M7f6ed5bcfd7e2604d1753f6c". already been saved, and its Email id is "M7f6ed5bcfd7e2604d1753f6c".
This call then sends the email immediately, and if successful removes This call then sends the Email immediately, and if successful,
the draft flag and moves it from the Drafts folder (which has Mailbox removes the "$draft" flag and moves it from the drafts folder (which
id "7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e") to the Sent folder (which has Mailbox id "7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e") to the sent
we presume has Mailbox id "73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6"). folder (which we presume has Mailbox id "73dbcb4b-bffc-48bd-8c2a-
a2e91ca672f6").
[[ "EmailSubmission/set", { [[ "EmailSubmission/set", {
"accountId": "ue411d190", "accountId": "ue411d190",
"create": { "create": {
"k1490": { "k1490": {
"identityId": "I64588216", "identityId": "I64588216",
"emailId": "M7f6ed5bcfd7e2604d1753f6c", "emailId": "M7f6ed5bcfd7e2604d1753f6c",
"envelope": { "envelope": {
"mailFrom": { "mailFrom": {
"email": "john@example.com", "email": "john@example.com",
skipping to change at page 72, line 34 skipping to change at page 85, line 5
}, },
"onSuccessUpdateEmail": { "onSuccessUpdateEmail": {
"#k1490": { "#k1490": {
"mailboxIds/7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e": null, "mailboxIds/7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e": null,
"mailboxIds/73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6": true, "mailboxIds/73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6": true,
"keywords/$draft": null "keywords/$draft": null
} }
} }
}, "0" ]] }, "0" ]]
A successful response might look like this. Note there are two 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 responses due to the implicit "Email/set" call, but both have the
method call id as they are due to the same call in the request: same method call id as they are due to the same call in the request:
[[ "EmailSubmission/set", { [[ "EmailSubmission/set", {
"accountId": "ue411d190", "accountId": "ue411d190",
"oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21", "oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"newState": "355421f6-8aed-4cf4-a0c4-7377e951af36", "newState": "355421f6-8aed-4cf4-a0c4-7377e951af36",
"created": { "created": {
"k1490": { "k1490": {
"id": "ES-3bab7f9a-623e-4acf-99a5-2e67facb02a0" "id": "ES-3bab7f9a-623e-4acf-99a5-2e67facb02a0"
} }
} }
}, "0" ], }, "0" ],
[ "Email/set", { [ "Email/set", {
"accountId": "ue411d190", "accountId": "ue411d190",
"oldState": "778193", "oldState": "778193",
"newState": "778197", "newState": "778197",
"updated": { "updated": {
"M7f6ed5bcfd7e2604d1753f6c": null "M7f6ed5bcfd7e2604d1753f6c": null
} }
}, "0" ]] }, "0" ]]
Suppose instead an admin has removed sending rights for the user, and Suppose instead an admin has removed sending rights for the user, so
so the email submission is rejected with a "forbiddenToSend" error. the submission is rejected with a "forbiddenToSend" error. The
The description argument of the error is intended for display to the description argument of the error is intended for display to the
user, so should be localised appropriately. Let's suppose the user, so it should be localised appropriately. Let's suppose the
request was sent with an Accept-Language header like this: request was sent with an Accept-Language header like this:
Accept-Language: de;q=0.9,en;q=0.8 Accept-Language: de;q=0.9,en;q=0.8
The server should attempt to choose the best localisation from those The server should attempt to choose the best localisation from those
it has available based on the Accept-Language header, as described in it has available based on the Accept-Language header, as described in
[I-D.ietf-jmap-core], section 3.7. If the server has English, French [RFC8620], Section 3.8. If the server has English, French, and
and German translations it would choose German as the preferred German translations, it would choose German as the preferred language
language and return a response like this: and return a response like this:
[[ "EmailSubmission/set", { [[ "EmailSubmission/set", {
"accountId": "ue411d190", "accountId": "ue411d190",
"oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21", "oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"newState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21", "newState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"notCreated": { "notCreated": {
"k1490": { "k1490": {
"type": "forbiddenToSend", "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." "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" ]] }, "0" ]]
8. Vacation response
A vacation response automatically sends a reply to messages sent to a 8. Vacation Response
particular account, to inform the original sender that their message
may not be read for some time. Automated message sending can produce A vacation response sends an automatic reply when a message is
undesirable behaviour. To avoid this, implementors MUST follow the delivered to the mail store, informing the original sender that their
recommendations set forth in [RFC3834]. 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- The *VacationResponse* object represents the state of vacation-
response related settings for an account. It has the following response-related settings for an account. It has the following
properties: properties:
o *id*: "Id" (immutable; server-set) The id of the object. There is o id: "Id" (immutable; server-set)
only ever one vacation response object, and its id is
""singleton"".
o *isEnabled*: "Boolean" Should a vacation response be sent if an The id of the object. There is only ever one VacationResponse
email arrives between the _fromDate_ and _toDate_? object, and its id is "singleton".
o *fromDate*: "UTCDate|null" If _isEnabled_ is "true" emails that o isEnabled: "Boolean"
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", emails that Should a vacation response be sent if a message arrives between
arrive before this date-time (but on or after the _fromDate_ if the "fromDate" and "toDate"?
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 o fromDate: "UTCDate|null"
message sent in response to emails when the vacation response is
enabled. If "null", an appropriate subject SHOULD be set by the
server.
o *textBody*: "String|null" The plain text body to send in response If "isEnabled" is true, messages that arrive on or after this
to emails when the vacation response is enabled. If this is date-time (but before the "toDate" if defined) should receive the
"null", when the vacation message is sent a plain-text body part user's vacation response. If null, the vacation response is
SHOULD be generated from the _htmlBody_ but the server MAY choose effective immediately.
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 o toDate: "UTCDate|null"
emails when the vacation response is enabled. If this is "null",
when the vacation message is sent an HTML body part MAY be
generated from the _textBody_, or the server MAY choose to send
the response as plain-text only.
The following JMAP methods are supported: 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 8.1. VacationResponse/get
Standard "/get" method as described in [I-D.ietf-jmap-core] section This is a standard "/get" method as described in [RFC8620],
5.1. Section 5.1.
There MUST only be exactly one VacationResponse object in an account. There MUST only be exactly one VacationResponse object in an account.
It MUST have the id "singleton". It MUST have the id "singleton".
8.2. VacationResponse/set 8.2. VacationResponse/set
Standard "/set" method as described in [I-D.ietf-jmap-core] section This is a standard "/set" method as described in [RFC8620],
5.3. Section 5.3.
9. Security considerations 9. Security Considerations
All security considerations of JMAP ([I-D.ietf-jmap-core]) apply to All security considerations of JMAP [RFC8620] apply to this
this specification. Additional considerations specific to the data specification. Additional considerations specific to the data types
types and functionality introduced by this document are described in and functionality introduced by this document are described in the
the following subsections. following subsections.
9.1. EmailBodyPart value 9.1. EmailBodyPart Value
Service providers typically perform security filtering on incoming Service providers typically perform security filtering on incoming
email and it's important that the detection of content-type and messages, and it's important that the detection of content-type and
charset for the security filter aligns with the heuristics performed charset for the security filter aligns with the heuristics performed
by JMAP servers. Servers that apply heuristics to determine the by JMAP servers. Servers that apply heuristics to determine the
content-type or charset for _EmailBodyValue_ SHOULD document the content-type or charset for an EmailBodyValue SHOULD document the
heuristics and provide a mechanism to turn them off in the event they heuristics and provide a mechanism to turn them off in the event they
are misaligned with the security filter used at a particular mailbox are misaligned with the security filter used at a particular mail
host. host.
Automatic conversion of charsets that allow hidden channels for ASCII Automatic conversion of charsets that allow hidden channels for ASCII
text, such as UTF-7, have been problematic for security filters in text, such as UTF-7, have been problematic for security filters in
the past so server implementations can mitigate this risk by having the past, so server implementations can mitigate this risk by having
such conversions off-by-default and/or separately configurable. such conversions off-by-default and/or separately configurable.
To allow the client to restrict the volume of data it can receive in 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 response to a request, a maximum length may be requested for the data
returned for a textual body part. However, truncating the data may returned for a textual body part. However, truncating the data may
change the semantic meaning, for example truncating a URL changes its change the semantic meaning, for example, truncating a URL changes
location. Servers that scan for links to malicious sites should take its location. Servers that scan for links to malicious sites should
care to either ensure truncation is not at a semantically significant take care to either ensure truncation is not at a semantically
point, or to rescan the truncated value for malicious content before significant point or rescan the truncated value for malicious content
returning it. before returning it.
9.2. HTML email display 9.2. HTML Email Display
HTML message bodies provide richer formatting for emails but present HTML message bodies provide richer formatting for messages but
a number of security challenges, especially when embedded in a present a number of security challenges, especially when embedded in
webmail context in combination with interface HTML. Clients that a webmail context in combination with interface HTML. Clients that
render HTML email should make careful consideration of the potential render HTML messages should carefully consider the potential risks,
risks, including: including:
o Embedded JavaScript can rewrite the email to change its content on o Embedded JavaScript can rewrite the message to change its content
subsequent opening, allowing users to be mislead. In webmail on subsequent opening, allowing users to be mislead. In webmail
systems, if run in the same origin as the interface it can access systems, if run in the same origin as the interface, it can access
and exfiltrate all private data accessible to the user, including and exfiltrate all private data accessible to the user, including
all other emails and potentially contacts, calendar events, all other messages and potentially contacts, calendar events,
settings, and credentials. It can also rewrite the interface to settings, and credentials. It can also rewrite the interface to
undetectably phish passwords. A compromise is likely to be undetectably phish passwords. A compromise is likely to be
persistent, not just for the duration of page load, due to persistent, not just for the duration of page load, due to
exfiltration of session credentials or installation of a service exfiltration of session credentials or installation of a service
worker that can intercept all subsequent network requests (this worker that can intercept all subsequent network requests
however would only be possible if blob downloads are also (however, this would only be possible if blob downloads are also
available on the same origin, and the service worker script is available on the same origin, and the service worker script is
attached to the message). attached to the message).
o HTML documents may load content directly from the internet, rather o HTML documents may load content directly from the Internet rather
than just referencing attached resources. For example you may than just referencing attached resources. For example, you may
have an "<img>" tag with an external "src" attribute. This 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 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 address of the recipient. Cookies may also be sent and set by the
server, allowing tracking between different emails and even server, allowing tracking between different messages and even
website visits and advertising profiles. website visits and advertising profiles.
o In webmail systems, CSS can break the layout or create phishing o In webmail systems, CSS can break the layout or create phishing
vulnerabilities. For example, the use of "position:fixed" can vulnerabilities. For example, the use of "position:fixed" can
allow an email to draw content outside of its normal bounds, allow a message to draw content outside of its normal bounds,
potentially clickjacking a real interface element. potentially clickjacking a real interface element.
o If in a webmail context and not inside a separate frame, any o If in a webmail context and not inside a separate frame, any
styles defined in CSS rules will apply to interface elements as styles defined in CSS rules will apply to interface elements as
well if the selector matches, allowing the interface to be well if the selector matches, allowing the interface to be
modified. Similarly, any interface styles that match elements in modified. Similarly, any interface styles that match elements in
the email will alter their appearance, potentially breaking the the message will alter their appearance, potentially breaking the
layout of the email. layout of the message.
o The link text in HTML has no necessary correlation with the actual 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 target of the link, which can be used to make phishing attacks
more convincing. more convincing.
o Links opened from an email or embedded external content may leak o Links opened from a message or embedded external content may leak
private info in the "Referer" header sent by default in most private info in the Referer header sent by default in most
systems. systems.
o Forms can be used to mimic login boxes, providing a potent o Forms can be used to mimic login boxes, providing a potent
phishing vector if allowed to submit directly from the email phishing vector if allowed to submit directly from the message
display. display.
There are a number of ways clients can mitigate these issues, and a There are a number of ways clients can mitigate these issues, and a
defence-in-depth approach that uses a combination of techniques will defence-in-depth approach that uses a combination of techniques will
provide the strongest security. provide the strongest security.
o HTML can be filtered before rendering, stripping potentially o HTML can be filtered before rendering, stripping potentially
malicious content. Sanitizing HTML correctly is tricky, and malicious content. Sanitising HTML correctly is tricky, and
implementers are strongly recommended to use a well-tested library implementors are strongly recommended to use a well-tested library
with a carefully vetted whitelist-only approach. New features with a carefully vetted whitelist-only approach. New features
with unexpected security characteristics may be added to HTML with unexpected security characteristics may be added to HTML
rendering engines in the future; a blacklist approach is likely to rendering engines in the future; a blacklist approach is likely to
result in security issues. result in security issues.
Subtle differences in parsing of HTML can introduce security flaws: Subtle differences in parsing of HTML can introduce security
to filter with 100% accuracy you need to use the same parser when flaws: to filter with 100% accuracy, you need to use the same
sanitizing that the HTML rendering engine will use. parser that the HTML rendering engine will use.
o Encapsulating the message in an "<iframe sandbox>", as defined in o Encapsulating the message in an "<iframe sandbox>", as defined in
[HTML], section 4.7.6, can help mitigate a number of risks. This [HTML], Section 4.7.6, can help mitigate a number of risks. This
will: will:
* Disable JavaScript. * Disable JavaScript.
* Disable form submission. * Disable form submission.
* Prevent drawing outside of its bounds, or conflict with * Prevent drawing outside of its bounds or conflicts between
interface CSS. message CSS and interface CSS.
* Establish a unique anonymous origin, separate to the containing * Establish a unique anonymous origin, separate to the containing
origin. origin.
o A strong Content Security Policy [3] can, among other things, o A strong Content Security Policy (see <https://www.w3.org/TR/
block JavaScript and loading of external content should it manage CSP3/>) can, among other things, block JavaScript and the loading
to evade the filter. of external content should it manage to evade the filter.
o The leakage of information in the Referer header can be mitigated o The leakage of information in the Referer header can be mitigated
with the use of a referrer policy [4]. 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 o A "crossorigin=anonymous" attribute on tags that load remote
content can prevent cookies from being sent. content can prevent cookies from being sent.
o If adding "target=_blank" to open links in new tabs, also add 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 "rel=noopener" to ensure the page that opens cannot change the URL
in the original tab to redirect the user to a phishing site. in the original tab to redirect the user to a phishing site.
As highly complex software components, HTML rendering engines As highly complex software components, HTML rendering engines
increase the attack surface of a client considerably, especially when increase the attack surface of a client considerably, especially when
being used to process untrusted, potentially malicious content. being used to process untrusted, potentially malicious content.
Serious bugs have been found in image decoders, JavaScript engines
Serious bugs have been found in image decoders, JavaScript engines,
and HTML parsers in the past, which could lead to full system and HTML parsers in the past, which could lead to full system
compromise. Clients using an engine should ensure they get the compromise. Clients using an engine should ensure they get the
latest version and continue to incorporate any security patches latest version and continue to incorporate any security patches
released by the vendor. released by the vendor.
9.3. Multiple part display 9.3. Multiple Part Display
Messages may consist of multiple parts to be displayed sequentially Messages may consist of multiple parts to be displayed sequentially
as a body. Clients MUST render each part in isolation and MUST NOT 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 concatenate the raw text values to render. Doing so may change the
overall semantics of the message. If the client or server is overall semantics of the message. If the client or server is
decrypting a PGP or S/MIME encrypted part, concatenating with other decrypting a Pretty Good Privacy (PGP) or S/MIME encrypted part,
parts may leak the decrypted text to an attacker, as described in concatenating with other parts may leak the decrypted text to an
[EFAIL]. attacker, as described in [EFAIL].
9.4. Email submission 9.4. Email Submission
SMTP submission servers [RFC6409] use a number of mechanisms to SMTP submission servers [RFC6409] use a number of mechanisms to
mitigate damage caused by compromised user accounts and end-user mitigate damage caused by compromised user accounts and end-user
systems including rate limiting, anti-virus/anti-spam milters (mail systems including rate limiting, anti-virus/anti-spam milters (mail
filters) and other technologies. The technologies work better when filters), and other technologies. The technologies work better when
they have more information about the client connection. If JMAP they have more information about the client connection. If JMAP
email submission is implemented as a proxy to an SMTP Submission email submission is implemented as a proxy to an SMTP submission
server, it is useful to communicate this information from the JMAP server, it is useful to communicate this information from the JMAP
proxy to the submission server. The de-facto [XCLIENT] extension to proxy to the submission server. The de facto XCLIENT extension to
SMTP can be used to do this, but use of an authenticated channel is SMTP [XCLIENT] can be used to do this, but use of an authenticated
recommended to limit use of that extension to explicitly authorized channel is recommended to limit use of that extension to explicitly
proxies. authorised proxies.
JMAP servers that proxy to an SMTP Submission server SHOULD allow use JMAP servers that proxy to an SMTP submission server SHOULD allow use
of the _submissions_ port [RFC8314]. Implementation of a mechanism of the submissions port [RFC8314]. Implementation of a mechanism
similar to SMTP XCLIENT is strongly encouraged. While SASL PLAIN similar to SMTP XCLIENT is strongly encouraged. While Simple
over TLS [RFC4616] is presently the mandatory-to-implement mechanism Authentication and Security Layer (SASL) PLAIN over TLS [RFC4616] is
for interoperability with SMTP submission servers [RFC4954], a JMAP presently the mandatory-to-implement mechanism for interoperability
submission proxy SHOULD implement and prefer a stronger mechanism for with SMTP submission servers [RFC4954], a JMAP submission proxy
this use case such as TLS client certificate authentication with SASL SHOULD implement and prefer a stronger mechanism for this use case
EXTERNAL ([RFC4422] appendix A) or SCRAM [RFC7677]. 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 In the event the JMAP server directly relays mail to SMTP servers in
other administrative domains, then implementation of the de-facto other administrative domains, implementation of the de facto [milter]
protocol is strongly encouraged to integrate with third-party
[milter] protocol is strongly encouraged to integrate with third- products that address security issues including anti-virus/anti-spam,
party products that address security issues including anti-virus/ reputation protection, compliance archiving, and data loss
anti-spam, reputation protection, compliance archiving, and data loss prevention. Proxying to a local SMTP submission server may be a
prevention. Proxying to a local SMTP Submission server may be a
simpler way to provide such security services. simpler way to provide such security services.
9.5. Partial account access 9.5. Partial Account Access
A user may only have permission to access a subset of the data that A user may only have permission to access a subset of the data that
exists in an account. To avoid leaking unauthorised information, in exists in an account. To avoid leaking unauthorised information, in
such a situation the server MUST treat any data the user does not 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. have permission to access the same as if it did not exist.
For example, suppose user A has an account with two mailboxes, Inbox 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 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 user B fetches Mailboxes for this account, the server MUST behave as
though the Sent mailbox did not exist. Similarly when querying or though the sent Mailbox did not exist. Similarly, when querying or
fetching Email objects, it MUST treat any messages that just belong fetching Email objects, it MUST treat any messages that just belong
to the Sent mailbox as though they did not exist. Fetching Thread to the sent Mailbox as though they did not exist. Fetching Thread
objects MUST only return ids for Email objects the user has objects MUST only return ids for Email objects the user has
permission to access; if none, the Thread again MUST be treated the permission to access; if none, the Thread again MUST be treated the
same as if it did not exist. same as if it did not exist.
If the server forbids a single account from having two identical If the server forbids a single account from having two identical
messages, or two messages with the same "Message-Id" header field, a messages, or two messages with the same Message-Id header field, a
user with write access can use the error returned trying to create/ user with write access can use the error returned by trying to
import such a message to detect whether it already exists in an create/import such a message to detect whether it already exists in
inaccessible portion of the account. an inaccessible portion of the account.
9.6. Permission to send from an address 9.6. Permission to Send from an Address
The email ecosystem has in recent years moved towards associating In recent years, the email ecosystem has moved towards associating
trust with the From address in the [RFC5322] message, particularly trust with the From address in the message [RFC5322], particularly
with schemes such as DMARC ([RFC7489]). 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 The set of Identity objects (see Section 6) in an account lets the
client know which email addresses the user has permission to send client know which email addresses the user has permission to send
from. Each email submission is associated with an identity, and from. Each email submission is associated with an Identity, and
servers SHOULD reject submissions where the "From" header field of servers SHOULD reject submissions where the From header field of the
the email does not correspond to the associated identity. message does not correspond to the associated Identity.
The server MAY allow an exception to send an exact copy of an The server MAY allow an exception to send an exact copy of an
existing message received into the mail store to another address existing message received into the mail store to another address
(otherwise known as "redirecting" or "bouncing"), although it is (otherwise known as "redirecting" or "bouncing"), although it is
RECOMMENDED the server limit this to destinations the user has RECOMMENDED the server limit this to destinations the user has
verified they also control. verified they also control.
If the user attempts to create a new Identity, the server MUST reject If the user attempts to create a new Identity object, the server MUST
it with the appropriate error if the user does not have permission to reject it with the appropriate error if the user does not have
use that email address to send from. permission to use that email address to send from.
The [RFC5321] SMTP MAIL FROM address is often confused with the The SMTP MAIL FROM address [RFC5321] is often confused with the From
[RFC5322] message header. The user generally only ever sees the message header field [RFC5322]. The user generally only ever sees
message header address, and this is the primary one to enforce. the address in the message header field, and this is the primary one
However the server MUST also enforce appropriate restrictions on the to enforce. However, the server MUST also enforce appropriate
[RFC5321] MAIL FROM address to stop the user from flooding a 3rd restrictions on the MAIL FROM address [RFC5321] to stop the user from
party address with bounces and non-delivery notices. flooding a third-party address with bounces and non-delivery notices.
The JMAP submission model provides separate errors for impermissible The JMAP submission model provides separate errors for impermissible
addresses in either context. addresses in either context.
10. IANA considerations 10. IANA Considerations
10.1. JMAP capability registration for "mail" 10.1. JMAP Capability Registration for "mail"
IANA will register the "mail" JMAP Capability as follows: IANA has registered the "mail" JMAP Capability as follows:
Capability Name: "urn:ietf:params:jmap:mail" Capability Name: urn:ietf:params:jmap:mail
Specification document: this document Specification document: this document
Intended use: common Intended use: common
Change Controller: IETF Change Controller: IETF
Security and privacy considerations: this document, section 9 Security and privacy considerations: this document, Section 9
10.2. JMAP capability registration for "submission" 10.2. JMAP Capability Registration for "submission"
IANA will register the "submission" JMAP Capability as follows: IANA has registered the "submission" JMAP Capability as follows:
Capability Name: "urn:ietf:params:jmap:submission" Capability Name: urn:ietf:params:jmap:submission
Specification document: this document Specification document: this document
Intended use: common Intended use: common
Change Controller: IETF Change Controller: IETF
Security and privacy considerations: this document, section 9 Security and privacy considerations: this document, Section 9
10.3. JMAP capability registration for "vacationresponse" 10.3. JMAP Capability Registration for "vacationresponse"
IANA will register the "vacationresponse" JMAP Capability as follows: IANA has registered the "vacationresponse" JMAP Capability as
follows:
Capability Name: "urn:ietf:params:jmap:vacationresponse" Capability Name: urn:ietf:params:jmap:vacationresponse
Specification document: this document Specification document: this document
Intended use: common Intended use: common
Change Controller: IETF Change Controller: IETF
Security and privacy considerations: this document, section 9 Security and privacy considerations: this document, Section 9
10.4. IMAP and JMAP keywords registry 10.4. IMAP and JMAP Keywords Registry
This document makes two changes to the IMAP keywords registry as This document makes two changes to the IMAP keywords registry as
defined in [RFC5788]. defined in [RFC5788].
First, the name of the registry is changed to the "IMAP and JMAP First, the name of the registry is changed to the "IMAP and JMAP
keywords Registry". Keywords" registry.
Second, a scope column is added to the template and registry Second, a scope column is added to the template and registry
indicating whether a keyword applies to IMAP-only, JMAP-only, both, indicating whether a keyword applies to "IMAP-only", "JMAP-only",
or reserved. All keywords presently in the IMAP keyword registry "both", or "reserved". All keywords already in the IMAP keyword
will be marked with a scope of both. The "reserved" status can be registry have been marked with a scope of "both". The "reserved"
used to prevent future registration of a name that would be confusing status can be used to prevent future registration of a name that
if registered. Registration of keywords with scope 'reserved' omit would be confusing if registered. Registration of keywords with
most fields in the registration template (see registration of scope "reserved" omit most fields in the registration template (see
"$recent" below for an example); such registrations are intended to registration of "$recent" below for an example); such registrations
be infrequent. are intended to be infrequent.
IMAP clients MAY silently ignore any keywords marked JMAP-only or IMAP clients MAY silently ignore any keywords marked "JMAP-only" or
reserved in the event they appear in protocol. JMAP clients MAY "reserved" in the event they appear in protocol. JMAP clients MAY
silently ignore any keywords marked IMAP-only or reserved in the silently ignore any keywords marked "IMAP-only" or "reserved" in the
event they appear in protocol. event they appear in protocol.
New JMAP-only keywords are registered in the following sub-sections. New "JMAP-only" keywords are registered in the following subsections.
These keywords correspond to IMAP system keywords and are thus not These keywords correspond to IMAP system keywords and are thus not
appropriate for use in IMAP. These keywords can not be subsequently appropriate for use in IMAP. These keywords cannot be subsequently
registered for use in IMAP except via standards action. registered for use in IMAP except via standards action.
10.4.1. Registration of JMAP keyword '$draft' 10.4.1. Registration of JMAP Keyword "$draft"
This registers the JMAP-only keyword '$draft' in the "IMAP and JMAP This registers the "JMAP-only" keyword "$draft" in the "IMAP and JMAP
keywords Registry". Keywords" registry.
Keyword name: $draft
Keyword name: "$draft"
Scope: JMAP-only Scope: JMAP-only
Purpose (description): This is set when the user wants to treat the Purpose (description): This is set when the user wants to treat the
message as a draft the user is composing. This is the JMAP message as a draft the user is composing. This is the JMAP
equivalent of the IMAP \Draft flag. equivalent of the IMAP \Draft flag.
Private or Shared on a server: BOTH Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action: Is it an advisory keyword or may it cause an automatic action:
Automatic. If the account has a mailbox marked with the \Drafts Automatic. If the account has an IMAP mailbox marked with the
special use [RFC6154], setting this flag MAY cause the message to \Drafts special use attribute [RFC6154], setting this flag MAY cause
appear in that mailbox automatically. Certain JMAP computed values the message to appear in that mailbox automatically. Certain JMAP
such as _unreadEmails_ will change as a result of changing this flag. computed values such as "unreadEmails" will change as a result of
In addition, mail clients typically will present draft messages in a changing this flag. In addition, mail clients will typically present
composer window rather than a viewer window. 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 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 JMAP client when referring to a draft message. One model for draft
emails would result in clearing this flag in an EmailSubmission/set Emails would result in clearing this flag in an "EmailSubmission/set"
operation with an onSuccessUpdateEmail attribute. In a mailstore operation with an "onSuccessUpdateEmail" argument. In a mail store
shared by JMAP and IMAP, this is also set and cleared as necessary so shared by JMAP and IMAP, this is also set and cleared as necessary so
it matches the IMAP \Draft flag. it matches the IMAP \Draft flag.
Related keywords: None Related keywords: None
Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154] Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]
Security Considerations: A server implementing this keyword as a Security Considerations: A server implementing this keyword as a
shared keyword may disclose that a user considers the message a draft shared keyword may disclose that a user considers the message a draft
message. This information would be exposed to other users with read message. This information would be exposed to other users with read
permission for the mailbox keywords. permission for the Mailbox keywords.
Published specification (recommended): this document Published specification: this document
Person & email address to contact for further information: (editor- Person & email address to contact for further information:
contact-goes-here) JMAP mailing list <jmap@ietf.org>
Intended usage: COMMON Intended usage: COMMON
Owner/Change controller: IESG Owner/Change controller: IESG
10.4.2. Registration of JMAP keyword '$seen' 10.4.2. Registration of JMAP Keyword "$seen"
This registers the JMAP-only keyword '$seen' in the "IMAP and JMAP This registers the "JMAP-only" keyword "$seen" in the "IMAP and JMAP
keywords Registry". Keywords" registry.
Keyword name: $seen
Keyword name: "$seen"
Scope: JMAP-only Scope: JMAP-only
Purpose (description): This is set when the user wants to treat the 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. message as read. This is the JMAP equivalent of the IMAP \Seen flag.
Private or Shared on a server: BOTH Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action: Is it an advisory keyword or may it cause an automatic action:
Advisory. However, certain JMAP computed values such as Advisory. However, certain JMAP computed values such as
_unreadEmails_ will change as a result of changing this flag. "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/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 when it presents the message content to the user; clients often offer
an option to clear this flag. In a mailstore shared by JMAP and 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, this is also set and cleared as necessary so it matches the
IMAP \Seen flag. IMAP \Seen flag.
Related keywords: None Related keywords: None
Related IMAP/JMAP Capabilities: None Related IMAP/JMAP Capabilities: None
Security Considerations: A server implementing this keyword as a Security Considerations: A server implementing this keyword as a
shared keyword may disclose that a user considers the message to have shared keyword may disclose that a user considers the message to have
been read. This information would be exposed to other users with been read. This information would be exposed to other users with
read permission for the mailbox keywords. read permission for the Mailbox keywords.
Published specification (recommended): this document Published specification: this document
Person & email address to contact for further information: (editor- Person & email address to contact for further information:
contact-goes-here) JMAP mailing list <jmap@ietf.org>
Intended usage: COMMON Intended usage: COMMON
Owner/Change controller: IESG Owner/Change controller: IESG
10.4.3. Registration of JMAP keyword '$flagged' 10.4.3. Registration of JMAP Keyword "$flagged"
This registers the JMAP-only keyword '$flagged' in the "IMAP and JMAP This registers the "JMAP-only" keyword "$flagged" in the "IMAP and
keywords Registry". JMAP Keywords" registry.
Keyword name: "$flagged" Keyword name: $flagged
Scope: JMAP-only Scope: JMAP-only
Purpose (description): This is set when the user wants to treat the Purpose (description): This is set when the user wants to treat the
message as flagged for urgent/special attention. This is the JMAP message as flagged for urgent/special attention. This is the JMAP
equivalent of the IMAP \Flagged flag. equivalent of the IMAP \Flagged flag.
Private or Shared on a server: BOTH Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action: Is it an advisory keyword or may it cause an automatic action:
Automatic. If the account has a mailbox marked with the \Flagged Automatic. If the account has an IMAP mailbox marked with the
special use [RFC6154], setting this flag MAY cause the message to \Flagged special use attribute [RFC6154], setting this flag MAY cause
appear in that mailbox automatically. the message to appear in that mailbox automatically.
When/by whom the keyword is set/cleared: JMAP clients typically allow When/by whom the keyword is set/cleared: JMAP clients typically allow
a user to set/clear this flag as desired. In a mailstore shared by 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 JMAP and IMAP, this is also set and cleared as necessary so it
matches the IMAP \Flagged flag. matches the IMAP \Flagged flag.
Related keywords: None Related keywords: None
Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154] Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]
Security Considerations: A server implementing this keyword as a Security Considerations: A server implementing this keyword as a
shared keyword may disclose that a user considers the message as shared keyword may disclose that a user considers the message as
flagged for urgent/special attention. This information would be flagged for urgent/special attention. This information would be
exposed to other users with read permission for the mailbox keywords. exposed to other users with read permission for the Mailbox keywords.
Published specification (recommended): this document Published specification: this document
Person & email address to contact for further information: (editor- Person & email address to contact for further information:
contact-goes-here) JMAP mailing list <jmap@ietf.org>
Intended usage: COMMON Intended usage: COMMON
Owner/Change controller: IESG Owner/Change controller: IESG
10.4.4. Registration of JMAP keyword '$answered' 10.4.4. Registration of JMAP Keyword "$answered"
This registers the JMAP-only keyword '$answered' in the "IMAP and This registers the "JMAP-only" keyword "$answered" in the "IMAP and
JMAP keywords Registry". JMAP Keywords" registry.
Keyword name: "$answered" Keyword name: $answered
Scope: JMAP-only Scope: JMAP-only
Purpose (description): This is set when the message has been Purpose (description): This is set when the message has been
answered. answered.
Private or Shared on a server: BOTH Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action: Is it an advisory keyword or may it cause an automatic action:
Advisory. Advisory.
When/by whom the keyword is set/cleared: JMAP clients typically set 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 this when submitting a reply or answer to the message. It may be set
by the EmailSubmission/set operation with an onSuccessUpdateEmail by the "EmailSubmission/set" operation with an "onSuccessUpdateEmail"
attribute. In a mailstore shared by JMAP and IMAP, this is also set 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. and cleared as necessary so it matches the IMAP \Answered flag.
Related keywords: None Related keywords: None
Related IMAP/JMAP Capabilities: None Related IMAP/JMAP Capabilities: None
Security Considerations: A server implementing this keyword as a Security Considerations: A server implementing this keyword as a
shared keyword may disclose that a user has replied to a message. shared keyword may disclose that a user has replied to a message.
This information would be exposed to other users with read permission This information would be exposed to other users with read permission
for the mailbox keywords. for the Mailbox keywords.
Published specification (recommended): this document Published specification: this document
Person & email address to contact for further information: (editor- Person & email address to contact for further information:
contact-goes-here) JMAP mailing list <jmap@ietf.org>
Intended usage: COMMON Intended usage: COMMON
Owner/Change controller: IESG Owner/Change controller: IESG
10.4.5. Registration of '$recent' keyword 10.4.5. Registration of "$recent" Keyword
This registers the keyword '$recent' in the "IMAP and JMAP keywords This registers the keyword "$recent" in the "IMAP and JMAP Keywords"
Registry". registry.
Keyword name: "$recent" Keyword name: $recent
Scope: reserved Scope: reserved
Purpose (description): This keyword is not used to avoid confusion Purpose (description): This keyword is not used to avoid confusion
with the IMAP \Recent system flag. with the IMAP \Recent system flag.
Published specification (recommended): this document Published specification: this document
Person & email address to contact for further information: (editor- Person & email address to contact for further information:
contact-goes-here) JMAP mailing list <jmap@ietf.org>
Owner/Change controller: IESG Owner/Change controller: IESG
10.5. Registration of "inbox" role in 10.5. IMAP Mailbox Name Attributes Registry
This registers the JMAP-only "inbox" attribute in the "IMAP Mailbox 10.5.1. Registration of "inbox" Role
Name Attributes Registry", as established in [RFC8457].
This registers the "JMAP-only" "inbox" attribute in the "IMAP Mailbox
Name Attributes" registry, as established in [RFC8457].
Attribute Name: Inbox Attribute Name: Inbox
Description: New mail is delivered here by default. Description: New mail is delivered here by default.
Reference: This document, section 10.5. Reference: This document, Section 10.5.1
Usage Notes: JMAP only Usage Notes: JMAP only
10.6. JMAP Error Codes registry 10.6. JMAP Error Codes Registry
The following sub-sections register several new error codes in the The following subsections register several new error codes in the
JMAP Error Codes registry, as defined in [I-D.ietf-jmap-core]. "JMAP Error Codes" registry, as defined in [RFC8620].
10.6.1. mailboxHasChild 10.6.1. mailboxHasChild
JMAP Error Code: mailboxHasChild JMAP Error Code: mailboxHasChild
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 2.5 Reference: This document, Section 2.5
Description: The mailbox still has at least one child mailbox. The Description: The Mailbox still has at least one child Mailbox. The
client MUST remove these before it can delete the parent mailbox. client MUST remove these before it can delete the parent Mailbox.
10.6.2. mailboxHasEmail 10.6.2. mailboxHasEmail
JMAP Error Code: mailboxHasEmail JMAP Error Code: mailboxHasEmail
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 2.5 Reference: This document, Section 2.5
Description: The mailbox has at least one message assigned to it and Description: The Mailbox has at least one message assigned to it, and
the onDestroyRemoveMessages argument was false. the onDestroyRemoveEmails argument was false.
10.6.3. blobNotFound 10.6.3. blobNotFound
JMAP Error Code: blobNotFound JMAP Error Code: blobNotFound
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 4.6 Reference: This document, Section 4.6
Description: At least one blob id referenced in the object doesn't Description: At least one blob id referenced in the object doesn't
exist. exist.
10.6.4. tooManyKeywords 10.6.4. tooManyKeywords
JMAP Error Code: tooManyKeywords JMAP Error Code: tooManyKeywords
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 4.6 Reference: This document, Section 4.6
Description: The change to the email's keywords would exceed a Description: The change to the Email's keywords would exceed a
server-defined maximum. server-defined maximum.
10.6.5. tooManyMailboxes 10.6.5. tooManyMailboxes
JMAP Error Code: tooManyMailboxes JMAP Error Code: tooManyMailboxes
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 4.6 Reference: This document, Section 4.6
Description: The change to the email's mailboxes would exceed a Description: The change to the set of Mailboxes that this Email is in
server-defined maximum. would exceed a server-defined maximum.
10.6.6. invalidEmail 10.6.6. invalidEmail
JMAP Error Code: invalidEmail JMAP Error Code: invalidEmail
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 7.5 Reference: This document, Section 7.5
Description: The email to be sent is invalid in some way. Description: The Email to be sent is invalid in some way.
10.6.7. tooManyRecipients 10.6.7. tooManyRecipients
JMAP Error Code: tooManyRecipients JMAP Error Code: tooManyRecipients
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 7.5
Description: The RFC5321 envelope (supplied or generated) has more Reference: This document, Section 7.5
Description: The envelope [RFC5321] (supplied or generated) has more
recipients than the server allows. recipients than the server allows.
10.6.8. noRecipients 10.6.8. noRecipients
JMAP Error Code: noRecipients JMAP Error Code: noRecipients
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 7.5 Reference: This document, Section 7.5
Description: The RFC5321 envelope (supplied or generated) does not Description: The envelope [RFC5321] (supplied or generated) does not
have any rcptTo emails. have any rcptTo email addresses.
10.6.9. invalidRecipients 10.6.9. invalidRecipients
JMAP Error Code: invalidRecipients JMAP Error Code: invalidRecipients
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 7.5 Reference: This document, Section 7.5
Description: The rcptTo property of the RFC5321 envelope (supplied or Description: The rcptTo property of the envelope [RFC5321] (supplied
generated) contains at least one rcptTo value which is not a valid or generated) contains at least one rcptTo value that is not a valid
email for sending to. email address for sending to.
10.6.10. forbiddenMailFrom 10.6.10. forbiddenMailFrom
JMAP Error Code: forbiddenMailFrom JMAP Error Code: forbiddenMailFrom
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 7.5 Reference: This document, Section 7.5
Description: The server does not permit the user to send an email Description: The server does not permit the user to send a message
with the RFC5321 envelope From. with this envelope From address [RFC5321].
10.6.11. forbiddenFrom 10.6.11. forbiddenFrom
JMAP Error Code: forbiddenFrom JMAP Error Code: forbiddenFrom
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, sections 6.3 and 7.5 Reference: This document, Sections 6.3 and 7.5
Description: The server does not permit the user to send an email Description: The server does not permit the user to send a message
with the RFC5322 From header field of the email to be sent. with the From header field [RFC5322] of the message to be sent.
10.6.12. forbiddenToSend 10.6.12. forbiddenToSend
JMAP Error Code: forbiddenToSend JMAP Error Code: forbiddenToSend
Intended use: common Intended use: common
Change controller: IETF Change controller: IETF
Reference: This document, section 7.5 Reference: This document, Section 7.5
Description: The user does not have permission to send at all right Description: The user does not have permission to send at all right
now. now.
11. References 11. References
11.1. Normative References 11.1. Normative References
[HTML] Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and [HTML] Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and
S. Moon, "HTML 5.2", 2017, S. Moon, "HTML 5.2", World Wide Web Consortium
Recommendation REC-html52-20171214, December 2017,
<https://www.w3.org/TR/html52/>. <https://www.w3.org/TR/html52/>.
[I-D.ietf-jmap-core]
Jenkins, N. and C. Newman, "JSON Meta Application
Protocol", draft-ietf-jmap-core-14 (work in progress),
January 2019.
[RFC1870] Klensin, J., Freed, N., and K. Moore, "SMTP Service [RFC1870] Klensin, J., Freed, N., and K. Moore, "SMTP Service
Extension for Message Size Declaration", STD 10, RFC 1870, Extension for Message Size Declaration", STD 10, RFC 1870,
DOI 10.17487/RFC1870, November 1995, DOI 10.17487/RFC1870, November 1995,
<https://www.rfc-editor.org/info/rfc1870>. <https://www.rfc-editor.org/info/rfc1870>.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
<https://www.rfc-editor.org/info/rfc2045>. <https://www.rfc-editor.org/info/rfc2045>.
skipping to change at page 93, line 19 skipping to change at page 107, line 37
[RFC8457] Leiba, B., Ed., "IMAP "$Important" Keyword and [RFC8457] Leiba, B., Ed., "IMAP "$Important" Keyword and
"\Important" Special-Use Attribute", RFC 8457, "\Important" Special-Use Attribute", RFC 8457,
DOI 10.17487/RFC8457, September 2018, DOI 10.17487/RFC8457, September 2018,
<https://www.rfc-editor.org/info/rfc8457>. <https://www.rfc-editor.org/info/rfc8457>.
[RFC8474] Gondwana, B., Ed., "IMAP Extension for Object [RFC8474] Gondwana, B., Ed., "IMAP Extension for Object
Identifiers", RFC 8474, DOI 10.17487/RFC8474, September Identifiers", RFC 8474, DOI 10.17487/RFC8474, September
2018, <https://www.rfc-editor.