JMAP
Internet Engineering Task Force (IETF)                        N. Jenkins
Internet-Draft                                                  FastMail
Request for Comments: 8621                                      Fastmail
Updates: 5788 (if approved)                                                  C. Newman
Intended status:
Category: Standards Track                                         Oracle
Expires: September 9, 2019                                 March 8,
ISSN: 2070-1721                                              August 2019

             JMAP (JSON

           The JSON Meta Application Protocol) Protocol (JMAP) for Mail
                        draft-ietf-jmap-mail-16

Abstract

   This document specifies a data model for synchronising email data
   with a server using JMAP (the the JSON Meta Application Protocol). Protocol (JMAP).
   Clients can use this to efficiently search, access, organise organise, and
   send messages, and to get pushed push notifications for fast
   resynchronisation when new messages are delivered or a change is made
   in another client.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list  It represents the consensus of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid the IETF community.  It has
   received public review and has been approved for a maximum publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of six months RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be updated, replaced, or obsoleted by other documents obtained at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 9, 2019.
   https://www.rfc-editor.org/info/rfc8621.

Copyright Notice

   Copyright (c) 2019 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.1.  Notational conventions Conventions  . . . . . . . . . . . . . . . . .   4
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   5
     1.3.  Additions to the capabilities object Capabilities Object  . . . . . . . . . .   5
       1.3.1.  urn:ietf:params:jmap:mail . . . . . . . . . . . . . .   5
       1.3.2.  urn:ietf:params:jmap:submission . . . . . . . . . . .   6   7
       1.3.3.  urn:ietf:params:jmap:vacationresponse . . . . . . . .   7   8
     1.4.  Data type support Type Support in different accounts Different Accounts . . . . . . . . .   7   8
     1.5.  Push  . . . . . . . . . . . . . . . . . . . . . . . . . .   8
       1.5.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   8   9
     1.6.  Ids . . . . . . . . . . . . . . . . . . . . . . . . . . .   8   9
   2.  Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . .   8   9
     2.1.  Mailbox/get . . . . . . . . . . . . . . . . . . . . . . .  12  13
     2.2.  Mailbox/changes . . . . . . . . . . . . . . . . . . . . .  12  14
     2.3.  Mailbox/query . . . . . . . . . . . . . . . . . . . . . .  13  14
     2.4.  Mailbox/queryChanges  . . . . . . . . . . . . . . . . . .  14  15
     2.5.  Mailbox/set . . . . . . . . . . . . . . . . . . . . . . .  14  15
     2.6.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  14  16
   3.  Threads . . . . . . . . . . . . . . . . . . . . . . . . . . .  18  20
     3.1.  Thread/get  . . . . . . . . . . . . . . . . . . . . . . .  19  21
       3.1.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  19  21
     3.2.  Thread/changes  . . . . . . . . . . . . . . . . . . . . .  19  21
   4.  Emails  . . . . . . . . . . . . . . . . . . . . . . . . . . .  20  22
     4.1.  Properties of the Email object Object  . . . . . . . . . . . . .  20  22
       4.1.1.  Metadata  . . . . . . . . . . . . . . . . . . . . . .  21  23
       4.1.2.  Header fields parsed forms Fields Parsed Forms  . . . . . . . . . . . . .  23  25
       4.1.3.  Header fields properties Fields Properties  . . . . . . . . . . . . . .  28  31
       4.1.4.  Body parts Parts  . . . . . . . . . . . . . . . . . . . . .  30  33
     4.2.  Email/get . . . . . . . . . . . . . . . . . . . . . . . .  36  40
       4.2.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  38  42
     4.3.  Email/changes . . . . . . . . . . . . . . . . . . . . . .  39  43
     4.4.  Email/query . . . . . . . . . . . . . . . . . . . . . . .  40  44
       4.4.1.  Filtering . . . . . . . . . . . . . . . . . . . . . .  40  44
       4.4.2.  Sorting . . . . . . . . . . . . . . . . . . . . . . .  42  47
       4.4.3.  Thread collapsing Collapsing . . . . . . . . . . . . . . . . . .  44  48
     4.5.  Email/queryChanges  . . . . . . . . . . . . . . . . . . .  44  49
     4.6.  Email/set . . . . . . . . . . . . . . . . . . . . . . . .  44  49
     4.7.  Email/copy  . . . . . . . . . . . . . . . . . . . . . . .  47  51
     4.8.  Email/import  . . . . . . . . . . . . . . . . . . . . . .  47  52
     4.9.  Email/parse . . . . . . . . . . . . . . . . . . . . . . .  49  54
     4.10. Examples  . . . . . . . . . . . . . . . . . . . . . . . .  51  56
   5.  Search snippets Snippets . . . . . . . . . . . . . . . . . . . . . . .  58  66
     5.1.  SearchSnippet/get . . . . . . . . . . . . . . . . . . . .  59  67
     5.2.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  60  68
   6.  Identities  . . . . . . . . . . . . . . . . . . . . . . . . .  61  69
     6.1.  Identity/get  . . . . . . . . . . . . . . . . . . . . . .  62  70
     6.2.  Identity/changes  . . . . . . . . . . . . . . . . . . . .  62  70
     6.3.  Identity/set  . . . . . . . . . . . . . . . . . . . . . .  62  71
     6.4.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  63  71
   7.  Email submission Submission  . . . . . . . . . . . . . . . . . . . . . .  63  72
     7.1.  EmailSubmission/get . . . . . . . . . . . . . . . . . . .  68  78
     7.2.  EmailSubmission/changes . . . . . . . . . . . . . . . . .  68  78
     7.3.  EmailSubmission/query . . . . . . . . . . . . . . . . . .  68  78
     7.4.  EmailSubmission/queryChanges  . . . . . . . . . . . . . .  69  79
     7.5.  EmailSubmission/set . . . . . . . . . . . . . . . . . . .  69  79
       7.5.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  71  81
   8.  Vacation response Response . . . . . . . . . . . . . . . . . . . . . .  74  84
     8.1.  VacationResponse/get  . . . . . . . . . . . . . . . . . .  75  85
     8.2.  VacationResponse/set  . . . . . . . . . . . . . . . . . .  75  85
   9.  Security considerations Considerations . . . . . . . . . . . . . . . . . . .  75  85
     9.1.  EmailBodyPart value Value . . . . . . . . . . . . . . . . . . .  75  85
     9.2.  HTML email display Email Display  . . . . . . . . . . . . . . . . . . .  76  86
     9.3.  Multiple part display Part Display . . . . . . . . . . . . . . . . . .  78  88
     9.4.  Email submission Submission  . . . . . . . . . . . . . . . . . . . .  78  88
     9.5.  Partial account access Account Access  . . . . . . . . . . . . . . . . .  79  89
     9.6.  Permission to send Send from an address Address  . . . . . . . . . . .  79  89
   10. IANA considerations Considerations . . . . . . . . . . . . . . . . . . . . .  80  90
     10.1.  JMAP capability registration Capability Registration for "mail"  . . . . . . . .  80  90
     10.2.  JMAP capability registration for Capability Registration for "submission"  . . . . .  80  90
     10.3.  JMAP capability registration Capability Registration for "vacationresponse"  . .  81  91
     10.4.  IMAP and JMAP keywords registry Keywords Registry  . . . . . . . . . . . .  81  91
       10.4.1.  Registration of JMAP keyword '$draft' Keyword "$draft"  . . . . . . .  81  92
       10.4.2.  Registration of JMAP keyword '$seen' Keyword "$seen" . . . . . . . .  82  93
       10.4.3.  Registration of JMAP keyword '$flagged' Keyword "$flagged"  . . . . . .  83  94
       10.4.4.  Registration of JMAP keyword '$answered' Keyword "$answered" . . . . . .  84  94
       10.4.5.  Registration of '$recent' keyword "$recent" Keyword  . . . . . . . . .  85  95
     10.5.  IMAP Mailbox Name Attributes Registry  . . . . . . . . .  96
       10.5.1.  Registration of "inbox" role in Role . . . . . . . . . . . .  85  96
     10.6.  JMAP Error Codes registry Registry  . . . . . . . . . . . . . . .  86  96
       10.6.1.  mailboxHasChild  . . . . . . . . . . . . . . . . . .  86  96
       10.6.2.  mailboxHasEmail  . . . . . . . . . . . . . . . . . .  86  96
       10.6.3.  blobNotFound . . . . . . . . . . . . . . . . . . . .  86  97
       10.6.4.  tooManyKeywords  . . . . . . . . . . . . . . . . . .  87  97
       10.6.5.  tooManyMailboxes . . . . . . . . . . . . . . . . . .  87  97
       10.6.6.  invalidEmail . . . . . . . . . . . . . . . . . . . .  87  98
       10.6.7.  tooManyRecipients  . . . . . . . . . . . . . . . . .  87  98
       10.6.8.  noRecipients . . . . . . . . . . . . . . . . . . . .  88  98
       10.6.9.  invalidRecipients  . . . . . . . . . . . . . . . . .  88  98
       10.6.10. forbiddenMailFrom  . . . . . . . . . . . . . . . . .  88  99
       10.6.11. forbiddenFrom  . . . . . . . . . . . . . . . . . . .  89  99
       10.6.12. forbiddenToSend  . . . . . . . . . . . . . . . . . .  89  99
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  89  99
     11.1.  Normative References . . . . . . . . . . . . . . . . . .  89 100
     11.2.  Informative References . . . . . . . . . . . . . . . . .  93
     11.3.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  93 103
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  94 104

1.  Introduction

   JMAP ([I-D.ietf-jmap-core] -

   The JSON Meta Application Protocol) Protocol (JMAP) [RFC8620] is a generic
   protocol for synchronising data, such as mail, calendars calendars, or
   contacts, contacts
   between a client and a server.  It is optimised for mobile and web environments,
   environments and aims to provide a consistent interface to different
   data types.

   This specification defines a data model for accessing a mail store
   over JMAP, allowing you to query, read, organise organise, and submit mail for
   sending.

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

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

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

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

1.1.  Notational conventions Conventions

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

   Type signatures, examples examples, and property descriptions in this document
   follow the conventions established in section Section 1.1 of
   [I-D.ietf-jmap-core]. [RFC8620].  Data
   types defined in the core specification are also used in this
   document.

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

1.2.  Terminology

   The

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

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

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

1.3.  Additions to the capabilities object Capabilities Object

   The capabilities object is returned as part of the JMAP Session
   object; see [I-D.ietf-jmap-core], section [RFC8620], Section 2.

   This document defines three additional capability URIs.

1.3.1.  urn:ietf:params:jmap:mail

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

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

   o  *maxMailboxesPerEmail*:  maxMailboxesPerEmail: "UnsignedInt|null"

      The maximum number of
      mailboxes Mailboxes (see Section 2) that can be can
      assigned to a single Email object (see
      section Section 4).  This MUST be
      an integer >= 1, or "null" null for no limit (or rather, the limit is
      always the number of mailboxes Mailboxes in the account).

   o  *maxMailboxDepth*:  maxMailboxDepth: "UnsignedInt|null"
      The maximum depth of the
      mailbox Mailbox hierarchy (i.e. (i.e., one more than
      the maximum number of ancestors a mailbox Mailbox may have), or "null" null for
      no limit.

   o  *maxSizeMailboxName*:  maxSizeMailboxName: "UnsignedInt"

      The maximum length, in (UTF-8) octets, allowed for the name of a mailbox.
      Mailbox.  This MUST be at least 100, although it is recommended
      servers allow more.

   o  *maxSizeAttachmentsPerEmail*:  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 emails 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 server-
      defined limit).  Note,

      Note that this limit is for the sum of unencoded attachment sizes.
      Users are generally not knowledgeable about encoding overhead 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
      message [RFC5322], created by combining the attachments Base64 encoded
      and (often
      base64 encoded) with the message headers and bodies too. bodies.  For example,
      suppose the server advertises "maxSizeAttachmentsPerEmail:
      50000000" (50 MB).  The enforced server limit may be for an RFC5322 a message
      size of 70000000
      octets (70 MB). octets.  Even with Base64 base64 encoding and a 2 MB
      HTML body, 50 MB attachments would fit under this limit.

   o  *emailQuerySortOptions*:  emailQuerySortOptions: "String[]"

      A list of all the values the server supports for the "property"
      field of the Comparator object in an Email/query "Email/query" sort (see section 5.5).
      Section 4.4.2).  This MAY include properties the client does not
      recognise (for example example, custom properties specified in a vendor
      extension).  Clients MUST ignore any unknown properties in the
      list.

   o  *mayCreateTopLevelMailbox*:  mayCreateTopLevelMailbox: "Boolean"

      If "true", true, the user may create a mailbox Mailbox (see section Section 2) in this
      account with a "null" null parentId.  (Permission for creating a child of
      an existing mailbox Mailbox is given by the myRights "myRights" property on that mailbox.)
      Mailbox.)

1.3.2.  urn:ietf:params:jmap:submission

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

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

   o  *maxDelayedSend*:  maxDelayedSend: "UnsignedInt"

      The number in seconds of the maximum delay the server supports in
      sending (see the EmailSubmission object description).  This is "0" 0
      if the server does not support delayed send.

   o  *submissionExtensions*:  submissionExtensions: "String[String[]]"

      The set of SMTP submission extensions supported by the server,
      which the client may use when creating an EmailSubmission object
      (see section Section 7).  Each key in the object is the _ehlo-name_, "ehlo-name", and
      the value is a list of _ehlo-args_. "ehlo-args".

      A JMAP implementation that talks to a Submission
      [RFC6409] 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 are have to do with the
      transport mechanism and thus are only relevant to the JMAP server
      (for example example, PIPELINING, CHUNKING, or STARTTLS).

      Examples of Submission extensions to include:

      *  FUTURERELEASE ([RFC4865]) [RFC4865]

      *  SIZE ([RFC1870]) [RFC1870]

      *  DSN ([RFC3461]) [RFC3461]

      *  DELIVERYBY ([RFC2852]) [RFC2852]

      *  MT-PRIORITY ([RFC6710]) [RFC6710]
      A JMAP server MAY advertise an extension and implement the
      semantics of that extension locally on the JMAP server even if a
      submission server used by JMAP doesn't implement it.

      The full IANA registry of submission extensions can be found at
      <https://www.iana.org/assignments/mail-parameters/mail-
      parameters.xhtml#mail-parameters-2>.
      <https://www.iana.org/assignments/mail-parameters>.

1.3.3.  urn:ietf:params:jmap:vacationresponse

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

1.4.  Data type support Type Support in different accounts Different Accounts

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

1.5.  Push

   Servers MUST support the JMAP push mechanisms, as specified in
   [I-D.ietf-jmap-core] section
   [RFC8620], Section 7, to receive notifications when the state changes
   for any of the types defined in this specification.

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

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

1.5.1.  Example

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

1.6.  Ids

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

2.  Mailboxes

   A mailbox Mailbox represents a named set of emails. Email objects.  This is the
   primary mechanism for organising emails messages within an account.  It is
   analogous to a folder or a label in other systems.  A mailbox Mailbox may
   perform a certain role in the system; see below for more details.

   For compatibility with IMAP, an email Email MUST belong to one or more
   mailboxes.
   Mailboxes.  The email Email id does not change if the email Email changes
   mailboxes.
   Mailboxes.

   A *Mailbox* object has the following properties:

   o  *id*:  id: "Id" (immutable; server-set)

      The id of the mailbox. Mailbox.

   o  *name*:  name: "String"

      User-visible name for the mailbox, e.g. Mailbox, e.g., "Inbox".  This MUST be a
      Net-Unicode string ([RFC5198]) [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 Mailboxes with both the same parent and
      the same name.  Servers MAY reject names that violate server
      policy (e.g., names containing a slash (/) or control characters).

   o  *parentId*:  parentId: "Id|null" (default: null)
      The mailbox Mailbox id for the parent of this mailbox, Mailbox, or "null" null if 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  *role*:  role: "String|null" (default: null)

      Identifies mailboxes Mailboxes that have a particular common purpose (e.g. (e.g.,
      the "inbox"), regardless of the _name_ "name" property (which may be
      localised).

      This value is shared with IMAP (exposed in IMAP via the [RFC6154] SPECIAL-USE extension). SPECIAL-
      USE extension [RFC6154]).  However, unlike in IMAP, a mailbox Mailbox MUST
      only have a single role, and there MUST NOT be two mailboxes Mailboxes in
      the same account with the same role.  Servers providing IMAP
      access to the same data are encouraged to enforce these extra
      restrictions in IMAP as well.  Otherwise, it is implementation dependent how to modify modifying the IMAP
      attributes to ensure compliance when exposing the data over JMAP. JMAP
      is implementation dependent.

      The value MUST be one of the mailbox Mailbox attribute names listed in the
      IANA IMAP "IMAP Mailbox Name Attributes Registry [1], Attributes" registry at
      <https://www.iana.org/assignments/imap-mailbox-name-attributes/>,
      as established in [RFC8457], converted to lower-case. lowercase.  New roles
      may be established here in the future.

      An account is not required to have mailboxes Mailboxes with any particular
      roles.

   o  *sortOrder*:  sortOrder: "UnsignedInt" (default: 0)

      Defines the sort order of
      mailboxes 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 Mailbox with a lower order should be displayed before a mailbox Mailbox
      with a higher order (that has the same parent) in any mailbox 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*:  totalEmails: "UnsignedInt" (server-set)

      The number of emails Emails in this mailbox. Mailbox.

   o  *unreadEmails*:  unreadEmails: "UnsignedInt" (server-set)
      The number of emails Emails in this mailbox Mailbox that have neither the "$seen"
      keyword nor the "$draft" keyword.

   o  *totalThreads*:  totalThreads: "UnsignedInt" (server-set)

      The number of threads Threads where at least one email Email in the thread Thread is in
      this mailbox. Mailbox.

   o  *unreadThreads*:  unreadThreads: "UnsignedInt" (server-set)

      An indication of the number of "unread" threads Threads in the mailbox. Mailbox.

      For compatibility with existing implementations, the way "unread threads"
      Threads" is determined is not mandated in this document.  The
      simplest solution to implement is simply the number of threads Threads
      where at least one email Email in the thread Thread is both in this mailbox 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. Mailbox.  A thread Thread is
      shown as unread if it contains any unread messages Emails that will be
      displayed when the thread Thread is opened.  Therefore  Therefore, "unreadThreads"
      should be the number of threads Threads where at least one email Email in the thread
      Thread has neither the "$seen" nor the "$draft" keyword AND at
      least one email Email in the thread Thread is in this mailbox.  Note, Mailbox.  Note that the
      unread email Email does not need to be the one in this mailbox. Mailbox.  In
      addition, the Trash mailbox trash Mailbox (that is is, a
      mailbox Mailbox whose "role" is
      "trash") is treated specially: requires special treatment:

      1.  Emails that are *only* in the Trash trash (and no other mailbox) Mailbox) are
          ignored when calculating the "unreadThreads" count of other
          mailboxes.
          Mailboxes.

      2.  Emails that are *not* in the Trash trash are ignored when
          calculating the "unreadThreads" count for the Trash mailbox. trash Mailbox.

      The result of this is that emails Emails in the Trash trash are treated as
      though they are in a separate thread Thread for the purposes of unread
      counts.  It is expected that clients will hide emails Emails in the Trash trash
      when viewing a thread Thread in another mailbox Mailbox, and vice versa.  This
      allows you to delete a single email Email to the Trash trash out of a thread.
      So for Thread.

      For example, suppose you have an account where the entire contents
      is a single thread Thread with 2 emails: Emails: an unread email Email in the
      Trash trash and
      a read email Email in the Inbox. inbox.  The "unreadThreads" count would be "1" 1
      for the Trash trash and "0" 0 for the Inbox. inbox.

   o  *myRights*:  myRights: "MailboxRights" (server-set)
      The set of rights (ACLs) (Access Control Lists (ACLs)) the user has in
      relation to this mailbox. Mailbox.  These are backwards compatible with
      IMAP ACLs, as defined in [RFC4314].  A
      _MailboxRights_ *MailboxRights* object has
      the following properties:

      *  *mayReadItems*:  mayReadItems: "Boolean"

         If true, the user may use this
         mailbox Mailbox as part of a filter in a _Email/query_ call
         an "Email/query" call, and the
         mailbox Mailbox may be included in the _mailboxIds_ set
         "mailboxIds" property of _Email_ Email objects.  Email objects may be
         fetched if they are in *at least one* mailbox Mailbox with this
         permission.  If a sub-mailbox sub-Mailbox is shared but not the parent mailbox,
         Mailbox, this may be "false". false.  Corresponds to IMAP ACLs "lr" (if
         mapping from IMAP, both are required for this to be "true"). true).

      *  *mayAddItems*:  mayAddItems: "Boolean"

         The user may add mail to this mailbox Mailbox (by either creating a new email
         Email or moving an existing one).  Corresponds to IMAP ACL "i".

      *  *mayRemoveItems*:  mayRemoveItems: "Boolean"

         The user may remove mail from this
         mailbox Mailbox (by either changing
         the mailboxes Mailboxes of an email Email or
         deleting it). destroying the Email).
         Corresponds to IMAP ACLs "te" (if mapping from IMAP, both are
         required for this to be "true"). true).

      *  *maySetSeen*:  maySetSeen: "Boolean"

         The user may add or remove the "$seen" keyword to/from an email.
         Email.  If an email Email belongs to multiple
         mailboxes, Mailboxes, the user may
         only modify "$seen" if they have this permission for *all* of
         the mailboxes. Mailboxes.  Corresponds to IMAP ACL "s".

      *  *maySetKeywords*:  maySetKeywords: "Boolean"

         The user may add or remove any keyword _other than_ other than "$seen" to/from to/
         from an email. Email.  If an email Email belongs to multiple mailboxes, Mailboxes, the
         user may only modify keywords if they have this permission for
         *all* of the
         mailboxes. Mailboxes.  Corresponds to IMAP ACL "w".

      *  *mayCreateChild*:  mayCreateChild: "Boolean"

         The user may create a mailbox Mailbox with this mailbox Mailbox as its parent.
         Corresponds to IMAP ACL "k".

      *  *mayRename*:  mayRename: "Boolean"
         The user may rename the mailbox Mailbox or make it a child of another mailbox.
         Mailbox.  Corresponds to IMAP ACL "x" (although this covers
         both rename and delete permissions).

      *  *mayDelete*:  mayDelete: "Boolean"

         The user may delete the mailbox Mailbox itself.  Corresponds to IMAP
         ACL "x" (although this covers both rename and delete
         permissions).

      *  *maySubmit*:  maySubmit: "Boolean"

         Messages may be submitted directly to this mailbox. Mailbox.
         Corresponds to IMAP ACL "p".

   o  *isSubscribed*:  isSubscribed: "Boolean"

      Has the user indicated they wish to see this mailbox Mailbox in their
      client?  This SHOULD default to "false" false for
      mailboxes Mailboxes in shared
      accounts the user has access to, to and "true" true for any new mailboxes Mailboxes
      created by the user themself.  This MUST be stored separately per-user per
      user where multiple users have access to a shared mailbox. 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, Mailboxes,
      but only be interested in the contents of a few of these.  Clients
      may choose only to only display mailboxes to the
      user that have Mailboxes where the "isSubscribed"
      property is set to "true", true, and offer a separate UI to allow the user
      to see and subscribe/
      unsubscribe subscribe/unsubscribe from the full set of mailboxes. Mailboxes.
      However, clients MAY choose to ignore this property, either
      entirely for ease of
      implementation, implementation or just for an account where
      "isPersonal" is
      "true" true (indicating it is the user's own, own rather than
      a shared account).

      This property corresponds to IMAP ([RFC3501]) [RFC3501] mailbox subscriptions.

   For IMAP compatibility, an email Email in both the Trash trash and another
   mailbox
   Mailbox SHOULD be treated by the client as existing in both places
   (i.e.
   (i.e., when emptying the trash, the client should just remove it from
   the
   Trash mailbox trash Mailbox and leave it in the other mailbox). Mailbox).

   The following JMAP methods are supported: supported.

2.1.  Mailbox/get

   Standard

   This is a standard "/get" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.1.  The _ids_ "ids" argument may be "null" to fetch all at once.

2.2.  Mailbox/changes

   Standard

   This is a standard "/changes" method as described in [I-D.ietf-jmap-core]
   section 5.2, [RFC8620],
   Section 5.2 but with one extra argument to the response:

   o  *updatedProperties*:  updatedProperties: "String[]|null"

      If only the mailbox counts
      (unread/total emails/threads) "totalEmails", "unreadEmails", "totalThreads", and/or
      "unreadThreads" Mailbox properties have changed since the old
      state, this will be the list of properties that may have changed, i.e.
      "["totalEmails", "unreadEmails", "totalThreads",
      "unreadThreads"]". changed.
      If the server is unable to tell if only counts have changed, it
      MUST just be "null". null.

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

2.3.  Mailbox/query

   Standard

   This is a standard "/query" method as described in [I-D.ietf-jmap-core] section
   5.5, [RFC8620],
   Section 5.5 but with the following additional request argument:

   o  *sortAsTree*:  sortAsTree: "Boolean" (default: false)

      If "true", true, when sorting the query results and comparing two mailboxes a Mailboxes A
      and b: B:

      *  If a A is an ancestor of b, B, it always comes first regardless of
         the _sort_ sort comparators.  Similarly, if a A is descendant of b, B, then b
         B always comes first.

      *  Otherwise, if a A and b B do not share a _parentId_, "parentId", find the
         nearest ancestors of each that do have the same _parentId_ "parentId" and
         compare the sort properties on those mailboxes Mailboxes instead.

      The result of this is that the mailboxes Mailboxes are sorted as a tree
      according to the parentId properties, with each set of children
      with a common parent sorted according to the standard sort
      comparators.

   o  *filterAsTree*:  filterAsTree: "Boolean" (default: false)

      If "true", true, a mailbox Mailbox is only included in the query if all its
      ancestors are also included in the query according to the filter.

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

   o  *parentId*:  parentId: "Id|null"

      The Mailbox _parentId_ "parentId" property must match the given value
      exactly.

   o  *name*:  name: "String"

      The Mailbox _name_ "name" property contains the given string.

   o  *role*:  role: "String|null"

      The Mailbox _role_ "role" property must match the given value exactly.

   o  *hasAnyRole*:  hasAnyRole: "Boolean"

      If "true", true, a Mailbox matches if it has any
      non-"null" non-null value for its _role_
      "role" property.

   o  *isSubscribed*:  isSubscribed: "Boolean"

      The "isSubscribed" property of the
      mailbox Mailbox must be identical to
      the value given to match the condition.

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

   The following Mailbox properties MUST be supported for sorting:

   o  "sortOrder"

   o  "name"

2.4.  Mailbox/queryChanges

   Standard

   This is a standard "/queryChanges" method as described in [I-D.ietf-jmap-core]
   section [RFC8620],
   Section 5.6.

2.5.  Mailbox/set

   Standard

   This is a standard "/set" method as described in [I-D.ietf-jmap-core] section
   5.3, [RFC8620],
   Section 5.3 but with the following additional request argument:

   o  *onDestroyRemoveMessages*:  onDestroyRemoveEmails: "Boolean" (default: false)
      If "false", false, any attempt to destroy a mailbox Mailbox that still has messages Emails
      in it will be rejected with a "mailboxHasEmail" SetError.  If "true",
      true, any messages Emails that were in the mailbox Mailbox will be removed from it,
      and if in no other mailboxes Mailboxes, they will be destroyed when the mailbox
      Mailbox is destroyed.

   The following extra _SetError_ SetError types are defined:

   For *destroy*: "destroy":

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

   o  "mailboxHasEmail": The mailbox Mailbox has at least one message Email assigned to it
      it, and the _onDestroyRemoveMessages_ "onDestroyRemoveEmails" argument was "false". false.

2.6.  Example

   Fetching all mailboxes Mailboxes in an account:

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

   And the response:

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

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

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

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

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

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

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

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

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

3.  Threads

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

   The exact algorithm for determining whether two emails Emails belong to the
   same thread Thread is not mandated in this spec to allow for compatibility
   with different existing systems.  For new implementations, it is
   suggested that two messages belong in the same thread Thread if both of the
   following conditions apply:

   1.  An identical RFC5322 message id [RFC5322] appears in both messages in any
       of the Message-Id, In-Reply-To In-Reply-To, and References headers. header fields.

   2.  After stripping automatically added prefixes such as "Fwd:",
       "Re:", "[List-Tag]" etc. "[List-Tag]", etc., and ignoring whitespace, white space, the subjects
       are the same.  This avoids the situation where a person replies
       to an old message as a convenient way of finding the right
       recipient to send to, to but changes the subject and starts a new
       conversation.

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

   A *Thread* object has the following properties:

   o  *id*:  id: "Id" (immutable; server-set)
      The id of the thread. Thread.

   o  *emailIds*:  emailIds: "Id[]" (server-set)

      The ids of the emails Emails in the
      thread, Thread, sorted by the _receivedAt_ "receivedAt"
      date of the email, Email, oldest first.  If two emails Emails have an identical
      date, the sort is server- server dependent but MUST be stable (sorting by
      id is recommended).

   The following JMAP methods are supported: supported.

3.1.  Thread/get

   Standard

   This is a standard "/get" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.1.

3.1.1.  Example

   Request:

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

   with response:

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

3.2.  Thread/changes

   Standard

   This is a standard "/changes" method as described in [I-D.ietf-jmap-core]
   section [RFC8620],
   Section 5.2.

4.  Emails

   The

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

4.1.  Properties of the Email object Object

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

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

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

   o  _textBody_/_htmlBody_:  "textBody"/"htmlBody": These provide a list of parts that should
      be rendered sequentially as the "body" of the message.  This is a
      list rather than a single part as messages may have headers and/or
      footers appended/prepended as separate parts as when they are
      transmitted, and some clients send text and images intended to be
      displayed inline in the body (or even videos and sound clips) as
      multiple parts rather than a single HTML part with referenced
      images.

      Because MIME allows for multiple representations of the same data
      (using "multipart/alternative"), there is a textBody "textBody" property
      (which prefers a plain text plaintext representation) and an htmlBody "htmlBody"
      property (which prefers an HTML representation) to accommodate the
      two most common client requirements.  The same part may appear in
      both lists where there is no alternative between the two.

   o  _attachments_:  "attachments": This provides a list of parts that should be
      presented as "attachments" to the message.  Some images may be
      solely there for embedding within an HTML body part; clients may
      wish to not present these as attachments in the user interface if
      they are displaying the HTML with the embedded images directly.
      Some parts may also be in htmlBody/textBody; again, clients may
      wish to not present these as attachments in the user interface if
      rendered as part of the body.

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

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

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

4.1.1.  Metadata

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

   o  *id*:  id: "Id" (immutable; server-set)

      The id of the Email object.
      Note,  Note that this is the JMAP object id,
      NOT the [RFC5322] Message-ID header field value. value of the message [RFC5322].

   o  *blobId*:  blobId: "Id" (immutable; server-set)

      The id representing the raw octets of the message [RFC5322] message. for
      this Email.  This may be used to download the raw original message, message
      or to attach it directly to another Email Email, etc.

   o  *threadId*:  threadId: "Id" (immutable; server-set)

      The id of the Thread to which this Email belongs.

   o  *mailboxIds*:  mailboxIds: "Id[Boolean]"

      The set of Mailbox ids this email Email belongs to.  An email Email in the
      mail store MUST belong to one or more
      mailboxes Mailboxes at all times
      (until it is deleted). destroyed).  The set is represented as an object,
      with each key being a _Mailbox id_. Mailbox id.  The value for each key in the
      object MUST be "true". true.

   o  *keywords*:  keywords: "String[Boolean]" (default: {})

      A set of keywords that apply to the email. Email.  The set is represented
      as an object, with the keys being the _keywords_. keywords.  The value for
      each key in the object MUST be "true". true.

      Keywords are shared with IMAP.  The six system keywords from IMAP are treated specially.
      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 Email is a draft the user is composing.

      *  "$seen": The email Email has been read.

      *  "$flagged": The email Email has been flagged for urgent/special
         attention.

      *  "$answered": The email Email has been replied to.

      The IMAP "\Recent" keyword is not exposed via JMAP.  The IMAP
      "\Deleted" keyword is also not present: IMAP uses a delete+expunge
      model, which JMAP does not.  Any message with the "\Deleted"
      keyword MUST NOT be visible via JMAP (including as part of any
      mailbox counts). (and so are not counted in
      the "totalEmails", "unreadEmails", "totalThreads", and
      "unreadThreads" Mailbox properties).

      Users may add arbitrary keywords to an email. Email.  For compatibility
      with IMAP, a keyword is a case-insensitive string of 1-255
      characters in the ASCII subset %x21-%x7e (excludes control chars
      and space), and it MUST NOT include any of these characters: "(

                              ( ) { ] % * " \" \

      Because JSON is case-sensitive, case sensitive, servers MUST return keywords in lower-case.
      lowercase.

      The IANA Keyword
      Registry [2] "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 Email has been forwarded.

      *  "$phishing": The email Email is highly likely to be phishing.
         Clients SHOULD warn users to take care when viewing this email Email
         and disable links and attachments.

      *  "$junk": The email Email is definitely spam.  Clients SHOULD set this
         flag when users report spam to help train automated spam-
         detection systems.

      *  "$notjunk": The email Email is definitely not spam.  Clients SHOULD
         set this flag when users indicate an email Email is legitimate, to
         help train automated spam-detection systems.

   o  *size*:  size: "UnsignedInt" (immutable; server-set)

      The size, in octets, of the raw data for the [RFC5322] message [RFC5322] (as
      referenced by the
      _blobId_, i.e. "blobId", i.e., the number of octets in the file
      the user would download).

   o  *receivedAt*:  receivedAt: "UTCDate" (immutable; default: time of creation on
      server)

      The date the email Email was received by the message store.  This is the _internal date_
      "internal date" in IMAP ([RFC3501]). [RFC3501].

4.1.2.  Header fields parsed forms Fields Parsed Forms

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

4.1.2.1.  Raw

   Type: "String"

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

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

4.1.2.2.  Text

   Type: "String"

   The header field value with:

   1.  White space unfolded (as defined in [RFC5322] section [RFC5322], Section 2.2.3).

   2.  The terminating CRLF at the end of the value removed.

   3.  Any SP characters at the beginning of the value removed.

   4.  Any syntactically correct [RFC2047] encoded sections [RFC2047] with a known
       character set decoded.  Any [RFC2047] encoded NUL octets or control characters
       encoded per [RFC2047] are dropped from the decoded value.  Any
       text that looks like [RFC2047] syntax per [RFC2047] but violates [RFC2047] placement
       or whitespace white space rules per [RFC2047] MUST NOT be decoded.

   5.  The resulting unicode converted to NFC Normalization Form C (NFC)
       form.

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

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

   o  Subject

   o  Comments

   o  Keywords

   o  List-Id

   o  Any header field not defined in [RFC5322] or [RFC2369]

4.1.2.3.  Addresses

   Type: "EmailAddress[]"

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

   The

   An *EmailAddress* object has the following properties:

   o  *name*:  name: "String|null"

      The _display-name_ "display-name" of the [RFC5322]
      _mailbox_. "mailbox" [RFC5322].  If this is a _quoted-string_:
      "quoted-string":

      1.  The surrounding DQUOTE characters are removed.

      2.  Any _quoted-pair_ "quoted-pair" is decoded.

      3.  White-space  White space is unfolded, and then any leading and trailing
          white-space
          white space is removed.

      If there is no _display-name_ "display-name" but there is a _comment_ "comment" immediately
      following the _addr-spec_, "addr-spec", the value of this SHOULD be used
      instead.  Otherwise, this property is "null". null.

   o  *email*:  email: "String"

      The _addr-spec_ "addr-spec" of the [RFC5322] _mailbox_. "mailbox" [RFC5322].

   Any syntactically correct [RFC2047] encoded sections [RFC2047] with a known
   encoding MUST be decoded, following the same rules as for the _Text_
   form. Text
   form (see Section 4.1.2.2).

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

   For example, the following "address-list" string:

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

   would be parsed as:

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

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

   o  From
   o  Sender

   o  Reply-To

   o  To

   o  Cc

   o  Bcc

   o  Resent-From

   o  Resent-Sender

   o  Resent-Reply-To

   o  Resent-To

   o  Resent-Cc

   o  Resent-Bcc

   o  Any header field not defined in [RFC5322] or [RFC2369]

4.1.2.4.  GroupedAddresses

   Type: "EmailAddressGroup[]"

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

   The

   An *EmailAddressGroup* object has the following properties:

   o  *name*:  name: "String|null"

      The _display-name_ "display-name" of the [RFC5322] _group_, "group" [RFC5322], or "null" null if the
      addresses are not part of a group.  If this is a
      _quoted-string_ "quoted-string",
      it is processed the same as the _name_ "name" in the
      _EmailAddress_ EmailAddress type.

   o  *addresses*:  addresses: "EmailAddress[]"

      The _mailbox_es "mailbox" values that belong to this group, represented as
      EmailAddress objects.

   Any syntactically correct [RFC2047] encoded sections [RFC2047] with a known
   encoding MUST be decoded, following the same rules as for the _Text_
   form. Text
   form (see Section 4.1.2.2).

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

   For example, the following "address-list" string:

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

   would be parsed as:

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

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

4.1.2.5.  MessageIds

   Type: "String[]|null"

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

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

   o  Message-ID

   o  In-Reply-To

   o  References
   o  Resent-Message-ID

   o  Any header field not defined in [RFC5322] or [RFC2369]

4.1.2.6.  Date

   Type: "Date|null"

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

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

   o  Date

   o  Resent-Date

   o  Any header field not defined in [RFC5322] or [RFC2369]

4.1.2.7.  URLs

   Type: "String[]|null"

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

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

   o  List-Help

   o  List-Unsubscribe

   o  List-Subscribe

   o  List-Post

   o  List-Owner

   o  List-Archive

   o  Any header field not defined in [RFC5322] or [RFC2369]

4.1.3.  Header fields properties Fields Properties

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

   o  *headers*:  headers: "EmailHeader[]" (immutable)

      This is a list of all
      [RFC5322] header fields, fields [RFC5322], in the same order
      they appear in the message.  An *EmailHeader* object has the
      following properties:

      *  *name*:  name: "String"

         The header _field name_ "field name" as defined in [RFC5322], with the same
         capitalization that it has in the message.

      *  *value*:  value: "String"

         The header _field value_ "field value" as defined in [RFC5322], in _Raw_ Raw form.

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

                        header:{header-field-name}

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

   o  *:as{header-form}*  :as{header-form}

      This means the value is in a parsed form, where "{header-form}" is
      one of the parsed-form names specified above.  If not given, the
      value is in _Raw_ Raw form.

   o  *:all*  :all

      This means the value is an array, with the items corresponding to
      each instance of the header field, in the order they appear in the
      message.  If this suffix is not used, the result is the value of
      the *last* instance of the header field
      (i.e. (i.e., identical to the *last*
      last item in the array if :all is used), or "null" null if none.

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

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

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

   1.  Find _all_ *all* header fields named Resent-To (matched case- case
       insensitively).

   2.  For each instance instance, parse the header field value in the _Addresses_ Addresses
       form.

   3.  The result is of type "EmailAddress[][]" - -- each item in the
       array corresponds to the parsed value (which is itself an array)
       of the Resent-To header field instance.

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

   o  *messageId*:  messageId: "String[]|null" (immutable)

      The value is identical to the value of _header:Message-ID:asMessageIds_. "header:Message-
      ID:asMessageIds".  For messages conforming to RFC5322 RFC 5322, this will
      be an array with a single entry.

   o  *inReplyTo*:  inReplyTo: "String[]|null" (immutable)

      The value is identical to the value of _header:In-Reply-To:asMessageIds_. "header:In-Reply-
      To:asMessageIds".

   o  *references*:  references: "String[]|null" (immutable)

      The value is identical to the value of _header:References:asMessageIds_.
      "header:References:asMessageIds".

   o  *sender*:  sender: "EmailAddress[]|null" (immutable)

      The value is identical to the value of _header:Sender:asAddresses_.
      "header:Sender:asAddresses".

   o  *from*:  from: "EmailAddress[]|null" (immutable)

      The value is identical to the value of _header:From:asAddresses_. "header:From:asAddresses".

   o  *to*:  to: "EmailAddress[]|null" (immutable)

      The value is identical to the value of _header:To:asAddresses_. "header:To:asAddresses".

   o  *cc*:  cc: "EmailAddress[]|null" (immutable)

      The value is identical to the value of _header:Cc:asAddresses_. "header:Cc:asAddresses".

   o  *bcc*:  bcc: "EmailAddress[]|null" (immutable)

      The value is identical to the value of _header:Bcc:asAddresses_. "header:Bcc:asAddresses".

   o  *replyTo*:  replyTo: "EmailAddress[]|null" (immutable)

      The value is identical to the value of _header:Reply-To:asAddresses_. "header:Reply-
      To:asAddresses".

   o  *subject*:  subject: "String|null" (immutable)

      The value is identical to the value of _header:Subject:asText_. "header:Subject:asText".

   o  *sentAt*:  sentAt: "Date|null" (immutable; default on creation: current
      server time)

      The value is identical to the value of
      _header:Date:asDate_. "header:Date:asDate".

4.1.4.  Body parts Parts

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

   A entities [RFC2045].

   An *EmailBodyPart* object has the following properties:

   o  *partId*:  partId: "String|null"

      Identifies this part uniquely within the Email.  This is scoped to
      the _emailId_ "emailId" and has no meaning outside of the JMAP Email object
      representation.  This is "null" null if, and only if, the part is of type
      "multipart/*".

   o  *blobId*:  blobId: "Id|null"

      The id representing the raw octets of the contents of the part,
      after decoding any known _Content-Transfer-
      Encoding_ Content-Transfer-Encoding (as defined in
      [RFC2045]), or "null" null if, and only if, the part is of type
      "multipart/*".  Note,  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. transfer encoding.

   o  *size*:  size: "UnsignedInt"

      The size, in octets, of the raw data after content transfer
      decoding (as referenced by the _blobId_, i.e. "blobId", i.e., the number of
      octets in the file the user would download).

   o  *headers*:  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_ Raw form.

   o  *name*:  name: "String|null"

      This is the [RFC2231] decoded _filename_ "filename" parameter of the _Content-Disposition_ Content-
      Disposition header field, field per [RFC2231], or (for compatibility with
      existing systems) if not present present, then it's the
      [RFC2047] decoded _name_ "name"
      parameter of the _Content-Type_ Content-Type header
      field. field per [RFC2047].

   o  *type*:  type: "String"

      The value of the _Content-Type_ Content-Type header field of the part, if present, otherwise
      present; otherwise, the implicit type as per the MIME standard ("text/plain",
      ("text/plain" or "message/rfc822" if inside a "multipart/digest").
      CFWS is removed and any parameters are stripped.

   o  *charset*:  charset: "String|null"

      The value of the charset parameter of the
      _Content-Type_ Content-Type header
      field, if present, or "null" null if the header field is present but not
      of type "text/*".  If there is no
      _Content-Type_ 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*:  disposition: "String|null"

      The value of the _Content-
      Disposition_ Content-Disposition header field of the part, if present, otherwise
      "null".
      present; otherwise, it's null.  CFWS is removed and any parameters
      are stripped.

   o  *cid*:  cid: "String|null"

      The value of the _Content-Id_ Content-Id header field of the part, if present, otherwise "null". present;
      otherwise, it's null.  CFWS and surrounding angle brackets ("<>")
      are removed.  This may be used to reference the content from
      within an [HTML] a "text/html" body part [HTML] using the "cid:" protocol,
      as defined in [RFC2392].

   o  *language*:  language: "String[]|null"

      The list of language tags, as defined in [RFC3282], in the _Content-Language_
      Content-Language header field of the part, if present.

   o  *location*:  location: "String|null"

      The URI, as defined in [RFC2557], in the
      _Content-Location_ Content-Location header
      field of the part, if present.

   o  *subParts*:  subParts: "EmailBodyPart[]|null"

      If the type is "multipart/*", this contains the body parts of each
      child.

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

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

   o  *bodyStructure*:  bodyStructure: "EmailBodyPart" (immutable)

      This is the full MIME structure of the message body, represented as an array of the
      message's top-level MIME parts, without
      recursing into "message/
      rfc822" "message/rfc822" or "message/global" parts.  Note
      that EmailBodyParts may have subParts if they are of type
      "multipart/*".

   o  *bodyValues*:  bodyValues: "String[EmailBodyValue]" (immutable)

      This is a map of _partId_ "partId" to an *EmailBodyValue* EmailBodyValue object for none, some
      some, or all "text/*" parts.  Which parts are included and whether
      the value is truncated is determined by various arguments to _Email/get_
      "Email/get" and
      _Email/parse_. "Email/parse".  An *EmailBodyValue* object has the
      following properties:

      *  *value*:  value: "String"

         The value of the body part after decoding
         _Content-Transfer-Encoding_ Content-Transfer-
         Encoding and decoding the _Content-Type_ 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 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_ "size" property on the corresponding
         EmailBodyPart.

      *  *isEncodingProblem*:  isEncodingProblem: "Boolean" (default: false)

         This is "true" true if malformed sections were found while decoding
         the charset, or the charset was unknown, or the content-transfer-encoding content-transfer-
         encoding was unknown.

      *  *isTruncated*:  isTruncated: "Boolean" (default: false)

         This is "true" true if the
         _value_ "value" has been truncated.

      See the security considerations Security Considerations section for issues related to
      truncation and heuristic determination of the content-type and
      charset.

   o  *textBody*:  textBody: "EmailBodyPart[]" (immutable)

      A list of "text/plain", "text/html", "image/*", "audio/*" "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*:  htmlBody: "EmailBodyPart[]" (immutable)

      A list of "text/plain", "text/html", "image/*", "audio/*" "audio/*", and/or
      "video/*" parts to display (sequentially) as the message body,
      with a preference for "text/html" when alternative versions are
      available.

   o  *attachments*:  attachments: "EmailBodyPart[]" (immutable)

      A list list, traversing depth-first, of all parts in _bodyStructure_, traversing depth-first, which "bodyStructure"
      that satisfy either of the following conditions:

      *  not of type "multipart/*" and not included in _textBody_ "textBody" or
         _htmlBody_
         "htmlBody"

      *  of type "image/*", "audio/*" "audio/*", or "video/*" and not in both
         _textBody_
         "textBody" and _htmlBody_ "htmlBody"
      None of these parts include subParts, including "message/*" types.
      Attached messages may be fetched using the Email/parse "Email/parse" method
      and the blobId.  Note, an [HTML] "blobId".

      Note that a "text/html" body part [HTML] may reference image parts
      in attachments by using "cid:" links to reference the _Content-Id_, Content-Id,
      as defined in [RFC2392], or by referencing the _Content-Location_. Content-Location.

   o  *hasAttachment*:  hasAttachment: "Boolean" (immutable; server-set)

      This is "true" true if there are one or more parts in the message that a
      client UI should offer as downloadable.  A server SHOULD set
      hasAttachment to "true" true if the _attachments_ "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, way or are referenced as embedded images in
      one of the "text/
      html" "text/html" parts of the message.

      The server MAY set hasAttachment based on implementation-defined
      or site configurable site-configurable heuristics.

   o  *preview*:  preview: "String" (immutable; server-set)

      A plain text plaintext fragment of the message body.  This is intended to be
      shown as a preview line on a mailbox listing, 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 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 Email a second time MAY return a different result.  However,
      the previous value is not considered incorrect, and the change
      SHOULD NOT cause the Email object to be considered as changed by
      the server.

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

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

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

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

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

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

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

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

  parseStructure( [ bodyStructure ], 'mixed', false,
      htmlBody, textBody, attachments );
   For instance, consider a message with both text and HTML versions
   that's then
   that has gone through a list software manager that attaches a
   header/footer. header
   and footer.  It might have a MIME structure something like:

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

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

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

4.2.  Email/get

   Standard

   This is a standard "/get" method as described in [I-D.ietf-jmap-core] section
   5.1, [RFC8620],
   Section 5.1 with the following additional request arguments:

   o  *bodyProperties*:  bodyProperties: "String[]"

      A list of properties to fetch for each EmailBodyPart returned.  If
      omitted, this defaults to:

         [ "partId", "blobId", "size", "name", "type", "charset",
           "disposition", "cid", "language", "location" ]

   o  *fetchTextBodyValues*:  fetchTextBodyValues: "Boolean" (default: false)

      If "true", true, the
      _bodyValues_ "bodyValues" property includes any "text/*" part in
      the "textBody" property.

   o  *fetchHTMLBodyValues*:  fetchHTMLBodyValues: "Boolean" (default: false)

      If "true", true, the
      _bodyValues_ "bodyValues" property includes any "text/*" part in
      the "htmlBody" property.

   o  *fetchAllBodyValues*:  fetchAllBodyValues: "Boolean" (default: false)

      If "true", true, the
      _bodyValues_ "bodyValues" property includes any "text/*" part in
      the "bodyStructure" property.

   o  *maxBodyValueBytes*:  maxBodyValueBytes: "UnsignedInt" (default: 0)

      If greater than zero, the _value_ "value" property of any EmailBodyValue
      object returned in _bodyValues_ "bodyValues" MUST be truncated if necessary so
      it does not exceed this number of octets in size.  If "0" 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. 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_ "properties" argument is omitted or "null", null, the
   following default MUST be used instead of "all" properties:

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

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

   o  id

   o  blobId

   o  threadId

   o  mailboxIds

   o  keywords

   o  size

   o  receivedAt

   o  messageId

   o  inReplyTo
   o  sender

   o  from

   o  to

   o  cc

   o  bcc

   o  replyTo

   o  subject

   o  sentAt

   o  hasAttachment

   o  preview

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

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

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

4.2.1.  Example

   Request:

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

   and response:

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

4.3.  Email/changes

   Standard

   This is a standard "/changes" method as described in [I-D.ietf-jmap-core]
   section [RFC8620],
   Section 5.2.  If generating intermediate states for a large set of
   changes, it is recommended that newer changes are be returned first, as
   these are generally of more interest to users.

4.4.  Email/query

   Standard

   This is a standard "/query" method as described in [I-D.ietf-jmap-core] section
   5.5, [RFC8620],
   Section 5.5 but with the following additional request arguments:

   o  *collapseThreads*:  collapseThreads: "Boolean" (default: false)

      If "true", emails true, Emails in the same thread Thread as a previous email Email in the list
      (given the filter and sort order) will be removed from the list.
      This means only one email Email at most will be included in the list for
      any given
      thread. Thread.

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

4.4.1.  Filtering

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

   o  *inMailbox*:  inMailbox: "Id"

      A mailbox Mailbox id.  An email Email must be in this mailbox Mailbox to match the
      condition.

   o  *inMailboxOtherThan*:  inMailboxOtherThan: "Id[]"

      A list of mailbox Mailbox ids.  An email Email must be in at least one mailbox Mailbox
      not in this list to match the condition.  This is to allow
      messages solely in trash/spam to be easily excluded from a search.

   o  *before*:  before: "UTCDate"

      The _receivedAt_ "receivedAt" date-time of the email Email must be before this date-time date-
      time to match the condition.

   o  *after*:  after: "UTCDate"

      The _receivedAt_ "receivedAt" date-time of the email Email must be the same or after
      this date-time to match the condition.

   o  *minSize*:  minSize: "UnsignedInt"

      The _size_ "size" property of the email in octets Email must be equal to or greater than
      this number to match the condition.

   o  *maxSize*:  maxSize: "UnsignedInt"

      The _size_ "size" property of the email in octets Email must be less than this number to
      match the condition.

   o  *allInThreadHaveKeyword*:  allInThreadHaveKeyword: "String"

      All emails Emails (including this one) in the same thread Thread as this email Email
      must have the given keyword to match the condition.

   o  *someInThreadHaveKeyword*:  someInThreadHaveKeyword: "String"

      At least one email Email (possibly this one) in the same thread Thread as this email
      Email must have the given keyword to match the condition.

   o  *noneInThreadHaveKeyword*:  noneInThreadHaveKeyword: "String"

      All emails Emails (including this one) in the same thread Thread as this email Email
      must *not* have the given keyword to match the condition.

   o  *hasKeyword*:  hasKeyword: "String"

      This email Email must have the given keyword to match the condition.

   o  *notKeyword*:  notKeyword: "String"

      This email Email must not have the given keyword to match the condition.

   o  *hasAttachment*:  hasAttachment: "Boolean"

      The "hasAttachment" property of the
      email Email must be identical to the
      value given to match the condition.

   o  *text*:  text: "String"

      Looks for the text in emails. Emails.  The server MUST look up text in the _from_, _to_, _cc_, _bcc_, _subject_
      From, To, Cc, Bcc, and Subject header fields of the message, 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*:  from: "String"

      Looks for the text in the _From_ From header field of the message.

   o  *to*:  to: "String"

      Looks for the text in the _To_ To header field of the message.

   o  *cc*:  cc: "String"

      Looks for the text in the _Cc_ Cc header field of the message.

   o  *bcc*:  bcc: "String"

      Looks for the text in the _Bcc_ Bcc header field of the message.

   o  *subject*:  subject: "String"

      Looks for the text in the _subject_ property Subject header field of the email. message.

   o  *body*:  body: "String"

      Looks for the text in one of the body parts of the email. message.  The
      server MAY exclude MIME body parts with content media types other
      than "text/_" "text/*" and "message/_" "message/*" from consideration in search
      matching.  Care should be taken to match based on the text content
      actually presented to an end-user end user by viewers for that media type, type
      or otherwise identified as appropriate for search indexing.
      Matching document metadata uninteresting to an end-user end user (e.g.,
      markup tag and attribute names) is undesirable.

   o  *header*:  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_
      has a header field of the given name.

   If zero properties are specified on the FilterCondition, the
   condition MUST always evaluate to "true". true.  If multiple properties are
   specified, ALL must apply for the condition to be "true" true (it is
   equivalent to splitting the object into one-property conditions and
   making them all the child of an AND filter operator).

   The exact semantics for matching "String" fields is *deliberately not
   defined* to allow for flexibility in indexing implementation, subject
   to the following:

   o  Any syntactically correct [RFC2047] encoded sections [RFC2047] of header
      fields with a known encoding SHOULD be decoded before attempting
      to match text.

   o  When searching inside a "text/html" body part, any text considered
      markup rather than content SHOULD be ignored, including HTML tags
      and most attributes, anything inside the "<head>" tag, CSS Cascading
      Style Sheets (CSS), and JavaScript.  Attribute content intended
      for presentation to the user such as "alt" and "title" SHOULD be
      considered in the search.

   o  Text SHOULD be matched in a case-insensitive manner.

   o  Text contained in either (but matched) single (') or double (")
      quotes SHOULD be treated as a *phrase search*, search*; that is is, a match is
      required for that exact word or sequence of words, excluding the
      surrounding quotation marks.  Use "\"", "\'" and "\\"

      Within a phrase, to match one of the following characters you MUST
      escape it by prefixing it with a
      literal """, "'" and "\" respectively in a phrase. backslash (\):

                                    ' " \

   o  Outside of a phrase, white-space white space SHOULD be treated as dividing
      separate tokens that may be searched for separately, separately but MUST all
      be present for the email Email to match the filter.

   o  Tokens (not part of a phrase) MAY be matched on a whole-word basis
      using stemming (so for example (for example, a text search for "bus" would match
      "buses" but not "business").

4.4.2.  Sorting

   The following value for the "property" field on the Comparator object
   MUST be supported for sorting:

   o  *receivedAt*  "receivedAt" - The _receivedAt_ "receivedAt" date as returned in the Email
      object.

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

   o  *size*  "size" - The _size_ "size" as returned in the Email object.

   o  *from*  "from" - This is taken to be either the "name" part, property or if
      "null"/empty then
      null/empty, the "email" part, property of the *first* EmailAddress
      object in the _from_ Email's "from" property.  If still none, consider
      the value to be the empty string.

   o  *to*  "to" - This is taken to be either the "name" part, property or if
      "null"/empty then null/
      empty, the "email" part, property of the *first* EmailAddress object in
      the _to_ Email's "to" property.  If still none, consider the value to
      be the empty string.

   o  *subject*  "subject" - This is taken to be the base subject of the email, message,
      as defined in section Section 2.1 of [RFC5256].

   o  *sentAt*  "sentAt" - The _sentAt_ "sentAt" property on the Email object.

   o  *hasKeyword*  "hasKeyword" - This value MUST be considered "true" true if the email Email has
      the keyword given as an additional _keyword_ "keyword" property on the
      _Comparator_
      Comparator object, or "false" false otherwise.

   o  *allInThreadHaveKeyword*  "allInThreadHaveKeyword" - This value MUST be considered "true" true for
      the email Email if *all* of the emails Emails in the same thread
      (regardless of mailbox) Thread have the
      keyword given as an additional
      _keyword_ "keyword" property on the _Comparator_
      Comparator object.

   o  *someInThreadHaveKeyword*  "someInThreadHaveKeyword" - This value MUST be considered "true" true for
      the email Email if *any* of the emails Emails in the same thread
      (regardless of mailbox) Thread have the
      keyword given as an additional
      _keyword_ "keyword" property on the _Comparator_
      Comparator object.

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

   Example sort:

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

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

4.4.3.  Thread collapsing Collapsing

   When _collapseThreads_ "collapseThreads" is "true", true, then after filtering and sorting the email
   Email list, the list is further winnowed by removing any emails Emails for a thread
   Thread id that has already been seen (when passing through the list
   sequentially).  A thread Thread will therefore only appear *once* in the
   result, at the position of the first email Email in the list that belongs
   to the thread Thread (given the current sort/filter).

4.5.  Email/queryChanges

   Standard

   This is a standard "/queryChanges" method as described in [I-D.ietf-jmap-core]
   section 5.6, [RFC8620],
   Section 5.6 with the following additional request arguments: argument:

   o  *collapseThreads*:  collapseThreads: "Boolean" (default: false)

      The
      _collapseThreads_ "collapseThreads" argument that was used with _Email/query_. "Email/query".

4.6.  Email/set

   Standard

   This is a standard "/set" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.3.  The _Email/set_ "Email/set" method encompasses:

   o  Creating a draft

   o  Changing the keywords of an email (e.g. Email (e.g., unread/flagged status)

   o  Adding/removing an email Email to/from mailboxes Mailboxes (moving a message)

   o  Deleting emails Emails

   The format of the keywords/mailboxIds "keywords"/"mailboxIds" properties means that when
   updating an email Email, you can either replace the entire set of keywords/
   mailboxes
   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 [RFC8620],
   Section 5.3 for the specification and section Section 5.7 for an example).

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

   o  The _headers_ "headers" property MUST NOT be given, given on either the top-level
      email
      Email or an EmailBodyPart - -- the client must set each header field
      as an individual property.

   o  There MUST NOT be two properties that represent the same header
      field (e.g. (e.g., "header:from" and "from") within the Email or
      particular EmailBodyPart.

   o  Header fields MUST NOT be specified in parsed forms that are
      forbidden for that particular field.

   o  Header fields beginning with "Content-" MUST NOT be specified on
      the Email object, only on EmailBodyPart objects.

   o  If a bodyStructure "bodyStructure" property is given, there MUST NOT be textBody,
      htmlBody
      "textBody", "htmlBody", or attachments "attachments" properties.

   o  If given, the bodyStructure "bodyStructure" EmailBodyPart MUST NOT contain a
      property representing a header field that is already defined on
      the top-level Email object.

   o  If given, textBody MUST contain exactly one body part, part and it MUST
      be of type "text/plain".

   o  If given, htmlBody MUST contain exactly one body part, part and it MUST
      be of type "text/html".

   o  Within an EmailBodyPart:

      *  The client may specify a partId OR a blobId blobId, but not both.  If
         a partId is given, this partId MUST be present in the bodyValues
         "bodyValues" property.

      *  The charset "charset" property MUST be omitted if a partId is given
         (the part's content is included in bodyValues bodyValues, and the server
         may choose any appropriate encoding).

      *  The size "size" property MUST be omitted if a partId is given.  If a
         blobId is given, it may be included but is ignored by the
         server (the size is actually calculated from the blob content
         itself).

      *  A "Content-Transfer-Encoding" Content-Transfer-Encoding header field MUST NOT be given.

   o  Within an EmailBodyValue object, isEncodingProblem and isTruncated
      MUST be either "false" false or omitted.

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

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

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

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

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

   For successfully created Email objects, the _created_ "created" response
   contains the _id_, _blobId_, _threadId_ "id", "blobId", "threadId", and _size_ "size" properties of the
   object.

   The following extra _SetError_ SetError types are defined:

   For *create*: "create":

   o  "blobNotFound": At least one blob id given for an EmailBodyPart
      doesn't exist.  An extra _notFound_ "notFound" property of type "Id[]" MUST
      be included in the error SetError object containing every _blobId_ "blobId"
      referenced by an EmailBodyPart that could not be found on the
      server.

   For *create* "create" and *update*: "update":

   o  "tooManyKeywords": The change to the email's Email's keywords would exceed
      a server-defined maximum.

   o  "tooManyMailboxes": The change to the email's mailboxes set of Mailboxes that this
      Email is in would exceed a server-defined maximum.

4.7.  Email/copy

   Standard

   This is a standard "/copy" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.4, except only the _mailboxIds_, _keywords_ "mailboxIds", "keywords", and _receivedAt_
   "receivedAt" properties may be set during the copy.  This method
   cannot modify the
   RFC5322 representation of an email. message represented by the Email.

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

   For successfully copied Email objects, the _created_ "created" response
   contains the _id_, _blobId_, _threadId_ "id", "blobId", "threadId", and _size_ "size" properties of the
   new object.

4.8.  Email/import

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

   o  *accountId*:  accountId: "Id"

      The id of the account to use.

   o  *ifInState*:  ifInState: "String|null"

      This is a state string as returned by the _Email/get_ "Email/get" method.  If
      supplied, the string must match the current state of the account
      referenced by the accountId,
      otherwise accountId; otherwise, the method will be aborted
      and a "stateMismatch" error returned.  If "null", null, any changes will
      be applied to the current state.

   o  *emails*:  emails: "Id[EmailImport]"

      A map of creation id (client specified) to EmailImport objects objects.

   An *EmailImport* object has the following properties:

   o  *blobId*:  blobId: "Id"

      The id of the blob containing the raw [RFC5322]
      message. message [RFC5322].

   o  *mailboxIds*:  mailboxIds: "Id[Boolean]"

      The ids of the mailboxes Mailboxes to assign this email Email to.  At least one mailbox
      Mailbox MUST be given.

   o  *keywords*:  keywords: "String[Boolean]" (default: {})

      The keywords to apply to the email. Email.

   o  *receivedAt*:  receivedAt: "UTCDate" (default: time of most recent Received
      header, or time of import on server if none)

      The _receivedAt_ "receivedAt" date to set on the email. Email.

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

   The server MAY forbid two email Email objects with the same exact [RFC5322]
   content, content
   [RFC5322], or even just with the same [RFC5322] Message-ID, Message-ID [RFC5322], to
   coexist within an account.  In this case, it MUST reject attempts to
   import an email Email considered to be a duplicate with an "alreadyExists"
   SetError.  An
   _existingId_ "existingId" property of type "Id" MUST be included on
   the error SetError object with the id of the existing email. 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_, "blobId", "mailboxIds", or _keywords_ "keywords" properties are invalid
   (e.g.
   (e.g., missing, wrong type, id not found), the server MUST reject the
   import with an "invalidProperties" SetError.

   If the email Email cannot be imported because it would take the account
   over quota, the import should be rejected with an "overQuota"
   SetError.

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

   The response has the following arguments:

   o  *accountId*:  accountId: "Id"

      The id of the account used for this call.

   o  *oldState*:  oldState: "String|null"

      The state string that would have been returned by _Email/get_ "Email/get" on
      this account before making the requested changes, or "null" null if the
      server doesn't know what the previous state string was.

   o  *newState*:  newState: "String"

      The state string that will now be returned by
      _Email/get_ "Email/get" on this
      account.

   o  *created*:  created: "Id[Email]|null"
      A map of the creation id to an object containing the _id_, _blobId_, _threadId_ "id",
      "blobId", "threadId", and _size_ "size" properties for each successfully
      imported Email, or "null" null if none.

   o  *notCreated*:  notCreated: "Id[SetError]|null"

      A map of the creation id to a SetError object for each Email that
      failed to be created, or
      "null" null if all successful.  The possible
      errors are defined above.

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

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

4.9.  Email/parse

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

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

   o  id

   o  mailboxIds

   o  keywords

   o  receivedAt

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

   The _Email/parse_ "Email/parse" method takes the following arguments:

   o  *accountId*:  accountId: "Id"

      The id of the account to use.

   o  *blobIds*:  blobIds: "Id[]"

      The ids of the blobs to parse.

   o  *properties*:  properties: "String[]"

      If supplied, only the properties listed in the array are returned
      for each Email object.  If omitted, defaults to:

      [ "messageId", "inReplyTo", "references", "sender", "from", "to",
      "cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment",
      "preview", "bodyValues", "textBody", "htmlBody", "attachments" ]

   o  *bodyProperties*:  bodyProperties: "String[]"

      A list of properties to fetch for each EmailBodyPart returned.  If
      omitted, defaults to the same value as the Email/get "Email/get"
      "bodyProperties" default argument.

   o  *fetchTextBodyValues*:  fetchTextBodyValues: "Boolean" (default: false)

      If "true", true, the
      _bodyValues_ "bodyValues" property includes any "text/*" part in
      the "textBody" property.

   o  *fetchHTMLBodyValues*:  fetchHTMLBodyValues: "Boolean" (default: false)

      If "true", true, the
      _bodyValues_ "bodyValues" property includes any "text/*" part in
      the "htmlBody" property.

   o  *fetchAllBodyValues*:  fetchAllBodyValues: "Boolean" (default: false)

      If "true", true, the
      _bodyValues_ "bodyValues" property includes any "text/*" part in
      the "bodyStructure" property.

   o  *maxBodyValueBytes*:  maxBodyValueBytes: "UnsignedInt" (default: 0)

      If greater than zero, the _value_ "value" property of any EmailBodyValue
      object returned in _bodyValues_ "bodyValues" MUST be truncated if necessary so
      it does not exceed this number of octets in size.  If "0" 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. 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:

   o  *accountId*:  accountId: "Id"
      The id of the account used for the call.

   o  *parsed*:  parsed: "Id[Email]|null"

      A map of blob id to parsed Email representation for each
      successfully parsed blob, or "null" null if none.

   o  *notParsable*:  notParsable: "Id[]|null"

      A list of ids given that corresponded to blobs that could not be
      parsed as emails, Emails, or "null" null if none.

   o  *notFound*:  notFound: "Id[]|null"

      A list of blob ids given that could not be found, or "null" null if none.

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

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

4.10.  Examples

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

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

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

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

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

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

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

   The response from the server may look something like this:

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

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

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

   The server applies this and sends the success response:

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

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

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

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

   The response:

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

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

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

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

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

   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 same request using back-references).

   It knows something has changed most brilliant plan.  Let me tell you all about "Ma783e5cdf5f2deffbc97930a", so
   it will refetch the mailboxes and keywords (the only mutable
   properties) for this email too. it.  What we
 do is, we

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

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

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

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

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

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

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

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

5.  Search snippets Snippets

   When doing a search on a "String" property, the client may wish to
   show the relevant section of the body that matches the search as a
   preview instead of the beginning of the message, and to highlight any matching terms in both this and the
   subject of the email. Email.  Search snippets represent this data.

   A *SearchSnippet* object has the following properties:

   o  *emailId*:  emailId: "Id"

      The email Email id the snippet applies to.

   o  *subject*:  subject: "String|null"

      If text from the filter matches the subject, this is the subject
      of the email Email with the following transformations:

      1.  Any instance of the following three characters MUST be
          replaced by an appropriate [HTML] HTML entity: & (ampersand), <
          (less-than sign), and > (greater-than sign). sign) [HTML].  Other
          characters MAY also be replaced with an HTML entity form.

      2.  The matching words/phrases from the filter are wrapped in HTML
          "<mark></mark>" tags.

      If the subject does not match text from the filter, this property
      is "null". null.

   o  *preview*:  preview: "String|null"

      If text from the filter matches the
      plain-text plaintext or HTML body, this
      is the relevant section of the body (converted to plain text plaintext if
      originally HTML), with the same transformations as the _subject_ "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 null.

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

   Note,

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

   The following JMAP method is supported: supported.

5.1.  SearchSnippet/get

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

   o  *accountId*:  accountId: "Id"

      The id of the account to use.

   o  *filter*:  filter: "FilterOperator|FilterCondition|null"

      The same filter as passed to Email/query; "Email/query"; see the description of
      this method in
      section Section 4.4 for details.

   o  *emailIds*:  emailIds: "Id[]"

      The ids of the emails Emails to fetch snippets for.

   The response has the following arguments:

   o  *accountId*:  accountId: "Id"

      The id of the account used for the call.

   o  *list*:  list: "SearchSnippet[]"
      An array of SearchSnippet objects for the requested email Email ids.
      This may not be in the same order as the ids that were in the
      request.

   o  *notFound*:  notFound: "Id[]|null"

      An array of email Email ids requested which that could not be found, or "null" null
      if all ids were found.

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

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

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

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

5.2.  Example

   Here

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

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

   Example response:

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

6.  Identities

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

   o  *id*:  id: "Id" (immutable; server-set)

      The id of the identity. Identity.

   o  *name*:  name: "String" (default: "")

      The "From" _name_ name the client SHOULD use when creating a new message Email
      from this identity. Identity.

   o  *email*:  email: "String" (immutable)

      The "From" email address the client MUST use when creating a new message
      Email from this identity. Identity.  If the
      mailbox "mailbox" part of the address
      (the section before the "@") is the single character "*" (e.g. "*@example.com") then (e.g.,
      "*@example.com"), the client may use any valid address ending in
      that domain (e.g. (e.g., "foo@example.com").

   o  *replyTo*:  replyTo: "EmailAddress[]|null" (default: null)

      The Reply-To value the client SHOULD set when creating a new message Email
      from this
      identity. Identity.

   o  *bcc*:  bcc: "EmailAddress[]|null" (default: null)

      The Bcc value the client SHOULD set when creating a new message Email from
      this identity. Identity.

   o  *textSignature*:  textSignature: "String" (default: "") Signature

      A signature the client SHOULD insert into new plain-text plaintext messages
      that will be sent from this identity. Identity.  Clients MAY ignore this
      and/or combine this with a client-specific signature preference.

   o  *htmlSignature*:  htmlSignature: "String" (default: "") Signature

      A signature the client SHOULD insert into new HTML messages that
      will be sent from this
      identity. Identity.  This text MUST be an HTML
      snippet to be inserted into the "<body></body>" section of the new email.
      HTML.  Clients MAY ignore this and/or combine this with a client-specific client-
      specific signature preference.

   o  *mayDelete*:  mayDelete: "Boolean" (server-set)

      Is the user allowed to delete this identity? Identity?  Servers may wish to
      set this to "false" false for the user's username or other default
      address.  Attempts to destroy an
      identity 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_. EmailAddress.

   Multiple identities with the same email address MAY exist, to allow
   for different settings the user wants to pick between (for example example,
   with different names/signatures).

   The following JMAP methods are supported: supported.

6.1.  Identity/get

   Standard

   This is a standard "/get" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.1.  The _ids_ "ids" argument may be "null" null to fetch all at once.

6.2.  Identity/changes

   Standard

   This is a standard "/changes" method as described in [I-D.ietf-jmap-core]
   section [RFC8620],
   Section 5.2.

6.3.  Identity/set

   Standard

   This is a standard "/set" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.3.  The following extra _SetError_ SetError types are defined:

   For *create*: "create":

   o  "forbiddenFrom": The user is not allowed to send from the address
      given as the _email_ "email" property of the identity. Identity.

6.4.  Example

   Request:

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

   with response:

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

7.  Email submission Submission

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

   o  *id*:  id: "Id" (immutable; server-set)

      The id of the email submission. EmailSubmission.

   o  *identityId*:  identityId: "Id" (immutable)

      The id of the identity Identity to associate with this submission.

   o  *emailId*:  emailId: "Id" (immutable)
      The id of the email Email to send.  The
      email Email being sent does not have
      to be a draft, for example example, when "redirecting" an existing email Email
      to a different address.

   o  *threadId*:  threadId: "Id" (immutable; server-set)

      The thread Thread id of the
      email Email to send.  This is set by the server to
      the _threadId_ "threadId" property of the email Email referenced by the _emailId_. "emailId".

   o  *envelope*:  envelope: "Envelope|null" (immutable)

      Information for use when sending via SMTP.  An *Envelope* object
      has the following properties:

      *  *mailFrom*:  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
         [RFC3461] ENVID parameter [RFC3461] and
         the EmailSubmission object id.  Servers that do this MAY
         replace a client-provided value for ENVID with a server-provided server-
         provided value.

      *  *rcptTo*:  rcptTo: "Address[]"

         The email addresses to send the message to, and any RCPT TO
         parameters to pass with the recipient.

      An *Address* object has the following properties:

      *  *email*:  email: "String"

         The email address being represented by the object.  This is a
         "Mailbox" as used in the Reverse-path or Forward-path of the
         MAIL FROM or RCPT TO command in [RFC5321].

      *  *parameters*:  parameters: "Object|null"

         Any parameters to send with the email address (either mail-parameter mail-
         parameter or rcpt-parameter as appropriate, as specified in
         [RFC5321]).  If supplied, each key in the object is a parameter
         name, and the value is either the parameter value (type
         "String") or null if the parameter does not take a value
         then "null". value.  For
         both name and value, any xtext or unitext encodings are removed ([RFC3461],
         (see [RFC3461] and [RFC6533]) and JSON string encoding is
         applied.

      If the _envelope_ "envelope" property is "null" null or omitted on creation, the
      server MUST generate this from the referenced email Email as follows:

      *  *mailFrom*:  "mailFrom": The email address in the _Sender_ header, Sender header field, if present,
         otherwise
         present; otherwise, it's the _From_ header, if present, and email address in the From header
         field, if present.  In either case, no parameters. parameters are added.

         If multiple addresses are present in one of these headers, header
         fields, or there is more than one _Sender_/_From_ header, Sender/From header field, the
         server SHOULD reject the email EmailSubmission as invalid but otherwise invalid; otherwise,
         it MUST take the first address in the last _Sender_/_From_ Sender/From header in the
         [RFC5322] version of the message.
         field.

         If the address found from this is not allowed by the identity Identity
         associated with this submission, the _email_ "email" property from the identity
         Identity MUST be used instead.

      *  *rcptTo*:  "rcptTo": The deduplicated set of email addresses from the
         _To_, _Cc_ To,
         Cc, and _Bcc_ headers, Bcc header fields, if present, with no parameters for
         any of them.

   o  *sendAt*:  sendAt: "UTCDate" (immutable; server-set)

      The date the email submission was/will be released for delivery.  If the
      client successfully used [RFC4865] FUTURERELEASE [RFC4865] with the email,
      submission, this MUST be the time when the server will release the email; otherwise
      message; otherwise, it MUST be the time the EmailSubmission was
      created.

   o  *undoStatus*:  undoStatus: "String"

      This represents whether the submission may be canceled.  This is
      server set on create and MUST be one of the following values:

      *  "pending": It may be possible to cancel this submission.

      *  "final": The email message has been relayed to at least one recipient
         in a manner that cannot be recalled.  It is no longer possible
         to cancel this submission.

      *  "canceled": The email submission was canceled and will not be
         delivered to any recipient.

      On systems that do not support unsending, the value of this
      property will always be "final".  On systems that do support
      canceling submission, it will start as "pending", "pending" and MAY
      transition to "final" when the server knows it definitely cannot
      recall the email, message, but it MAY just remain "pending".  If in
      pending state, a client can attempt to cancel the submission by
      setting this property to "canceled"; if the update succeeds, the
      submission was successfully canceled canceled, and the email message has not been
      delivered to any of the original recipients.

   o  *deliveryStatus*:  deliveryStatus: "String[DeliveryStatus]|null" (server-set)

      This represents the delivery status for each of the email's submission's
      recipients, if known.  This property MAY not be supported by all
      servers, in which case it will remain "null". 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_
      DeliveryStatus object.

      A *DeliveryStatus* object has the following properties:

      *  *smtpReply*:  smtpReply: "String"

         The SMTP reply string returned for this recipient when the
         server last tried to relay the email, message, or in a later DSN (Delivery Delivery
         Status Notification, Notification (DSN, as defined in [RFC3464]) response for
         the email. message.  This SHOULD be the response to the RCPT TO stage,
         unless this was accepted and the email message as a whole was
         rejected at the end of the DATA stage, in which case the DATA
         stage reply SHOULD be used instead.

         Multi-line SMTP responses should be concatenated to a single
         string as follows:

         +  The hyphen following the SMTP code on all but the last line
            is replaced with a space.

         +  Any prefix in common with the first line is stripped from
            lines after the first.

         +  CRLF is replaced by a space.

         For example:

          550-5.7.1 Our system has detected that this message is
          550 5.7.1 likely spam.

         would become:

    550 5.7.1 Our system has detected that this message is likely spam.

         For emails messages relayed via an alternative to SMTP, the server MAY
         generate a synthetic string representing the status instead.
         If it does this, the string MUST be of the following form:

         +  A 3-digit SMTP reply code, as defined in [RFC5321], section
            Section 4.2.3.

         +  Then a single space character.

         +  Then an SMTP Enhanced Mail System Status Code as defined in
            [RFC3463], with a registry defined in [RFC5248].

         +  Then a single space character.

         +  Then an implementation-specific information string with a
            human readable
            human-readable explanation of the response.

      *  *delivered*:  delivered: "String"

         Represents whether the email message has been successfully delivered
         to the recipient.  This MUST be one of the following values:

         +  "queued": The email message is in a local mail queue and the
            status will change once it exits the local mail queues.  The _smtpReply_
            "smtpReply" property may still change.

         +  "yes": The email message was successfully delivered to the mailbox mail
            store of the recipient.  The _smtpReply_ "smtpReply" property is final.

         +  "no": Delivery to the recipient permanently failed.  The
            _smtpReply_
            "smtpReply" property is final.

         +  "unknown": The final delivery status is unknown, (e.g. (e.g., it
            was relayed to an external machine and no further
            information is available).  The _smtpReply_ "smtpReply" property may
            still change if a DSN arrives.

         Note,

         Note that successful relaying to an external SMTP server SHOULD
         NOT be taken as an indication that the email message has successfully
         reached the final mailbox. mail store.  In this case though, the server
         may receive a DSN response, if requested.

         If a DSN is received for the recipient with Action equal to
         "delivered", as per
         [RFC3464] section [RFC3464], Section 2.3.3, then the _delivered_
         "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*:  displayed: "String"

         Represents whether the email message has been displayed to the
         recipient.  This MUST be one of the following values:

         +  "unknown": The display status is unknown.  This is the
            initial value.

         +  "yes": The recipient's system claims the email message content has
            been displayed to the recipient.  Note,  Note that there is no
            guarantee that the recipient has noticed, read, or
            understood the content.

         If an MDN a Message Disposition Notification (MDN) is received for
         this recipient with Disposition-Type (as per [RFC8098] section [RFC8098],
         Section 3.2.6.2) equal to "displayed", this property SHOULD be
         set to "yes".

         The server MAY also set this property based on other feedback
         channels.

   o  *dsnBlobIds*:  dsnBlobIds: "Id[]" (server-set)

      A list of blob ids for Delivery
      Status Notifications ([RFC3464]) DSNs [RFC3464] received for this
      submission, in order of receipt, oldest first.  The blob is the
      whole MIME message (with a top-level content-type of multipart/report), "multipart/
      report"), as received.

   o  *mdnBlobIds*:  mdnBlobIds: "Id[]" (server-set)

      A list of blob ids for Message
      Disposition Notifications ([RFC8098]) 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), "multipart/
      report"), as received.

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

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

   The following JMAP methods are supported: supported.

7.1.  EmailSubmission/get

   Standard

   This is a standard "/get" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.1.

7.2.  EmailSubmission/changes

   Standard

   This is a standard "/changes" method as described in [I-D.ietf-jmap-core]
   section [RFC8620],
   Section 5.2.

7.3.  EmailSubmission/query

   Standard

   This is a standard "/query" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.5.

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

   o  *identityIds*:  identityIds: "Id[]"

      The EmailSubmission _identityId_ "identityId" property must be in this list to
      match the condition.

   o  *emailIds*:  emailIds: "Id[]"

      The EmailSubmission _emailId_ "emailId" property must be in this list to
      match the condition.

   o  *threadIds*:  threadIds: "Id[]"

      The EmailSubmission _threadId_ "threadId" property must be in this list to
      match the condition.

   o  *undoStatus*:  undoStatus: "String"

      The EmailSubmission _undoStatus_ "undoStatus" property must be identical to the
      value given to match the condition.

   o  *before*:  before: "UTCDate"
      The _sendAt_ "sendAt" property of the EmailSubmission object must be before
      this date-time to match the condition.

   o  *after*:  after: "UTCDate"

      The _sendAt_ "sendAt" property of the EmailSubmission object must be the
      same as or after this date-time to match the condition.

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

   The following EmailSubmission properties MUST be supported for
   sorting:

   o  "emailId"

   o  "threadId"

   o  "sentAt"

7.4.  EmailSubmission/queryChanges

   Standard

   This is a standard "/queryChanges" method as described in [I-D.ietf-jmap-core]
   section [RFC8620],
   Section 5.6.

7.5.  EmailSubmission/set

   Standard

   This is a standard "/set" method as described in [I-D.ietf-jmap-core] section
   5.3, [RFC8620],
   Section 5.3 with the following two additional request arguments:

   o  *onSuccessUpdateEmail*:  onSuccessUpdateEmail: "Id[PatchObject]|null"

      A map of
      _EmailSubmission id_ EmailSubmission id to an object containing properties to
      update on the Email object referenced by the EmailSubmission if
      the create/update/destroy succeeds.  (For references to
      EmailSubmissions created in the same "/set" invocation, this is
      equivalent to a creation-reference creation-reference, so the id will be the creation
      id prefixed with a "#".)

   o  *onSuccessDestroyEmail*:  onSuccessDestroyEmail: "Id[]|null"

      A list of _EmailSubmission
      ids_ EmailSubmission ids for which the email Email with the
      corresponding emailId "emailId" should be destroyed if the create/update/destroy create/update/
      destroy succeeds.  (For references to EmailSubmission creations,
      this is equivalent to a creation-
      reference creation-reference, so the id will be the
      creation id prefixed with a "#".)

   A
   After all create/update/destroy items in the "EmailSubmission/set"
   invocation have been processed, a single implicit _Email/set_ "Email/set" call
   MUST be made after all
   EmailSubmissions cred in the same "/set" invocation/update/destroy
   requests have been processed to perform any changes requested in these two arguments.
   The response to this MUST be returned after the
   _EmailSubmission/set_ "EmailSubmission/set"
   response.

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

   If the referenced email Email is destroyed at any point after the
   EmailSubmission object is created, this MUST NOT change the behaviour
   of the email submission (i.e. (i.e., it does not cancel a future send).  The
   _emailId_
   "emailId" and _threadId_ "threadId" properties of the submission EmailSubmission object
   remain, but trying to fetch them (with a standard Email/get "Email/get" call)
   will return a "notFound" error if the corresponding objects have been
   destroyed.

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

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

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

   The following extra _SetError_ SetError types are defined:

   For *create*: "create":

   o  "invalidEmail" - The email Email to be sent is invalid in some way.  The
      SetError SHOULD contain a property called _properties_ "properties" of type
      "String[]" that lists *all* the properties of the email Email that were
      invalid.

   o  "tooManyRecipients" - The envelope (supplied or generated) has
      more recipients than the server allows.  A _maxRecipients_ "maxRecipients"
      "UnsignedInt" property MUST also be present on the SetError
      specifying the maximum number of allowed recipients.

   o  "noRecipients" - The envelope (supplied or generated) does not
      have any rcptTo emails. email addresses.

   o  "invalidRecipients" - The _rcptTo_ "rcptTo" property of the envelope
      (supplied or generated) contains at least one rcptTo value value, which
      is not a valid email address for sending to.  An _invalidRecipients_
      "invalidRecipients" "String[]" property MUST also be present on
      the SetError, which is a list of the invalid addresses.

   o  "forbiddenMailFrom" - The server does not permit the user to send
      an email
      a message with the [RFC5321] envelope From. From address [RFC5321].

   o  "forbiddenFrom" - The server does not permit the user to send an
      email a
      message with the [RFC5322] From header field [RFC5322] of the email message to be
      sent.

   o  "forbiddenToSend" - The user does not have permission to send at
      all right now for some reason.  A _description_ "description" "String" property
      MAY be present on the SetError object to display to the user why
      they are not permitted.

   For *update*: "update":

   o  "cannotUnsend":  "cannotUnsend" - The client attempted to update the _undoStatus_ "undoStatus"
      of a valid EmailSubmission object from "pending" to "canceled",
      but the email message cannot be unsent.

7.5.1.  Example

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

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

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

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

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

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

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

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

8.  Vacation response Response

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

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

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

   o  *id*:  id: "Id" (immutable; server-set)

      The id of the object.  There is only ever one vacation response VacationResponse
      object, and its id is
      ""singleton"". "singleton".

   o  *isEnabled*:  isEnabled: "Boolean"

      Should a vacation response be sent if an
      email a message arrives between
      the _fromDate_ "fromDate" and _toDate_? "toDate"?

   o  *fromDate*:  fromDate: "UTCDate|null"

      If _isEnabled_ "isEnabled" is "true" emails true, messages that arrive on or after this
      date-time (but before the _toDate_ "toDate" if defined) should receive the
      user's vacation response.  If "null", null, the vacation response is
      effective immediately.

   o  *toDate*:  toDate: "UTCDate|null"

      If _isEnabled_ "isEnabled" is "true", emails true, messages that arrive before this date-time
      (but on or after the _fromDate_ "fromDate" if defined) should receive the
      user's vacation response.  If "null", null, the vacation response is
      effective indefinitely.

   o  *subject*:  subject: "String|null"

      The subject that will be used by the message sent in response to emails
      messages when the vacation response is enabled.  If "null", null, an
      appropriate subject SHOULD be set by the server.

   o  *textBody*:  textBody: "String|null"

      The plain text plaintext body to send in response to emails messages when the
      vacation response is enabled.  If this is
      "null", when null, the vacation message is sent server SHOULD
      generate a plain-text plaintext body part
      SHOULD be generated from the _htmlBody_ "htmlBody" when sending
      vacation responses but the server MAY choose to send the response as HTML
      only.  If both _textBody_ "textBody" and
      _htmlBody_ "htmlBody" are "null", null, an appropriate
      default body SHOULD be generated for responses by the server.

   o  *htmlBody*:  htmlBody: "String|null"

      The HTML body to send in response to
      emails messages when the vacation
      response is enabled.  If this is "null",
      when null, the vacation message is sent server MAY choose to
      generate an HTML body part MAY be
      generated from the _textBody_, "textBody" when sending
      vacation responses or the server MAY choose to send the response as plain-text plaintext
      only.

   The following JMAP methods are supported: supported.

8.1.  VacationResponse/get

   Standard

   This is a standard "/get" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.1.

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

8.2.  VacationResponse/set

   Standard

   This is a standard "/set" method as described in [I-D.ietf-jmap-core] section [RFC8620],
   Section 5.3.

9.  Security considerations Considerations

   All security considerations of JMAP ([I-D.ietf-jmap-core]) [RFC8620] apply to this
   specification.  Additional considerations specific to the data types
   and functionality introduced by this document are described in the
   following subsections.

9.1.  EmailBodyPart value Value

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

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

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

9.2.  HTML email display Email Display

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

   o  Embedded JavaScript can rewrite the email message to change its content
      on subsequent opening, allowing users to be mislead.  In webmail
      systems, if run in the same origin as the interface interface, it can access
      and exfiltrate all private data accessible to the user, including
      all other emails messages and potentially contacts, calendar events,
      settings, and credentials.  It can also rewrite the interface to
      undetectably phish passwords.  A compromise is likely to be
      persistent, not just for the duration of page load, due to
      exfiltration of session credentials or installation of a service
      worker that can intercept all subsequent network requests (this
      however
      (however, this would only be possible if blob downloads are also
      available on the same origin, and the service worker script is
      attached to the message).

   o  HTML documents may load content directly from the internet, Internet rather
      than just referencing attached resources.  For example example, you may
      have an "<img>" tag with an external "src" attribute.  This may
      leak to the sender when a message is opened, as well as the IP
      address of the recipient.  Cookies may also be sent and set by the
      server, allowing tracking between different emails messages and even
      website visits and advertising profiles.

   o  In webmail systems, CSS can break the layout or create phishing
      vulnerabilities.  For example, the use of "position:fixed" can
      allow an email a message to draw content outside of its normal bounds,
      potentially clickjacking a real interface element.

   o  If in a webmail context and not inside a separate frame, any
      styles defined in CSS rules will apply to interface elements as
      well if the selector matches, allowing the interface to be
      modified.  Similarly, any interface styles that match elements in
      the email message will alter their appearance, potentially breaking the
      layout of the email. message.

   o  The link text in HTML has no necessary correlation with the actual
      target of the link, which can be used to make phishing attacks
      more convincing.

   o  Links opened from an email a message or embedded external content may leak
      private info in the "Referer" Referer header sent by default in most
      systems.

   o  Forms can be used to mimic login boxes, providing a potent
      phishing vector if allowed to submit directly from the email message
      display.

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

   o  HTML can be filtered before rendering, stripping potentially
      malicious content.  Sanitizing  Sanitising HTML correctly is tricky, and
      implementers
      implementors are strongly recommended to use a well-tested library
      with a carefully vetted whitelist-only approach.  New features
      with unexpected security characteristics may be added to HTML
      rendering engines in the future; a blacklist approach is likely to
      result in security issues.

      Subtle differences in parsing of HTML can introduce security
      flaws: to filter with 100% accuracy accuracy, you need to use the same
      parser when
   sanitizing that the HTML rendering engine will use.

   o  Encapsulating the message in an "<iframe sandbox>", as defined in
      [HTML], section Section 4.7.6, can help mitigate a number of risks.  This
      will:

      *  Disable JavaScript.

      *  Disable form submission.

      *  Prevent drawing outside of its bounds, bounds or conflict with conflicts between
         message CSS and interface CSS.

      *  Establish a unique anonymous origin, separate to the containing
         origin.

   o  A strong Content Security Policy [3] (see <https://www.w3.org/TR/
      CSP3/>) can, among other things, block JavaScript and the loading
      of external content should it manage to evade the filter.

   o  The leakage of information in the Referer header can be mitigated
      with the use of a referrer policy [4]. (see <https://www.w3.org/TR/
      referrer-policy/>).

   o  A "crossorigin=anonymous" attribute on tags that load remote
      content can prevent cookies from being sent.

   o  If adding "target=_blank" to open links in new tabs, also add
      "rel=noopener" to ensure the page that opens cannot change the URL
      in the original tab to redirect the user to a phishing site.

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

9.3.  Multiple part display Part Display

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

9.4.  Email submission Submission

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

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

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

9.5.  Partial account access Account Access

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

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

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

9.6.  Permission to send Send from an address

   The Address

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

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

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

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

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

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

10.  IANA considerations Considerations

10.1.  JMAP capability registration Capability Registration for "mail"

   IANA will register has registered the "mail" JMAP Capability as follows:

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

   Specification document: this document

   Intended use: common

   Change Controller: IETF

   Security and privacy considerations: this document, section Section 9

10.2.  JMAP capability registration Capability Registration for "submission"

   IANA will register has registered the "submission" JMAP Capability as follows:

   Capability Name: "urn:ietf:params:jmap:submission" urn:ietf:params:jmap:submission
   Specification document: this document

   Intended use: common

   Change Controller: IETF

   Security and privacy considerations: this document, section Section 9

10.3.  JMAP capability registration Capability Registration for "vacationresponse"

   IANA will register has registered the "vacationresponse" JMAP Capability as
   follows:

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

   Specification document: this document

   Intended use: common

   Change Controller: IETF

   Security and privacy considerations: this document, section Section 9

10.4.  IMAP and JMAP keywords registry Keywords Registry

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

   First, the name of the registry is changed to the "IMAP and JMAP
   keywords Registry".
   Keywords" registry.

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

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

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

10.4.1.  Registration of JMAP keyword '$draft' Keyword "$draft"

   This registers the JMAP-only "JMAP-only" keyword '$draft' "$draft" in the "IMAP and JMAP
   keywords Registry".
   Keywords" registry.

   Keyword name: "$draft" $draft

   Scope: JMAP-only

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

   Private or Shared on a server: BOTH

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

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

   Related keywords: None

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

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

   Published specification (recommended): specification: this document

   Person & email address to contact for further information: (editor-
   contact-goes-here) JMAP
   mailing list <jmap@ietf.org>

   Intended usage: COMMON
   Owner/Change controller: IESG

10.4.2.  Registration of JMAP keyword '$seen' Keyword "$seen"

   This registers the JMAP-only "JMAP-only" keyword '$seen' "$seen" in the "IMAP and JMAP
   keywords Registry".
   Keywords" registry.

   Keyword name: "$seen" $seen

   Scope: JMAP-only

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

   Private or Shared on a server: BOTH

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

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

   Related keywords: None

   Related IMAP/JMAP Capabilities: None

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

   Published specification (recommended): specification: this document

   Person & email address to contact for further information: (editor-
   contact-goes-here) JMAP
   mailing list <jmap@ietf.org>

   Intended usage: COMMON

   Owner/Change controller: IESG

10.4.3.  Registration of JMAP keyword '$flagged' Keyword "$flagged"

   This registers the JMAP-only "JMAP-only" keyword '$flagged' "$flagged" in the "IMAP and
   JMAP
   keywords Registry". Keywords" registry.

   Keyword name: "$flagged" $flagged

   Scope: JMAP-only

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

   Private or Shared on a server: BOTH

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

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

   Related keywords: None

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

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

   Published specification (recommended): specification: this document

   Person & email address to contact for further information: (editor-
   contact-goes-here) JMAP
   mailing list <jmap@ietf.org>

   Intended usage: COMMON

   Owner/Change controller: IESG

10.4.4.  Registration of JMAP keyword '$answered' Keyword "$answered"

   This registers the JMAP-only "JMAP-only" keyword '$answered' "$answered" in the "IMAP and
   JMAP keywords Registry". Keywords" registry.

   Keyword name: "$answered" $answered

   Scope: JMAP-only

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

   Private or Shared on a server: BOTH

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

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

   Related keywords: None

   Related IMAP/JMAP Capabilities: None

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

   Published specification (recommended): specification: this document

   Person & email address to contact for further information: (editor-
   contact-goes-here) JMAP
   mailing list <jmap@ietf.org>

   Intended usage: COMMON

   Owner/Change controller: IESG

10.4.5.  Registration of '$recent' keyword "$recent" Keyword

   This registers the keyword '$recent' "$recent" in the "IMAP and JMAP keywords
   Registry". Keywords"
   registry.

   Keyword name: "$recent" $recent

   Scope: reserved

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

   Published specification (recommended): specification: this document

   Person & email address to contact for further information: (editor-
   contact-goes-here) JMAP
   mailing list <jmap@ietf.org>

   Owner/Change controller: IESG

10.5.  IMAP Mailbox Name Attributes Registry

10.5.1.  Registration of "inbox" role in Role

   This registers the JMAP-only "JMAP-only" "inbox" attribute in the "IMAP Mailbox
   Name Attributes Registry", Attributes" registry, as established in [RFC8457].

   Attribute Name: Inbox

   Description: New mail is delivered here by default.

   Reference: This document, section 10.5. Section 10.5.1

   Usage Notes: JMAP only

10.6.  JMAP Error Codes registry Registry

   The following sub-sections subsections register several new error codes in the
   JMAP
   "JMAP Error Codes Codes" registry, as defined in [I-D.ietf-jmap-core]. [RFC8620].

10.6.1.  mailboxHasChild

   JMAP Error Code: mailboxHasChild

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 2.5

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

10.6.2.  mailboxHasEmail

   JMAP Error Code: mailboxHasEmail

   Intended use: common

   Change controller: IETF
   Reference: This document, section Section 2.5

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

10.6.3.  blobNotFound

   JMAP Error Code: blobNotFound

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 4.6

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

10.6.4.  tooManyKeywords

   JMAP Error Code: tooManyKeywords

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 4.6

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

10.6.5.  tooManyMailboxes

   JMAP Error Code: tooManyMailboxes

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 4.6

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

10.6.6.  invalidEmail

   JMAP Error Code: invalidEmail

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 7.5

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

10.6.7.  tooManyRecipients

   JMAP Error Code: tooManyRecipients

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 7.5

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

10.6.8.  noRecipients

   JMAP Error Code: noRecipients

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 7.5

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

10.6.9.  invalidRecipients

   JMAP Error Code: invalidRecipients

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 7.5
   Description: The rcptTo property of the RFC5321 envelope [RFC5321] (supplied
   or generated) contains at least one rcptTo value which that is not a valid
   email address for sending to.

10.6.10.  forbiddenMailFrom

   JMAP Error Code: forbiddenMailFrom

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 7.5

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

10.6.11.  forbiddenFrom

   JMAP Error Code: forbiddenFrom

   Intended use: common

   Change controller: IETF

   Reference: This document, sections Sections 6.3 and 7.5

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

10.6.12.  forbiddenToSend

   JMAP Error Code: forbiddenToSend

   Intended use: common

   Change controller: IETF

   Reference: This document, section Section 7.5

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

11.  References

11.1.  Normative References

   [HTML]     Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and
              S. Moon, "HTML 5.2", World Wide Web Consortium
              Recommendation REC-html52-20171214, December 2017,
              <https://www.w3.org/TR/html52/>.

   [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
              Extension for Message Size Declaration", STD 10, RFC 1870,
              DOI 10.17487/RFC1870, November 1995,
              <https://www.rfc-editor.org/info/rfc1870>.

   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part One: Format of Internet Message
              Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
              <https://www.rfc-editor.org/info/rfc2045>.

   [RFC2047]  Moore, K., "MIME (Multipurpose Internet Mail Extensions)
              Part Three: Message Header Extensions for Non-ASCII Text",
              RFC 2047, DOI 10.17487/RFC2047, November 1996,
              <https://www.rfc-editor.org/info/rfc2047>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC2231]  Freed, N. and K. Moore, "MIME Parameter Value and Encoded
              Word Extensions: Character Sets, Languages, and
              Continuations", RFC 2231, DOI 10.17487/RFC2231, November
              1997, <https://www.rfc-editor.org/info/rfc2231>.

   [RFC2369]  Neufeld, G. and J. Baer, "The Use of URLs as Meta-Syntax
              for Core Mail List Commands and their Transport through
              Message Header Fields", RFC 2369, DOI 10.17487/RFC2369,
              July 1998, <https://www.rfc-editor.org/info/rfc2369>.

   [RFC2392]  Levinson, E., "Content-ID and Message-ID Uniform Resource
              Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998,
              <https://www.rfc-editor.org/info/rfc2392>.

   [RFC2557]  Palme, J., Hopmann, A., and N. Shelness, "MIME
              Encapsulation of Aggregate Documents, such as HTML
              (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999,
              <https://www.rfc-editor.org/info/rfc2557>.

   [RFC2852]  Newman, D., "Deliver By SMTP Service Extension", RFC 2852,
              DOI 10.17487/RFC2852, June 2000,
              <https://www.rfc-editor.org/info/rfc2852>.

   [RFC3282]  Alvestrand, H., "Content Language Headers", RFC 3282,
              DOI 10.17487/RFC3282, May 2002,
              <https://www.rfc-editor.org/info/rfc3282>.

   [RFC3461]  Moore, K., "Simple Mail Transfer Protocol (SMTP) Service
              Extension for Delivery Status Notifications (DSNs)",
              RFC 3461, DOI 10.17487/RFC3461, January 2003,
              <https://www.rfc-editor.org/info/rfc3461>.

   [RFC3463]  Vaudreuil, G., "Enhanced Mail System Status Codes",
              RFC 3463, DOI 10.17487/RFC3463, January 2003,
              <https://www.rfc-editor.org/info/rfc3463>.

   [RFC3464]  Moore, K. and G. Vaudreuil, "An Extensible Message Format
              for Delivery Status Notifications", RFC 3464,
              DOI 10.17487/RFC3464, January 2003,
              <https://www.rfc-editor.org/info/rfc3464>.

   [RFC3834]  Moore, K., "Recommendations for Automatic Responses to
              Electronic Mail", RFC 3834, DOI 10.17487/RFC3834, August
              2004, <https://www.rfc-editor.org/info/rfc3834>.

   [RFC4314]  Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
              RFC 4314, DOI 10.17487/RFC4314, December 2005,
              <https://www.rfc-editor.org/info/rfc4314>.

   [RFC4422]  Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
              Authentication and Security Layer (SASL)", RFC 4422,
              DOI 10.17487/RFC4422, June 2006,
              <https://www.rfc-editor.org/info/rfc4422>.

   [RFC4616]  Zeilenga, K., Ed., "The PLAIN Simple Authentication and
              Security Layer (SASL) Mechanism", RFC 4616,
              DOI 10.17487/RFC4616, August 2006,
              <https://www.rfc-editor.org/info/rfc4616>.

   [RFC4865]  White, G. and G. Vaudreuil, "SMTP Submission Service
              Extension for Future Message Release", RFC 4865,
              DOI 10.17487/RFC4865, May 2007,
              <https://www.rfc-editor.org/info/rfc4865>.

   [RFC4954]  Siemborski, R., Ed. and A. Melnikov, Ed., "SMTP Service
              Extension for Authentication", RFC 4954,
              DOI 10.17487/RFC4954, July 2007,
              <https://www.rfc-editor.org/info/rfc4954>.

   [RFC5198]  Klensin, J. and M. Padlipsky, "Unicode Format for Network
              Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
              <https://www.rfc-editor.org/info/rfc5198>.

   [RFC5248]  Hansen, T. and J. Klensin, "A Registry for SMTP Enhanced
              Mail System Status Codes", BCP 138, RFC 5248,
              DOI 10.17487/RFC5248, June 2008,
              <https://www.rfc-editor.org/info/rfc5248>.

   [RFC5256]  Crispin, M. and K. Murchison, "Internet Message Access
              Protocol - SORT and THREAD Extensions", RFC 5256,
              DOI 10.17487/RFC5256, June 2008,
              <https://www.rfc-editor.org/info/rfc5256>.

   [RFC5321]  Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
              DOI 10.17487/RFC5321, October 2008,
              <https://www.rfc-editor.org/info/rfc5321>.

   [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,
              DOI 10.17487/RFC5322, October 2008,
              <https://www.rfc-editor.org/info/rfc5322>.

   [RFC5788]  Melnikov, A. and D. Cridland, "IMAP4 Keyword Registry",
              RFC 5788, DOI 10.17487/RFC5788, March 2010,
              <https://www.rfc-editor.org/info/rfc5788>.

   [RFC6154]  Leiba, B. and J. Nicolson, "IMAP LIST Extension for
              Special-Use Mailboxes", RFC 6154, DOI 10.17487/RFC6154,
              March 2011, <https://www.rfc-editor.org/info/rfc6154>.

   [RFC6409]  Gellens, R. and J. Klensin, "Message Submission for Mail",
              STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011,
              <https://www.rfc-editor.org/info/rfc6409>.

   [RFC6532]  Yang, A., Steele, S., and N. Freed, "Internationalized
              Email Headers", RFC 6532, DOI 10.17487/RFC6532, February
              2012, <https://www.rfc-editor.org/info/rfc6532>.

   [RFC6533]  Hansen, T., Ed., Newman, C., and A. Melnikov,
              "Internationalized Delivery Status and Disposition
              Notifications", RFC 6533, DOI 10.17487/RFC6533, February
              2012, <https://www.rfc-editor.org/info/rfc6533>.

   [RFC6710]  Melnikov, A. and K. Carlberg, "Simple Mail Transfer
              Protocol Extension for Message Transfer Priorities",
              RFC 6710, DOI 10.17487/RFC6710, August 2012,
              <https://www.rfc-editor.org/info/rfc6710>.

   [RFC7677]  Hansen, T., "SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple
              Authentication and Security Layer (SASL) Mechanisms",
              RFC 7677, DOI 10.17487/RFC7677, November 2015,
              <https://www.rfc-editor.org/info/rfc7677>.

   [RFC8098]  Hansen, T., Ed. and A. Melnikov, Ed., "Message Disposition
              Notification", STD 85, RFC 8098, DOI 10.17487/RFC8098,
              February 2017, <https://www.rfc-editor.org/info/rfc8098>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8314]  Moore, K. and C. Newman, "Cleartext Considered Obsolete:
              Use of Transport Layer Security (TLS) for Email Submission
              and Access", RFC 8314, DOI 10.17487/RFC8314, January 2018,
              <https://www.rfc-editor.org/info/rfc8314>.

   [RFC8457]  Leiba, B., Ed., "IMAP "$Important" Keyword and
              "\Important" Special-Use Attribute", RFC 8457,
              DOI 10.17487/RFC8457, September 2018,
              <https://www.rfc-editor.org/info/rfc8457>.

   [RFC8474]  Gondwana, B., Ed., "IMAP Extension for Object
              Identifiers", RFC 8474, DOI 10.17487/RFC8474, September
              2018, <https://www.rfc-editor.org/info/rfc8474>.

   [RFC8620]  Jenkins, N. and C. Newman, "The JSON Meta Application
              Protocol", RFC 8620, DOI 10.17487/RFC8620, June 2019,
              <https://www.rfc-editor.org/info/rfc8620>.

11.2.  Informative References

   [EFAIL]    Poddebniak, D., Dresen, C., Mueller, J., Ising, F.,
              Schinzel, S., Friedberger, S., Somorovsky, J., and J.
              Schwenk, "Efail: Breaking S/MIME and OpenPGP Email
              Encryption using Exfiltration Channels", August 2018,
              <https://www.usenix.org/system/files/conference/
              usenixsecurity18/sec18-poddebniak.pdf>.

   [milter]   Unknown,   Postfix, "Postfix before-queue Milter support", 2019,
              <http://www.postfix.org/MILTER_README.html>.

   [RFC3501]  Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
              4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
              <https://www.rfc-editor.org/info/rfc3501>.

   [RFC7489]  Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based
              Message Authentication, Reporting, and Conformance
              (DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015,
              <https://www.rfc-editor.org/info/rfc7489>.

   [XCLIENT]  Unknown,  Postfix, "Postfix XCLIENT Howto", 2019,
              <http://www.postfix.org/XCLIENT_README.html>.

11.3.  URIs

   [1] https://www.iana.org/assignments/imap-mailbox-name-attributes/
       imap-mailbox-name-attributes.xhtml

   [2] https://www.iana.org/assignments/imap-keywords/imap-
       keywords.xhtml

   [3] https://www.w3.org/TR/CSP3/
   [4] https://www.w3.org/TR/referrer-policy/

Authors' Addresses

   Neil Jenkins
   FastMail
   Fastmail
   PO Box 234, Collins St St. West
   Melbourne
   Melbourne, VIC  8007
   Australia

   Email: neilj@fastmailteam.com
   URI:   https://www.fastmail.com

   Chris Newman
   Oracle
   440 E. Huntington Dr., Suite 400
   Arcadia
   Arcadia, CA  91006
   United States of America

   Email: chris.newman@oracle.com