JMAP                                                          N. Jenkins
Internet-Draft                                                  FastMail
Updates: 5788 (if approved)                            November 29, 2017                                March 5, 2018
Intended status: Standards Track
Expires: June 2, September 6, 2018

                             JMAP for Mail
                        draft-ietf-jmap-mail-03
                        draft-ietf-jmap-mail-04

Abstract

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

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 of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents 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 June 2, September 6, 2018.

Copyright Notice

   Copyright (c) 2017 2018 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  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
     1.2.  The Date datatypes  . . . . . . . . . . . . . . . . . . .   4
     1.3.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
     1.4.  Addition to the capabilities object . . . . . . . . . . .   4
     1.5.  Data profile name . . . . . . . . . . . . . . . . . . . .   6
   2.  Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . .   5   6
     2.1.  getMailboxes  Mailbox/get . . . . . . . . . . . . . . . . . . . . . .   8 .   9
     2.2.  getMailboxUpdates  Mailbox/changes . . . . . . . . . . . . . . . . . . . .   8 .   9
     2.3.  getMailboxList  Mailbox/query . . . . . . . . . . . . . . . . . . . . . .   9
     2.4.  getMailboxListUpdates  Mailbox/queryChanges  . . . . . . . . . . . . . . . . . .   9  10
     2.5.  setMailboxes  Mailbox/set . . . . . . . . . . . . . . . . . . . . . .   9 .  10
   3.  Threads . . . . . . . . . . . . . . . . . . . . . . . . . . .  10
     3.1.  getThreads  Thread/get  . . . . . . . . . . . . . . . . . . . . . . .  11
       3.1.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  11
     3.2.  getThreadUpdates  Thread/changes  . . . . . . . . . . . . . . . . . . . .  11 .  12
   4.  Messages  Emails  . . . . . . . . . . . . . . . . . . . . . . . . . .  11 .  12
     4.1.  getMessages  Properties of the Email object  . . . . . . . . . . . . .  12
       4.1.1.  Metadata  . . . . . . . . . .  16
       4.1.1.  Example . . . . . . . . . . . .  12
       4.1.2.  Header fields . . . . . . . . . . . . . . . . . . . .  14
       4.1.3.  Body parts  . . . .  17 . . . . . . . . . . . . . . . . .  19
     4.2.  getMessageUpdates  Email/get . . . . . . . . . . . . . . . . . . . . . . . .  26
       4.2.1.  Example . . . . . . . . . . . . . . . . . .  17 . . . . .  28
     4.3.  getMessageList  Email/changes . . . . . . . . . . . . . . . . . . . . . .  29
     4.4.  Email/query . . . . . . . . . . . . . . . . . . . . .  18
       4.3.1. . .  30
       4.4.1.  Filtering . . . . . . . . . . . . . . . . . . . . . .  18
       4.3.2.  30
       4.4.2.  Sorting . . . . . . . . . . . . . . . . . . . . . . .  21
       4.3.3.  32
       4.4.3.  Thread collapsing . . . . . . . . . . . . . . . . . .  22
       4.3.4.  33
       4.4.4.  Response  . . . . . . . . . . . . . . . . . . . . . .  22
     4.4.  getMessageListUpdates  34
     4.5.  Email/queryChanges  . . . . . . . . . . . . . . . . . .  22
     4.5.  setMessages .  34
     4.6.  Email/set . . . . . . . . . . . . . . . . . . . . . . .  22
     4.6.  importMessages .  34
     4.7.  Email/import  . . . . . . . . . . . . . . . . . . . .  23
     4.7.  copyMessages . .  35
     4.8.  Email/copy  . . . . . . . . . . . . . . . . . . . . . . .  37
     4.9.  Email/parse . . . . . . . . . . . . . . . . . . .  25 . . . .  39
   5.  MessageSubmission  Email submission  . . . . . . . . . . . . . . . . . . . . . .  27  40
     5.1.  getMessageSubmissions  EmailSubmission/get . . . . . . . . . . . . . . . . . .  32 .  45
     5.2.  getMessageSubmissionUpdates  EmailSubmission/changes . . . . . . . . . . . . . . .  32 . .  45
     5.3.  getMessageSubmissionList  EmailSubmission/query . . . . . . . . . . . . . . . .  32 . .  45
     5.4.  getMessageSubmissionListUpdates  EmailSubmission/queryChanges  . . . . . . . . . . . . .  33 .  45
     5.5.  setMessageSubmissions  EmailSubmission/set . . . . . . . . . . . . . . . . . .  33 .  46
   6.  Identities  . . . . . . . . . . . . . . . . . . . . . . . . .  35  47
     6.1.  getIdentities  Identity/get  . . . . . . . . . . . . . . . . . . . . . .  36  48
     6.2.  getIdentityUpdates  Identity/changes  . . . . . . . . . . . . . . . . . . . .  36  48
     6.3.  setIdentities  Identity/set  . . . . . . . . . . . . . . . . . . . . . .  36  49
   7.  SearchSnippets  Search snippets . . . . . . . . . . . . . . . . . . . . . . .  36  49
     7.1.  getSearchSnippets  SearchSnippet/get . . . . . . . . . . . . . . . . . . . .  37  50

   8.  Vacation Response response . . . . . . . . . . . . . . . . . . . . . .  38  51
     8.1.  getVacationResponse .  VacationResponse/get  . . . . . . . . . . . . . . . . . .  39  52
     8.2.  setVacationResponse .  VacationResponse/set  . . . . . . . . . . . . . . . . . .  39  52
   9.  Security considerations . . . . . . . . . . . . . . . . . . .  39  52
     9.1.  EmailBodyPart value . . . . . . . . . . . . . . . . . . .  52
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  39  52
     10.1.  Normative References . . . . . . . . . . . . . . . . . .  39  52
     10.2.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  42  55
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  42  55

1.  Introduction

   JMAP <https://tools.ietf.org/html/draft-ietf-jmap-core-03> is a
   generic protocol for synchronising data, such as mail, calendars or
   contacts, between a client and a server.  It is optimised for mobile
   and web environments, and aims to provide a consistent interface to
   different data types.

   This specification defines a data model for synchronising mail
   between a client and a server using JMAP.

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   The underlying format used for this specification is I-JSON
   ([RFC7493]).  Consequently, the terms "object" and "array" as well as
   the four primitive types (strings, numbers, booleans, and null) are
   to be interpreted as described in Section 1 of [RFC7159].  Unless
   otherwise noted, all the property names and values are case
   sensitive.

   Some examples in this document contain "partial" JSON documents used
   for illustrative purposes.  In these examples, three periods "..."
   are used to indicate a portion of the document that has been removed
   for compactness.

   Types signatures are given for all JSON objects in this document.
   The following conventions are used:

   o  "Boolean|String" - The value is either a JSON "Boolean" value, or
      a JSON "String" value.

   o  "Foo" - Any name that is not a native JSON type means an object
      for which the properties (and their types) are defined elsewhere
      within this document.

   o  "Foo[]" - An array of objects of type "Foo".

   o  "String[Foo]" - A JSON "Object" being used as a map (associative
      array), where all the values are of type "Foo".

   Object properties may also have a set of attributes defined along
   with the type signature.  These have the following meanings:

   o  *sever-set*: Only the server can set the value for this property.
      The client MUST NOT send this property when creating a new object
      of this type.

   o  *immutable*: The value MUST NOT change after the object is
      created.

   o  *default*: (This is followed by a JSON value).  The value that
      will be used for this property if it is omitted in an argument, or
      when creating a new object of this type.

1.2.  The Date datatypes

   Where "Date" is given as a type, it means a string in [RFC3339]
   _date-time_ format.  To ensure a normalised form, the _time-secfrac_
   MUST always be omitted and any letters in the string (e.g.  "T" and
   "Z") MUST be upper-case.  For example, ""2014-10-30T14:12:00+08:00"".

   Where "UTCDate" is given as a type, it means a "Date" where the
   _time-offset_ component MUST be "Z" (i.e. it must be in UTC time).
   For example, ""2014-10-30T06:12:00Z"".

1.3.  Terminology

   The same terminology is used in this document as in the core JMAP
   specification.

1.4.  Addition to the capabilities object

   The capabilities object is returned as part of the standard JMAP
   session
   Session object; see the JMAP spec.  Servers supporting _this_
   specification MUST add a property called "ietf:jmapmail" to the
   capabilities object.  The value of this property is an object which
   MUST contain the following information on server capabilities:

   o  *maxMailboxesPerMessage*:  *maxMailboxesPerEmail*: "Number|null" The maximum number of
      mailboxes that can be can assigned to a single message. email.  This MUST
      be an integer >= 1, or "null" for no limit (or rather, the limit
      is always the number of mailboxes in the account).

   o  *maxSizeAttachmentsPerMessage*:  *maxSizeAttachmentsPerEmail*: "Number" The maximum total size of
      attachments, in bytes, octets, allowed for a single message. email.  A server MAY
      still reject messages emails with a lower attachment size total (for
      example, if the body includes several megabytes of text, causing
      the size of the encoded MIME structure to be over some server-
      defined limit).

   o  *maxDelayedSend*: "Number" The number in seconds of the maximum
      delay the server supports in sending (see the MessageSubmission EmailSubmission
      object).  This is "0" if the server does not support delayed send.

   o  *messageListSortOptions*:  *emailsListSortOptions*: "String[]" A list of all the message email
      properties the server supports for sorting by.  This MAY include
      properties the client does not recognise (for example custom
      properties specified in a vendor extension).  Clients MUST ignore
      any unknown properties in the list.

   o  *submissionExtensions*: "String[String[]]" A JMAP implementation
      that talks to a Submission [RFC6409] server SHOULD have a
      configuration setting that allows an administrator to expose a new
      submission EHLO capability in this field.  This allows a JMAP
      server to gain access to a new submission extension without code
      changes.  By default, the JMAP server should show only known safe-
      to-expose EHLO capabilities in this field, and hide EHLO
      capabilities that are only relevant to the JMAP server.  Each key
      in the object is the _ehlo-name_, and the value is a list of
      _ehlo-args_.  Examples of safe-to-expose Submission extensions
      include:

      *  FUTURERELEASE ([RFC4865])

      *  SIZE ([RFC1870])

      *  DSN ([RFC3461])

      *  DELIVERYBY ([RFC2852])

      *  MT-PRIORITY ([RFC6710])

      A JMAP server MAY advertise an extension and implement the
      semantics of that extension locally on the JMAP server even if a
      submission server used by JMAP doesn't implement it.  The full
      IANA registry of submission extensions can be found at
      <https://www.iana.org/assignments/mail-parameters/mail-
      parameters.xhtml#mail-parameters-2>

2.  Mailboxes

   A mailbox represents a named

1.5.  Data profile name

   The data profile name for the set of emails.  This types defined in this
   specification is the primary
   mechanism for "mail".

   The JMAP Session object has an _accounts_ property with the set of
   accounts to which the user has access.  Any account that contains
   data of the types defined in this specification MUST include the
   string ""mail"" in the _hasDataFor_ property of the account object.

2.  Mailboxes

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

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

   A *Mailbox* object has the following properties:

   o  *id*: "String" (immutable; server-set) The id of the mailbox.

   o  *name*: "String" User-visible name for the mailbox, e.g.  "Inbox".
      This may be any UTF-8 Net-Unicode string ([RFC3629]) ([RFC5198]) of at least 1
      character in length and maximum 256 bytes octets in size.  Servers
      SHOULD forbid sibling Mailboxes with the same name.  Servers MAY
      reject names that violate server policy (e.g., names containing
      slash (/) or control characters).

   o  *parentId*: "String|null" (default: "null") The mailbox id for the
      parent of this mailbox, or "null" if this mailbox is at the top
      level.  Mailboxes form acyclic graphs (forests) directed by the
      child-to-parent relationship.  There MUST NOT be a loop.

   o  *role*: "String|null" (default: "null") Identifies system
      mailboxes.  This property can only be set on create.  After mailboxes that
      have a particular common purpose (e.g. the
      record has been created, this property is immutable.  The
      following values MUST be used for "inbox"), regardless of
      the relevant mailboxes:

      *  "inbox" - _name_ (which may be localised).  This value is shared with
      IMAP (exposed in IMAP via the [RFC6154] SPECIAL-USE extension).
      However, unlike in IMAP, a mailbox to which new mail is delivered by
         default, unless diverted by may only have a rule or spam filter etc.

      *  "archive" - messages the user does not need right now, but does
         not wish to delete.

      *  "drafts" - messages the user is currently writing single role,
      and are not
         yet sent.

      *  "sent" - messages the user has sent.

      *  "trash" - messages the user has deleted.

      *  "spam" - messages considered spam by the server.

      *  "templates" - drafts which should be used as templates (i.e.
         used as the basis for creating new drafts).

      No no two mailboxes in the same account may have the same role.  Mailboxes without a
      known purpose
      The value MUST have a role be one of "null". the mailbox attribute names listed in the
      IANA Mailbox Name Attributes Registry [1], as established in
      [TODO], converted to lower-case.  New roles may be established
      here in the future.  An account is not required to have mailboxes
      with any of the above particular roles.  A client
      MAY create new mailboxes with a role property to help them keep
      track of a use-case not covered by the above list.  To avoid
      potential conflict with any special behaviour a server might apply
      to mailboxes with certain roles in the future, any roles not in
      the above list created by the client must begin with ""x-"".  The
      client MAY attempt to create mailboxes with the standard roles if
      not already present, but the server MAY reject these.

   o  *sortOrder*: "Number" (default: "0") Defines the sort order of
      mailboxes when presented in the client's UI, so it is consistent
      between devices.  The number MUST be an integer in the range 0 <=
      sortOrder < 2^31.  A mailbox with a lower order should be
      displayed before a mailbox with a higher order (that has the same
      parent) in any mailbox listing in the client's UI.  Mailboxes with
      equal order SHOULD be sorted in alphabetical order by name.  The
      sorting SHOULD take into account locale-specific character order
      convention.

   o  *mayReadItems*: "Boolean" (server-set) If true, may use this
      mailbox as part of a filter in a _getMessageList_ call.  If a sub-
      mailbox is shared but not the parent mailbox, this may be "false".

   o  *mayAddItems*: "Boolean" (server-set) The user may add messages to
      this mailbox (by either creating a new message or moving an
      existing one).

   o  *mayRemoveItems*: "Boolean" (server-set) The user may remove
      messages from this mailbox (by either changing the mailboxes of a
      message or deleting it).

   o  *mayCreateChild*: "Boolean" (server-set) The user may create a
      mailbox with this mailbox as its parent.

   o  *mayRename*: "Boolean" (server-set) The user may rename the
      mailbox or make it a child of another mailbox.

   o  *mayDelete*: "Boolean" (server-set) The user may delete the
      mailbox itself.
      convention..

   o  *totalMessages*:  *totalEmails*: "Number" (server-set) The number of messages emails in this
      mailbox.

   o  *unreadMessages*:  *unreadEmails*: "Number" (server-set) The number of messages emails in this
      mailbox that have neither the "$Seen" "$seen" keyword nor the
      "$Draft" "$draft"
      keyword.

   o  *totalThreads*: "Number" (server-set) The number of threads where
      at least one message email in the thread is in this mailbox.

   o  *unreadThreads*: "Number" (server-set) The number of threads where
      at least one message email in the thread has neither the "$Seen" "$seen" keyword
      nor the "$Draft" "$draft" keyword AND at least one message email in the thread is
      in this mailbox (but see below for special case handling of
      Trash).  Note, the unread message email does not need to be the one in
      this mailbox.

   o  *myRights*: "MailboxRights" (server-set) The Trash set of rights (ACLs)
      the user has in relation to this mailbox.  A _MailboxRights_
      object has the following properties:

      *  *mayReadItems*: "Boolean" If true, the user may use this
         mailbox (that is as part of a filter in a _Email/query_ call and the
         mailbox with "role == "trash"") MUST may be
   treated specially for included in the purpose _mailboxIds_ set of _Email_
         objects.  If a sub-mailbox is shared but not the parent
         mailbox, this may be "false".  Corresponds to IMAP ACLs "lr".

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

      *  *mayRemoveItems*: "Boolean" The user may remove mail from this
         mailbox (by either changing the mailboxes of an email or
         deleting it).  Corresponds to IMAP ACLs "te".

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

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

      *  *mayCreateChild*: "Boolean" The user may create a mailbox with
         this mailbox as its parent.  Corresponds to IMAP ACL "k".

      *  *mayRename*: "Boolean" The user may rename the mailbox or make
         it a child of another mailbox.  Corresponds to IMAP ACL "x".

      *  *mayDelete*: "Boolean" The user may delete the mailbox itself.
         Corresponds to IMAP ACL "x".

      *  *maySubmit*: "Boolean" Messages may be submitted directly to
         this mailbox.  Corresponds to IMAP ACL "p".

   The Trash mailbox (that is a mailbox with "role == "trash"") MUST be
   treated specially for the purpose of unread counts:

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

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

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

   So for example, suppose you have an account where the entire contents
   is a single conversation with 2 messages: emails: an unread message email in the Trash
   and a read message email in the Inbox.  The "unreadThreads" count would be
   "1" for the Trash and "0" for the Inbox.

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

   The following JMAP methods are supported:

2.1.  getMailboxes  Mailbox/get

   Standard _getFoos_ _/get_ method.  The _ids_ argument may be "null" to fetch
   all at once.

2.2.  getMailboxUpdates  Mailbox/changes

   Standard _getFooUpdates_ _/changes_ method, but with one extra argument to the
   _mailboxUpdates_
   response:

   o  *changedProperties*: "String[]|null" If only the mailbox counts
      (unread/total messages/threads) emails/threads) have changed since the old state,
      this will be the list of properties that may have changed, i.e.
      "["totalMessages", "unreadMessages",
      "["totalEmails", "unreadEmails", "totalThreads",
      "unreadThreads"]".  If the server is unable to tell if only counts
      have changed, it MUST just be "null".

   Since counts frequently change but the rest of the mailboxes state
   for most use cases changes rarely, the server can help the client
   optimise data transfer by keeping track of changes to message email/thread
   counts separately to other state changes.  The _changedProperties_
   array may be used directly via a result reference in a subsequent getMailboxes
   Mailboxe/get call in a single request.

2.3.  getMailboxList  Mailbox/query

   Standard _getFooList_ _/query_ method.

   The

   A *FilterCondition* object (optionally passed as the _filter_
   argument) has the following properties, any of which
   may be omitted:

   o  *parentId*: "String|null" The Mailbox _parentId_ property must
      match the given value exactly.

   o  *hasRole*: "Boolean" If this is "true", a Mailbox matches if it
      has a non-"null" value for its _role_ property.

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

   The following properties MUST be supported for sorting:

   o  "sortOrder"

   o  "name"

2.4.  getMailboxListUpdates

   Standard _getFooListUpdates_ method.

2.5.  setMailboxes

   Standard _setFoos_ method.  The following extra _SetError_ types are
   defined:

   For *create*:
   o  "maxQuotaReached": The user has reached  "parent/name": This is a server-defined limit on pseudo-property, just for sorting, with
      the number following semantics: if two mailboxes have a common parent,
      sort them by name.  Otherwise, find the nearest ancestors of mailboxes.

   For *update*: each
      that share a common parent and sort by their names instead. (i.e.
      This sorts the mailbox list in tree order).

2.4.  Mailbox/queryChanges

   Standard _/queryChanges_ method.

2.5.  Mailbox/set

   Standard _/set_ method, but with the following additional argument:

   o  "forbidden": The update would violate  *onDestroyRemoveMessages*: "Boolean" (default: "false") If
      "false", attempts to destroy a mayXXX property. mailbox that still has any messages
      in it will be rejected with a "mailboxHasEmail" SetError.  If
      "true", any messages that were in the mailbox will be removed from
      it, and if in no other mailboxes will be destroyed when the
      mailbox is destroyed.

   The following extra _SetError_ types are defined:

   For *destroy*:

   o  "forbidden": The update would violate a mayXXX property.

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

   o  "mailboxHasMessage":  "mailboxHasEmail": The mailbox has at least one message assigned
      to it.  The client MUST remove these before it can delete and the
      mailbox. _onDestroyRemoveMessages_ argument was "false".

3.  Threads

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

   The JMAP spec does not require the server to use any particular
   algorithm for determining whether two messages emails belong to the same
   thread, however there is a recommended algorithm in the
   implementation guide [1]. [2].

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

   A *Thread* object has the following properties:

   o  *id*: "String" (immutable) The id of the thread.

   o  *messageIds*:  *emailIds*: "String[]" The ids of the messages emails in the thread, sorted
      such that:

      *  Any message email with the "$Draft" "$draft" keyword that has an "In-Reply-To"
         header is sorted after the _first_ non-draft message email in the
         thread with the corresponding "Message-Id" header, but before
         any subsequent non-draft messages. emails.

      *  Other than that, everything is sorted by the _receivedAt_ date
         of the message, email, oldest first.

      *  If two messages emails are identical under the above two conditions, the
         sort is server-dependent but MUST be stable (sorting by id is
         recommended).

   The following JMAP methods are supported:

3.1.  getThreads  Thread/get

   Standard _getFoos_ _/get_ method.

3.1.1.  Example

   Request:

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

   with response:

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

3.2.  getThreadUpdates  Thread/changes

   Standard _getFooUpdates_ _/changes_ method.

4.  Messages

   A *Message*  Emails

   The *Email* object is a JSON representation of an [RFC5322] message
   that hides message, which
   allows clients to avoid the complexities of MIME.  All special encodings of either
   headers or textual body parts, such as Base64 ([RFC4648]), or
   [RFC2047] MIME parsing, transport
   encoding and character encoding.

4.1.  Properties of non-ASCII characters, MUST be fully decoded
   into UTF-8.  It has the following properties:

   o  *id*: "String" (immutable; server-set) Email object

   Broadly, a message consists of two parts: a list of header fields,
   then a body.  The id body is normally a MIME-encoded set of documents in
   a tree structure.  The JMAP Email object provides a way to access the message.
      This
   full structure, or to use simplified properties and avoid some
   complexity if this is sufficient for the JMAP id, NOT client application.

   Due to the [RFC5322] Message-Id header. number of properties involved, the set of _Email_
   properties is specified over the following three sub-sections.

4.1.1.  Metadata

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

   o  *id*: "String" (immutable; server-set) The id of the Email object.
      Note, this is the JMAP object id, NOT the [RFC5322] Message-ID
      header field value.

   o  *blobId*: "String" (immutable; server-set) The id representing the
      raw octets of the [RFC5322] message.  This may be used to download
      the raw original
      message message, or to attach it directly to another message
      Email etc.

   o  *threadId*: "String" (immutable; server-set) The id of the thread Thread
      to which this message Email belongs.

   o  *mailboxIds*: "String[Boolean]" The set of mailbox ids this
      message is in.  A message email
      belongs to.  An email MUST belong to one or more mailboxes at all
      times (until it is deleted).  The set is represented as an object,
      with each key being a _Mailbox id_. The value for each key in the
      object MUST be "true".

   o  *keywords*: "String[Boolean]" (default: "{}") A set of keywords
      that apply to the message. email.  The set is represented as an object,
      with the keys being the _keywords_. The value for each key in the
      object MUST be "true".  Keywords are shared with IMAP.  The six
      system keywords from IMAP are treated specially.  The following
      four keywords have their first character changed from "\" in IMAP
      to "$" in JMAP and have particular semantic meaning:

      *  "$Draft":  "$draft": The message email is a draft the user is composing.

      *  "$Seen":  "$seen": The message email has been read.

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

      *  "$Answered":  "$answered": The message 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.  Users may add arbitrary
      keywords to a message. an email.  For compatibility with IMAP, a keyword is a (case-sensitive)
      case-insensitive string of 1-255 characters in the ASCII subset
      %x21-%x7e (excludes control chars and space), and MUST NOT include
      any of these characters: "( ) { ] % * " \" Because JSON is case-
      sensitive, servers MUST return keywords in lower-case.  The IANA
      Keyword Registry [2] [3] 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":  "$forwarded": The message email has been forwarded.

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

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

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

   o  *hasAttachment*: "Boolean"  *size*: "Number" (immutable; server-set) This is "true"
      if and only if The size, in octets, of
      the _attachments_ property raw data for the Message contains
      at least one entry where _isInline_ is "false". RFC5322 message (as referenced by the
      _blobId_, i.e. the number of octets in the file the user would
      download).

   o  *headers*: "String[String]"  *receivedAt*: "UTCDate" (immutable; default: "{}") A map time of
      lower-cased creation on
      server) The date the email was received by the message store.
      This is the _internal date_ in IMAP.

4.1.2.  Header fields

   These properties are derived from the [RFC5322] and [RFC6532] message
   header name to (decoded) fields.  All header value for all headers fields may be fetched in the message.  For a raw form.  Some
   headers may also be fetched in a parsed form.  The structured form
   that occur multiple times (e.g.
      "Received"), may be fetched depends on the values header.  The following forms are concatenated with a single new line
      ("\n") character in between each one.
   defined:

   o  *sender*: "Emailer|null" (immutable; default: "null") An Emailer
      object (see below) containing the name/email from  *Raw* ("String") The raw octets of the parsed
      "Sender" header of field value from the email.  If
      first octet following the email doesn't have a
      "Sender" header, this is "null".

   o  *from*: "Emailer[]|null" (immutable; default: "null") An array of
      name/email objects (see below) representing the parsed "From" header of the email, in field name terminating colon, up
      to but excluding the same order as they appear header field terminating CRLF.  Any
      standards-compliant message MUST be either ASCII (RFC5322) or
      UTF-8 (RFC6532), however other encodings exist in the
      header.  If the email doesn't have wild.  A
      server MAY use heuristics to determine a "From" header, this is
      "null".  If charset and decode the header exists but does not have
      octets, or MAY replace any content, octet or octet run with the
      response is an array of zero length.

   o  *to*: "Emailer[]|null" (immutable; default: "null") An array of
      name/email objects (see below) representing high bit
      set that violates UTF-8 syntax with the parsed "To" unicode replacement
      character (U+FFFD).  Any NUL octet MUST be dropped.

   o  *Text* ("String") The header field value with:

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

      2.  The terminating CRLF at the end of the email, in value removed

      3.  Any SP characters at the same order as they appear in beginning of the header. value removed

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

      5.  Any [RFC6532] UTF-8 values decoded.

      6.  The resulting unicode converted to NFC form.

      If any decodings fail, the email doesn't have parser SHOULD insert a "To" header, 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 is "null".  If form may only be fetched or set
      for the following header fields:

      *  Subject

      *  Comment

      *  Any header exists but does not have any content, the response is an
      array of zero length. defined in [RFC5322] or [RFC2369]

   o  *cc*: "Emailer[]|null" (immutable; default: "null") An array of
      name/email objects (see below) representing the parsed "Cc"  *Addresses* ("EmailAddress[]") The header
      of the email, in the same order is parsed as they appear an
      "address-list" value, as specified in [RFC5322] section 3.4, into
      the header.  If "EmailAddress[]" type.  The *EmailAddress* object has the email doesn't have a "Cc" header,
      following properties:

      *  *name*: "String|null" The _display-name_ of the [RFC5322]
         _mailbox_ or _group_, or "null" if none.  If this is "null".  If the
      header exists but does not have a _quoted-
         string_:

         1.  The surrounding DQUOTE characters are removed.

         2.  Any _quoted-pair_ is decoded.

         3.  White-space is unfolded, and then any content, the response leading or trailing
             white-space is an
      array of zero length.

   o  *bcc*: "Emailer[]|null" (immutable; default: "null") An array of
      name/email objects (see below) representing the parsed "Bcc"
      header removed.

      *  *email*: "String|null" The _addr-spec_ of the email.  If the email doesn't have [RFC5322]
         _mailbox_, or "null" if a "Bcc" header
      (which will _group_.

   Any syntactically correct [RFC2047] encoded sections with a known
   encoding MUST be true decoded, following the same rules as for most emails outside of the Sent mailbox),
      this is "null".  If _Text_
   form.  Any [RFC6532] UTF-8 values MUST be decoded.

   Parsing SHOULD be best-effort in the header exists but face of invalid structure to
   accommodate invalid messages and semi-complete drafts.  EmailAddress
   objects MAY have an _email_ property that does not have any
      content, conform to the response is
   _addr-spec_ form (for example, may not contain an array of zero length.

   o  *replyTo*: "Emailer[]|null" (immutable; default: "null") An array
      of name/email objects (see below) representing @ symbol).

   To prevent obviously nonsense behaviour, which can lead to
   interoperability issues, this form may only be fetched or set for the parsed "Reply-
      To"
   following header of the email, 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 not defined in the same order [RFC5322] or [RFC2369]

   o  *MessageIds* ("String[]|null") The header is parsed as they appear a list of
      "msg-id" values, as specified in [RFC5322] section 3.6.4, into the
      header.
      "String[]" type.  If parsing fails, the email doesn't have a "Reply-To" header, this value is "null".  If

   To prevent obviously nonsense behaviour, which can lead to
   interoperability issues, this form may only be fetched or set for the
   following header exists but does not have any content, the
      response is an array of zero length. fields:

   o  *subject*: "String" (immutable; default: """") The subject of the
      message.  If none, defaults to the empty string,  Message-ID

   o  In-Reply-To

   o  References

   o  Resent-Message-ID

   o  Any header not "null". defined in [RFC5322] or [RFC2369]

   o  *sentAt*: "Date" (immutable; default: time of creation on server)  *Date* ("Date|null") The header is parsed date from the message's _Date_ header.

   o  *receivedAt*: "UTCDate" (immutable; default: time of creation on
      server) The date as a "date-time" value,
      as specified in [RFC5322] section 3.3, into the message was received by "Date" type.  If
      parsing fails, the message store.
      This value is "null".

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

   o  Date

   o  Resent-Date

   o  Any header not defined in IMAP. [RFC5322] or [RFC2369]

   o  *size*: "Number" (immutable; server-set)  *URL* ("String|null") The size header is parsed as a URL, as described
      in bytes of [RFC2369], into the
      whole message as counted by "String" type.  This does not include the server towards
      surrounding angle brackets or any comments in the user's quota.

   o  *preview*: "String" (immutable; server-set) Up to 256 characters
      of header with the beginning of a plain text version of
      URL.  If parsing fails, the message body.
      This value is intended "null".

   To prevent obviously nonsense behaviour, which can lead to be shown as a preview line on a mailbox
      listing, and the server
   interoperability issues, this form may choose to skip quoted sections only be fetched or
      salutations to return a more useful preview. set for the
   following header fields:

   o  *textBody*: "String" (immutable; default: """")  List-Help

   o  List-Unsubscribe

   o  List-Subscribe

   o  List-Post

   o  List-Owner

   o  List-Archive

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

   The plain text
      body part following low-level *Email* property is specified for complete
   access to the message.  If there is only an HTML version header data of the body, a plain text version MUST be generated from this; the
      exact method of conversion in this case is not defined and is
      server-specific.  If there message:

   o  *headers*: "EmailHeader[]" (immutable) This is neither a "text/plain" nor a "text/
      html" body part, this MUST be the empty string.

   o  *htmlBody*: "String|null" (immutable; default: "null") The HTML
      body part for the message if present.

   o  *attachments*: "Attachment[]|null" (default: "null") An array list of
      attachment objects (see below) detailing all the attachments to
      the message.

   o  *attachedMessages*: "String[Message]|null" (immutable; server-set)
      An object mapping attachment id (as found in the "attachments"
      property) to a *Message* object with the following properties, for
      each
      [RFC5322] message attached to this one:

      *  headers

      *  from

      *  to

      *  cc

      *  bcc

      *  replyTo

      *  subject

      *  date

      *  textBody

      *  htmlBody

      *  attachments

      *  attachedMessages

      This property is set by header fields, in the server based on same order they appear in the _attachments_
      property.
      message.  An *Emailer* *EmailHeader* object has the following properties:

   o

      *  *name*: "String" The name of header _field name_ as defined in RFC5322,
         with the sender/recipient.  If a name
      cannot be extracted for an email, this property SHOULD be same capitalization that it has in the
      empty string.

   o  *email*: message.

      *  *value*: "String" The email address header _field value_ as defined in
         RFC5322, in _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. characters that have values between 33 and
   126, inclusive), except colon.  The property may also have the sender/recipient.
   following suffixes:

   o  *:as{header-form}* This
      MUST be means the value is in a parsed form, where
      "{header-form}" is one of the form ""<mailbox>@<host>"" parsed-form names specified above.
      If a "host" or even
      "mailbox" cannot be extracted for an email, not given, the empty string
      SHOULD be used for this part (so value is in _Raw_ form.

   o  *:all* This means the result MUST always still
      contain value is an ""@"" character).

   Group information and comments from 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 RFC 5322 header field
      (i.e. identical to the *last* item in the array if :all is used),
      or "null" if none.

   If both suffixes are used, they MUST be
   discarded when converting into specified in the order above.
   Header field names are matched case-insensitively.  The value is
   typed according to the requested form, or an Emailer object.

   Example array of Emailer objects:

            [
                {name:"Joe Bloggs", email:"joeb@example.com"},
                {name:"", email:"john@example.com"},
                {name:"John Smith", email: "john@"}
            ]

   An *Attachment* object has that type if
   :all is used.  If no header fields exist in the following properties:

   o  *blobId*: "String" The id message with the
   requested name, the value is "null" if fetching a single instance, or
   the empty array if requesting :all.

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

   For a more complex example, consider the binary data.

   o  *type*: "String" client requesting a property
   called "header:Resent-To:asAddresses:all".  This means:

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

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

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

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

   o  *name*: "String|null"  *messageId*: "String[]|null" (immutable) The full file name, e.g.
      "myworddocument.doc", if available. value is identical to
      the value of _header:Message-ID:asMessageIds_. For messages
      conforming to RFC5322 this will be an array with a single entry.

   o  *size*: "Number"  *inReplyTo*: "String[]|null" (immutable) The size, in bytes, value is identical to
      the value of _header:In-Reply-To:asMessageIds_.

   o  *references*: "String[]|null" (immutable) The value is identical
      to the attachment when fully
      decoded (i.e. value of _header:References:asMessageIds_.

   o  *sender*: "EmailAddress[]|null" (immutable) The value is identical
      to the value of _header:Sender:asAddresses_.

   o  *from*: "EmailAddress[]|null" (immutable) The value is identical
      to the value of _header:From:asAddresses_.

   o  *to*: "EmailAddress[]|null" (immutable) The value is identical to
      the value of _header:To:asAddresses_.

   o  *cc*: "EmailAddress[]|null" (immutable) The value is identical to
      the value of _header:Cc:asAddresses_.

   o  *bcc*: "EmailAddress[]|null" (immutable) The value is identical to
      the value of _header:Bcc:asAddresses_.

   o  *replyTo*: "EmailAddress[]|null" (immutable) The value is
      identical to the value of _header:Reply-To:asAddresses_.

   o  *subject*: "String|null" (immutable) The value is identical to the
      value of _header:Subject:asText_.

   o  *sentAt*: "Date|null" (immutable; default on creation: current
      server time) The value is identical to the value of
      _header:Date:asDate_.

4.1.3.  Body parts

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

   A *EmailBodyPart* object has the following properties:

   o  *partId*: "String" Identifies this part uniquely within the Email.
      This is scoped to the _emailId_ and has no meaning outside of the
      JMAP Email object representation.

   o  *blobId*: "String" The id references the raw octets of the
      contents of the part after decoding any _Content-Transfer_
      encoding (as defined in [RFC2045]).  Note, two parts may be
      transfer-encoded differently but have same 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.

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

   o  *headers*: "EmailHeader[]" (immutable) This is a list of all
      header fields in the part, in the order they appear.  The values
      are in _Raw_ form.

   o  *name*: "String|null" This is the [RFC2231] decoded _filename_
      parameter of the _Content-Disposition_ header field, or (for
      compatibility with existing systems) if not present then the
      [RFC2047] decoded _name_ parameter of the _Content-Type_ header
      field.

   o  *type*: "String" The value of the _Content-Type_ header field of
      the part, if present, otherwise "null".  CFWS is removed and any
      parameters are stripped.

   o  *charset*: "String|null" The value of the charset parameter of the
      _Content-Type_ header field, if present.

   o  *disposition*: "String|null" The value of the _Content-
      Disposition_ header field of the part, if present, otherwise
      "null".  CFWS is removed and any parameters are stripped.

   o  *cid*: "String|null" The value of the _Content-Id_ header field of
      the part, if present, otherwise "null".  CFWS is removed.  This
      may be used to reference the content from within an html body part
      using the "cid:" protocol.

   o  *language*: "String[]|null" The list of language tags, as defined
      in [RFC3282], in the _Content-Language_ header field of the part,
      if present.

   o  *location*: "String|null" The URI, as defined in [RFC2557], in the
      _Content-Location_ header field of the part, if present.

   o  *subParts*: "EmailBodyPart[]" (optional) If type is "multipart/*",
      this contains the body parts of each child.

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

   o  *bodyStructure*: "EmailBodyPart[]" (immutable) This is the full
      MIME structure of the message body, including sub parts but not
      recursing into "message/rfc822" or "message/global" parts.

   o  *bodyValues*: "String[BodyValue]" (immutable) This is a map of
      _partId_ to an *EmailBodyValue* object for none, some or all
      "text/*" parts.  Which parts are included and whether the value is
      truncated is determined by various arguments to _Email/get_ and
      _Email/parse_.  An *EmailBodyValue* object has the following
      properties:

      *  *value*: "String" The value of the body part after decoding
         _Content-Transport-Encoding_ and decoding the _Content-Type_
         charset, if known to the server.  The server MAY use heuristics
         to determine the charset to use for decoding if the charset is
         unknown, or if no charset is given, or if it believes the
         charset given is incorrect.  Decoding is best-effort and SHOULD
         insert the unicode replacement character (U+FFFD) and continue
         when a malformed section is encountered.

      *  *isEncodingProblem*: "Boolean" This is "true" if malformed
         sections were found while decoding the charset, or the charset
         was unknown.

      *  *isTruncated*: "Boolean" This is "true" if the _value_ has been
         truncated.

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

   o  *textBody*: "EmailBodyPart[]" (immutable) A list of "text/plain",
      "text/html" and "image/*" parts to display (sequentially) as the
      message body, with a preference for "text/plain" when alternative
      versions are available.

   o  *htmlBody*: "EmailBodyPart[]" (immutable) A list of "text/plain",
      "text/html" and "image/*" parts to display (sequentially) as the
      message body, with a preference for "text/html" when alternative
      versions are available.

   o  *attachedEmails*: "EmailBodyPart[]" (immutable) A list of all
      parts of type "message/rfc822" or "message/global".  Note, this
      *does not* recurse, so the parts within these are not included.
      The attached message may be fetched using the Email/parse method
      and the blobId.

   o  *attachedFiles*: "EmailBodyPart[]" (immutable) A list of all parts
      in _bodyStructure_, traversing depth-first, which satisfy either
      of the following conditions:

      *  not of type "multipart/*" and not included in _attachedEmails_,
         _textBody_ or _htmlBody_

      *  of type "image/*" and not in both _textBody_ and _htmlBody_

      Note, an HTML body part may reference image parts in attachedFiles
      using "cid:" links to reference the _Content-Id_ or by referencing
      the _Content-Location_.

   o  *hasAttachment*: "Boolean" (immutable; server-set) This is "true"
      if there are one or more parts in the message that a client UI
      should offer as downloadable.  A server SHOULD set hasAttachment
      if either:

      *  The _attachedEmails_ list contains at least one item.

      *  The _attachedFiles_ list contains at least one item that does
         not have "Content-Disposition: inline".  The server MAY ignore
         parts in this list that are processed automatically in some
         way, or are referenced as embedded images in one of the "text/
         html" parts of the message.

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

   o  *preview*: "String" (immutable; server-set) Up to 256 characters
      of plain text, summarising the message body.  This is intended to
      be shown as a preview line on a mailbox listing, and may be
      truncated when shown.  The server may choose which part of the
      message to include in the preview, for example skipping quoted
      sections and salutations and collapsing white-space can result in
      a more useful preview.

   MIME structures are arbitrary nested trees of documents, but the
   majority of email clients present a model of an email body (normally
   plain text or HTML), with a set of attachments.  Interpreting the
   MIME structure to form this flat model represents considerable
   difficulty and causes inconsistency between clients.  Therefore in
   addition to the _bodyStructure_ property, which gives the full tree,
   the Email object contains 4 alternate properties with flat lists of
   body parts:

   o  _textBody_/_htmlBody_: These provide a list of parts that should
      be rendered 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 they are transmitted, and
      some clients send text and images intended to be displayed inline
      in the body as multiple parts rather than a single HTML part with
      referenced images.

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

   o  _attachedEmails_/_attachedFiles_: These provide a list of parts
      that should be presented as "attachments" to the message.  Emails
      are presented in a separate list so their contents may be easily
      fetched via a back-reference with the "Email/parse" method in the
      same request, if the client wishes to.  Some images in
      attachedFiles 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_ property allows for clients to fetch the value of
   text parts directly without having to do a second request for the
   blob, and have the server handle decoding the charset into unicode.
   This data is in a separate property rather than on the EmailBodyPart
   object to avoid duplication of large amounts of data, as the same
   part may be included twice if the client fetches more than one of
   bodyStructure, textBody and htmlBody.

   The exact algorithm for decomposing bodyStructure into textBody,
   htmlBody, attachedEmails and attachedFiles 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 parseStructure ( parts, multipartType, inAlternative,
        htmlBody, textBody, attachedEmails, attachedFiles ) {

    // 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" ||
              part.type.startsWith( 'image/' ) ) &&
            // If not the first part and has a filename, assume attachment
            ( i == 0 || !part.name ) &&
            // If multipart/related, only the first part can be inline
            ( i > 0 || multipartType != 'related' );

        if ( isMultipart ) {
            let subMultiType = part.type.split( '/' )[1];
            parseStructure( part.subParts, subMultiType,
                inAlternative || ( subMultiType == 'alternative' ),
                htmlBody, textBody, attachedEmails, attachedFiles );
        } else if ( isInline ) {
            if ( inAlternative && part.type == 'text/plain' ) {
                htmlBody = null;
            }
            if ( inAlternative && part.type == 'text/html' ) {
                textBody = null;
            }
            if ( textBody ) {
                textBody.push( part );
            }
            if ( htmlBody ) {
                htmlBody.push( part );
            }
            if ( ( !textBody || !htmlBody ) &&
                    part.type.startsWith( 'image/' ) ) {
                attachedFiles.push( part );
            }
        } else if ( part.type == 'message/rfc822' ||
                    part.type == 'message/global' ) {
            attachedEmails.push( part );
        } else {
            attachedFiles.push( part );
        }

        if ( multipartType == 'alternative' ) {
            // Found HTML part only
            if ( textBody && textLength == textBody.length &&
                    htmlLength != htmlBody.length ) {
                for ( let i = htmlLength; i < htmlBody.length; i += 1 ) {
                    textBody.push( htmlBody[i] );
                }
            }
            // Found plain text part only
            if ( htmlBody && 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 attachedEmails = [];
let attachedFiles = [];

parseStructure( bodyStructure, 'mixed', false,
    htmlBody, textBody, attachedEmails, attachedFiles );

   For instance, consider a message with both text and html versions
   that's then gone through a list software manager that attaches a
   header/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 ]
                      attachedEmails: [ J ]
                      attachedFiles => [ C, F, G, H ]

4.2.  Email/get

   Standard _/get_ method, with the following additional arguments:

   o  *bodyProperties*: "String[]" (optional) A list of properties to
      fetch for each EmailBodyPart returned.  If omitted, this defaults
      to: [ "partId", "blobId", "size", "name", "type", "charset",
      "disposition", cid", "language", "location" ]

   o  *fetchTextBodyValues*: "Boolean" (default: "false") If "true", the number of bytes
      _bodyValues_ property includes any "text/*" part in the file the user would
      download). "textBody"
      property.

   o  *cid*: "String|null" The id used within  *fetchHTMLBodyValues*: "Boolean" (default: "false") If "true", the message body to
      reference this attachment.  This is only unique when paired with
      _bodyValues_ property includes any "text/*" part in the message id, and has no meaning without reference to that. "htmlBody"
      property.

   o  *isInline*:  *fetchAllBodyValues*: "Boolean" True if (default: "false") If "true", the attachment is referenced
      _bodyValues_ property includes any "text/*" part in the
      "bodyStructure" property.

   o  *maxBodyValueBytes*: "Number" (optional) If supplied by a
      "cid:" link from within the HTML body of
      client, the message.

   o  *width*: "Number|null" (optional, server MAY omit if not
      supported) The width (in px) value MUST be a positive integer greater than 0.  If a
      value outside of this range is given, the image, if server MUST reject the attachment is
      call with an
      image.

   o  *height*: "Number|null" (optional, server MAY omit "invalidArguments" error.  When given, the _value_
      property of any EmailBodyValue object returned in _bodyValues_
      MUST be truncated if necessary so it does not
      supported) The height (in px) exceed this number
      of octets in size.  The server MUST ensure the image, if truncation results
      in valid UTF-8 and does not occur mid-codepoint.  If the attachment part is
      an image.

   To add an attachment,
      of type "text/html", the file must first be uploaded using server SHOULD NOT truncate inside an HTML
      tag.

   If the standard upload mechanism; this will give the client a blobId that
   may be used to identify _properties_ argument is omitted or "null", the file.  The "cid" property may
   following default MUST be assigned
   by the client, and is solely used for matching up with "cid:<id>"
   links inside the "htmlBody". 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", "attachedFiles", "attachedEmails" ]

   The following JMAP methods properties are supported:

4.1.  getMessages

   Standard _getFoos_ method, except the client may use the following
   pseudo values expected to be fast to fetch in the _properties_ argument: a
   quality implementation:

   o  id

   o  blobId
   o  threadId

   o  mailboxIds

   o  keywords

   o  size

   o  receivedAt

   o  messageId

   o  inReplyTo

   o  sender

   o  *body*: If ""body"" is included in the list of requested  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, it MUST be interpreted by the server as a request for
      ""htmlBody"" if there
   may be significantly longer latency in fetching and returning the message has an HTML part, or ""textBody""
      otherwise.

   o  *headers.property*: Instead
   data.

   As specified above, parsed forms of requesting all the headers (by
      requesting the ""headers"" property, the client may specify the
      particular headers it wants using the "headers.property-name"
      syntax, e.g. ""headers.x-spam-score", "headers.x-spam-hits"").
      The server MUST return only be used on
   appropriate header fields.  Attempting to fetch a _headers_ property but with just the
      requested headers in the object rather than all headers.  If
      ""headers"" form that is requested, the server
   forbidden (e.g. "header:From:asDate") MUST ignore result in the individual
      header requests and just return all headers.  If method call
   being rejected with an "invalidArguments" error.

   Where a requested specific header is not present requested as a property, the
   capitalization of the property name in the message, it response MUST NOT be present identical
   to that used in the _headers_ object.  Header names are case-insensitive.

4.1.1. request.

4.2.1.  Example

   Request:

 ["getMessages",

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

   and response:

       ["messages",

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

4.2.  getMessageUpdates

4.3.  Email/changes

   Standard _getFooUpdates_ _/changes_ method.

4.3.  getMessageList

4.4.  Email/query

   Standard _getFooList_ _/query_ method, but with the following additional
   arguments:

   o  *collapseThreads*: "Boolean" (default: "false") If "true",
      messages emails
      in the same thread as a previous message email in the list (given the
      filter and sort order) will be removed from the list.  This means
      at most only one message email will be included in the list
      for any given thread.

4.3.1.  Filtering

   A *FilterOperator* object has the following properties:

   o  *operator*: "String" This MUST be one of the following strings:
      "AND"/"OR"/"NOT":

      *  *AND*: all of the conditions must match for the filter to
         match.

      *  *OR*: at least one of the conditions must match for the filter
         to match.

      *  *NOT*: none of the conditions must match for the filter to
         match.

   o  *conditions*: "(FilterCondition|FilterOperator)[]" The conditions
      to evaluate against each message. in the list for any given
      thread.

4.4.1.  Filtering

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

   o  *inMailbox*: "String" A mailbox id.  A message  An email must be in this
      mailbox to match the condition.

   o  *inMailboxOtherThan*: "String" "String[]" A list of mailbox id.  A message ids.  An email
      must be in any at least one mailbox other than not in this one list to match the
      condition.  This is to allow messages solely in trash/spam to be
      easily excluded from a search.

   o  *before*: "UTCDate" The _receivedAt_ date of the message (as
      returned on the Message object) email must be
      before this date to match the condition.

   o  *after*: "UTCDate" The _receivedAt_ date of the message (as
      returned on the Message object) email must be on
      or after this date to match the condition.

   o  *minSize*: "Number" The size _size_ of the message email in bytes (as returned
      on the Message object) octets must be
      equal to or greater than this number to match the condition.

   o  *maxSize*: "Number" The size of the message email in bytes (as returned
      on the Message object) octets must be less
      than this number to match the condition.

   o  *allInThreadHaveKeyword*: "String" All messages emails (including this one)
      in the same thread as this message email must have the given keyword to
      match the condition.

   o  *someInThreadHaveKeyword*: "String" At least one message email (possibly
      this one) in the same thread as this message email must have the given
      keyword to match the condition.

   o  *noneInThreadHaveKeyword*: "String" All messages emails (including this
      one) in the same thread as this message email must *not* have the given
      keyword to match the condition.

   o  *hasKeyword*: "String" This message email must have the given keyword to
      match the condition.

   o  *notKeyword*: "String" This message email must not have the given keyword
      to match the condition.

   o  *hasAttachment*: "Boolean" The "hasAttachment" property of the
      message
      email must be identical to the value given to match the condition.

   o  *text*: "String" Looks for the text in messages. emails.  The server SHOULD
      look up text in the _from_, _to_, _cc_, _bcc_, _subject_,
      _textBody_, _htmlBody_ or _attachments_ properties _subject_ header
      fields of the message. message, and inside any "text/*" or other body parts
      that may converted to text by the server.  The server MAY extend
      the search to any additional textual property.

   o  *from*: "String" Looks for the text in the _from_ property _From_ header field of
      the message.

   o  *to*: "String" Looks for the text in the _to_ property _To_ header field of the
      message.

   o  *cc*: "String" Looks for the text in the _cc_ property _Cc_ header field of the
      message.

   o  *bcc*: "String" Looks for the text in the _bcc_ property _Bcc_ header field of
      the message.

   o  *subject*: "String" Looks for the text in the _subject_ property
      of the message. email.

   o  *body*: "String" Looks for the text in one of the _textBody_ or
      _htmlBody_ property "text/*" body
      parts of the message. email.

   o  *attachments*: "String" Looks for the text in the attachments of
      the message. email.  Server MAY handle text extraction when possible for
      the different kinds of media.

   o  *header*: "String[]" The array MUST contain either one or two
      elements.  The first element is the name of the header field to
      match against.  The second (optional) element is the text to look
      for in the header. header field value.  If not supplied, the message
      matches simply if it _has_ a header field of the given name.

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

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

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

   o  When searching inside a "text/html" body part, HTML tags and
      attributes SHOULD be ignored.

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

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

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

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

   o  When searching inside the _htmlBody_ property, HTML tags and
      attributes SHOULD be ignored.

4.3.2.

4.4.2.  Sorting

   The following properties MUST be supported for sorting:

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

   The following properties SHOULD be supported for sorting:

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

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

   o  *to* - This is taken to be either the "name" part of the *first*
      Emailer object, part, or if none
      "null"/empty then the "email" part part, of the *first*
      Emailer EmailAddress
      object (see the definition of the to property in the
      Message object). _to_ property.  If still none, consider the value to
      be the empty string.

   o  *subject* - This is taken to be the base subject of the Message with
      any ignoring any leading "Fwd:"s or "Re:"s (case-insensitive
      match). email, as
      defined in section 2.1 of [RFC5256].

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

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

   o  *allInThreadHaveKeyword:*"keyword"  *allInThreadHaveKeyword* - This value MUST be considered "true"
      for the message email if *all* of the messages emails in the same thread
      (regardless of mailbox) have the keyword. keyword given as the _keyword_
      property on this _Comparator_ object.

   o  *someInThreadHaveKeyword:*"keyword"  *someInThreadHaveKeyword* - This value MUST be considered "true"
      for the message email if *any* of the messages emails in the same thread
      (regardless of mailbox) have the keyword. keyword given as the _keyword_
      property on this _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_ object (see section 1).

   Example sort:

      `[ "someInThreadHaveKeyword:$Flagged desc",

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

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

4.3.3.

4.4.3.  Thread collapsing

   When "collapseThreads == true", then after filtering and sorting the
   message
   email list, the list is further winnowed by removing any messages emails for a
   thread id that has already been seen (when passing through the list
   sequentially).  A thread will therefore only appear *once* in the
   "threadIds" list of the result, at the position of the first
   message email in
   the list that belongs to the thread.

4.3.4.

4.4.4.  Response

   The _messageList_ response has the following additional argument:

   o  *collapseThreads*: "Boolean" The _collapseThreads_ value that was
      used when calculating the message email list for this call.

4.4.  getMessageListUpdates

4.5.  Email/queryChanges

   Standard _getFooListUpdates_ _/queryChanges_ method, with the following additional
   arguments:

   o  *collapseThreads*: "Boolean" (default: "false") The
      _collapseThreads_ argument that was used with _getMessageList_. _Email/query_.

   The _messageListUpdates_ response has the following additional
   arguments: argument:

   o  *collapseThreads*: "Boolean" The _collapseThreads_ value that was
      used when calculating the message email list for this call.

4.5.  setMessages

4.6.  Email/set

   Standard _setFoos_ _/set_ method.  The _setMessages_ _Email/set_ method encompasses:

   o  Creating a draft message

   o  Changing the flags keywords of a message an email (unread/flagged status)

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

   o  Deleting messages
   When emails

   Due to the format of the Email object, when creating an email there
   are a message, the _headers_ property specifies extra
   headers to add in addition number of ways to any based off the parsed properties
   (like _from_/_to_/_subject_). specify headers.  The keys client MUST only contain the
   characters a-z (lower-case only), 0-9 and hyphens.  If NOT supply
   conflicting information (for example, if a header _headers_ property is
   included that conflicts with one of the
   given, no other properties on the
   Message object (e.g. _from_, _date_), the value header field property may be given as these form a
   complete set).  Header fields MUST NOT be specified in the _headers_
   object parsed forms
   that are forbidden for that field.  Creation attempts that violate
   any of this MUST be ignored. rejected with an "invalidProperties" error.

   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. 3.6.4, and a "Date"
   header field in conformance with section 3.6.1.

   Other than making sure it conforms to the correct type, the server
   MUST NOT attempt to validate _from_/_to_/_cc_/_bcc_ (e.g. checking if
   an email address is valid) when creating a message. an email.  This is to ensure draft messages
   drafts can be saved at any point.

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

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

   The following extra _SetError_ types are defined:

   For *create*:

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

   o  "maxQuotaReached": The user has reached a server-defined limit on
      their message storage quota.

   For *create* and *update*:

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

4.6.  importMessages

   o  "tooManyMailboxes": The _importMessages_ change to the email's mailboxes would
      exceed a server-defined maximum.

4.7.  Email/import

   The _Email/import_ method adds [RFC5322] messages to a user's set of messages.
   emails.  The messages must first be uploaded as a file using the
   standard upload mechanism.  It takes the following arguments:

   o  *accountId*: "String|null" The id of the account to use for this
      call.  If "null", defaults to the primary account.

   o  *messages*: "String[MessageImport]"  *emails*: "String[EmailImport]" A map of creation id (client
      specified) to MessageImport EmailImport objects

   A *MessageImport*

   An *EmailImport* object has the following properties:

   o  *blobId*: "String" The id representing of the blob containing the raw [RFC5322] message
      (see the file upload section).
      message.

   o  *mailboxIds* "String[Boolean]" The ids of the mailbox(es) to
      assign this message email to.  At least one mailbox MUST be given.

   o  *keywords*: "String[Boolean]" (default: "{}") The keywords to
      apply to the message. email.

   o  *receivedAt*: "UTCDate" (default: time of import on server) The
      _receivedAt_ date to set on the message. email.

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

   The server MAY forbid two messages email objects with the same exact [RFC5322]
   content, or even just with the same [RFC5322] Message-Id, Message-ID, to coexist
   within an account.  In this case, it should MUST reject attempts to import
   a message
   an email considered a duplicate with an "alreadyExists" SetError.  A
   _messageId_  An
   _emailId_ property of type "String" MUST be included on the error
   object with the id of the existing message. email.

   If the _blobId_, _mailboxIds_, or _keywords_ properties are invalid
   (e.g. missing, wrong type, id not found), the server MUST reject the
   import with an "invalidProperties" SetError.

   If the message email cannot be imported because it would take the account
   over quota, the import should be rejected with a "maxQuotaReached"
   SetError.

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

   The response to _importMessages_ is called _messagesImported_. It has the following arguments:

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

   o  *created*: "String[Message]" "String[Email]" A map of the creation id to an object
      containing the _id_, _blobId_, _threadId_ and _size_ properties
      for each successfully imported Message. Email.

   o  *notCreated*: "String[SetError]" A map of creation id to a
      SetError object for each Message Email that failed to be created.  The
      possible errors are defined above.

   The following errors may be returned instead of the _messageImported_
   response:

   "accountNotFound": Returned if an _accountId_ was explicitly included
   with the request, but it does not correspond to a valid account.

   "accountNotSupportedByMethod": Returned if the _accountId_ given
   corresponds to a valid account, but the account does not support this
   data type.

   "accountReadOnly": Returned if the account has "isReadOnly == true".

   "invalidArguments": Returned if one of the arguments is of the wrong
   type, or otherwise invalid.  A "description" property MAY be present
   on the response object to help debug with an explanation of what the
   problem was.

4.7.  copyMessages

4.8.  Email/copy

   The only way to move messages *between* two different accounts is to
   copy them using the _copyMessages_ _Email/copy_ method, then once the copy has
   succeeded, delete the original.  It  The _onSuccessDestroyOriginal_
   argument allows you to try to do this in one method call, however
   note that the two different actions are not atomic, and so it is
   possible for the copy to succeed but the original not to be destroyed
   for some reason.

   The _Email/copy_ method takes the following arguments:

   o  *fromAccountId*: "String|null" The id of the account to copy
      messages
      emails from.  If "null", defaults to the primary account.

   o  *toAccountId*: "String|null" The id of the account to copy
      messages emails
      to.  If "null", defaults to the primary account.

   o  *messages*: "String[MessageCopy]" A map of _creation id_ primary account.

   o  *create*: "String[EmailCopy]" A map of _creation id_ to an
      EmailCopy object.

   o  *onSuccessDestroyOriginal*: "Boolean" (default: "false") If
      "true", an attempt will be made to destroy the emails that were
      successfully copied: after emitting the _Email/copy_ response, but
      before processing the next method, the server MUST make a single
      call to _Email/set_ to destroy the original of each successfully
      copied message; the output of this is added to the responses as
      normal to a
      MessageCopy object.

   A *MessageCopy* be returned to the client.

   An *EmailCopy* object has the following properties:

   o  *messageId*:  *id*: "String" The id of the message email to be copied in the "from"
      account.

   o  *mailboxIds*: "String[Boolean]" The ids of the mailboxes (in the
      "to" account) to add the copied message email to.  At least one mailbox
      MUST be given.

   o  *keywords*: "String[Boolean]" (default: "{}") The _keywords_
      property for the copy.

   o  *receivedAt*: "UTCDate" (default: _receivedAt_ date of original)
      The _receivedAt_ date to set on the copy.

   The server MAY forbid two messages email objects with the same exact [RFC5322]
   content, or even just with the same [RFC5322] Message-Id, Message-ID, to coexist
   within an account.  If duplicates are allowed though, the "from"
   account may be the same as the "to" account to copy messages emails within an
   account.

   Each message email copy is considered an atomic unit which may succeed or
   fail individually.  Copying successfully MUST create a new message email
   object, with separate ids and mutable properties (e.g. mailboxes and
   keywords) to the original message. email.

   The response has the following arguments:

   o  *fromAccountId*: "String" The id of the account emails were copied
      from.

   o  *toAccountId*: "String" The id of the account emails were copied
      to.

   o  *created*: "String[Email]|null" A map of the creation id to an
      object containing the _id_, _blobId_, _threadId_ and _size_
      properties for each successfully copied Email.

   o  *notCreated*: "String[SetError]|null" A map of creation id to a
      SetError object for each Email that failed to _copyMessages_ be copied, "null" if
      none.

   The *SetError* may be any of the standard set errors that may be
   returned for a _create_. The following extra _SetError_ type is called _messagesCopied_. It has also
   defined:

   "alreadyExists": The server forbids duplicates and the email already
   exists in the target account.  An _emailId_ property of type "String"
   MUST be included on the error object with the id of the existing
   email.

   The following additional errors may be returned instead of the
   _Email/copy_ response:

   "fromAccountNotFound": A _fromAccountId_ was explicitly included with
   the request, but it does not correspond to a valid account.

   "toAccountNotFound": A _toAccountId_ was explicitly included with the
   request, but it does not correspond to a valid account.

   "fromAccountNotSupportedByMethod": The _fromAccountId_ given
   corresponds to a valid account, but does not contain any mail data.

   "toAccountNotSupportedByMethod": The _toAccountId_ given corresponds
   to a valid account, but does not contain any mail data.

4.9.  Email/parse

   This method allows you to parse blobs as [RFC5322] messages to get
   Email objects (excluding the metadata properties).

   The _Email/parse_ method takes the following arguments:

   o  *fromAccountId*: "String"  *accountId*: "String|null" The id of the account messages were
      copied from.

   o  *toAccountId*: "String" The id of Account to use.  If
      "null", the primary account messages were copied
      to. is used.

   o  *created*: "String[Message]|null" A map  *blobIds*: "String[]" The ids of the creation id blobs to an
      object containing parse.

   o  *properties*: "String[]" If supplied, only the _id_, _blobId_, _threadId_ and _size_ properties listed
      in the array are returned for each successfully copied Message. Email object.  If omitted,
      defaults to the same value as the Email/get "properties" default
      argument.

   o  *notCreated*: "String[SetError]|null"  *bodyProperties*: "String[]" (optional) A map list of creation id properties to a
      SetError object
      fetch for each Message that failed EmailBodyPart returned.  If omitted, defaults to be copied, "null"
      if none.

   The *SetError* may be one of
      the following types:

   "alreadyExists": Returned if same value as the server forbids duplicates and Email/get "bodyProperties" default argument.

   o  *fetchTextBodyValues*: "Boolean" (default: "false") If "true", the
   message already exists
      _bodyValues_ property includes any "text/*" part in the target account.  A _messageId_ "textBody"
      property.

   o  *fetchHTMLBodyValues*: "Boolean" (default: "false") If "true", the
      _bodyValues_ property
   of type "String" includes any "text/*" part in the "htmlBody"
      property.

   o  *fetchAllBodyValues*: "Boolean" (default: "false") If "true", the
      _bodyValues_ property includes any "text/*" part in the
      "bodyStructure" property.

   o  *maxBodyValueBytes*: "Number" (optional) If supplied by the
      client, the value MUST be included on a positive integer greater than 0.  If a
      value outside of this range is given, the error object server MUST reject the
      call with an "invalidArguments" error.  When given, the id _value_
      property of
   the existing message.

   "notFound": Returned if the _messageId_ given can't any EmailBodyValue object returned in _bodyValues_
      MUST be found.

   "invalidProperties": Returned truncated if necessary so it does not exceed this number
      of octets in size.  The server MUST ensure the _mailboxIds_ or _keywords_
   properties are invalid (e.g. missing, wrong type, id truncation results
      in valid UTF-8 and does not found).

   "maxQuotaReached": Returned if occur mid-codepoint.  If the user has reached their mail quota
   so part is
      of type "text/html", the message cannot be copied. server SHOULD NOT truncate inside an HTML
      tag.

   The response has the following errors may be returned instead arguments:

   o  *accountId*: "String" The id of the _messagesCopied_
   response:

   "fromAccountNotFound": Returned if a _fromAccountId_ was explicitly
   included with the request, but it does not correspond to a valid
   account.

   "toAccountNotFound": Returned if a _toAccountId_ was explicitly
   included with account used for the request, but it does not correspond call.

   o  *parsed*: "String[Email]|null" A map of blob id to a valid
   account.

   "fromAccountNoMail": Returned parsed Email
      representation for each successfully parsed blob, or "null" if the _fromAccountId_
      none.

   o  *notParsable*: "String[]|null" A list of ids given
   corresponds that
      corresponded to a valid account, but does blobs that could not contain any mail data.

   "toAccountNoMail": Returned be parsed as emails, or
      "null" if the _toAccountId_ none.

   o  *notFound*: "String[]|null" A list of blob ids given corresponds to
   a valid account, but does that could
      not contain any mail data.

   "accountReadOnly": Returned if the "to" account has "isReadOnly ==
   true".

   "invalidArguments": Returned be found, or "null" if one none.

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

   Where a specific header is requested as a property, the
   capitalization of the wrong
   type, or otherwise invalid.  A "description" property MAY be present
   on name in the response object MUST be identical
   to help debug with an explanation of what that used in the
   problem was. request.

5.  MessageSubmission

   The MessageSubmission  Email submission

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

   o  *id*: "String" (immutable; server-set) The id of the message email
      submission.

   o  *identityId*: "String" (immutable) The id of the identity to
      associate with this submission.

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

   o  *threadId*: "String" (immutable; server-set) The thread id of the
      message
      email to send.  This is set by the server to the _threadId_
      property of the message email referenced by the _messageId_. _emailId_.

   o  *envelope*: "Envelope|null" (immutable; default: "null")
      Information for use when sending via SMTP.  An *Envelope* object
      has the following properties:

      *  *mailFrom*: "Address" The email address to use as the return
         address in the SMTP submission, plus any parameters to pass
         with the MAIL FROM address.  The JMAP server MAY allow the
         email
         address to be the empty string.  When a JMAP server performs a an
         SMTP message submission, it MAY use the same id string for the

         [RFC3461] ENVID parameter and the MessageSubmission EmailSubmission object id.
         Servers that do this MAY replace a client-provided value for
         ENVID with a server-provided value.

      *  *rcptTo*: "Address[]" The email addresses to send the message
         to, and any RCPT TO parameters to pass with the recipient.

      An *Address* object has the following properties:

      *  *email*: "String" The email address being represented by the
         object.  This as a "Mailbox" as used in the Reverse-path or
         Foward-path of the MAIL FROM or RCPT TO command in [@!RFC5321 [RFC5321].

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

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

      *  *mailFrom*: The email in the _Sender_ header, if present,
         otherwise the _From_ header, if present, and no parameters.  If
         multiple addresses are present in one of these headers, or
         there is more than one _Sender_/_From_ header, the server
         SHOULD reject the message email as invalid but otherwise MUST take the
         first email address in the last _Sender_/_From_ header in the
         [RFC5322] version of the message.  If the address found from
         this is not allowed by the identity associated with this
         submission, the _email_ property from the identity MUST be used
         instead.

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

   o  *sendAt*: "UTCDate" (immutable; server-set) The date the message email
      was/will be released for delivery.  If the client successfully
      used [RFC4865] FUTURERELEASE with the message, email, this MUST be the time
      when the server will release the message; email; otherwise it MUST be the
      time the MessageSubmission EmailSubmission was created.

   o  *undoStatus*: "String" (server-set) This represents whether the
      submission may be canceled.  This is server set and MUST be one of
      the following values:

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

      *  "final": The message email 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 message 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", and MAY
      transition to "final" when the server knows it definitely cannot
      recall the message, email, but MAY just remain "pending".  If in pending
      state, a client can attempt to cancel the submission by setting
      this property to "canceled"; if the update succeeds, the
      submission was successfully canceled and the message email has not been
      delivered to any of the original recipients.

   o  *deliveryStatus*: "String[DeliveryStatus]|null" (server-set) This
      represents the delivery status for each of the message email's recipients,
      if known.  This property MAY not be supported by all servers, in
      which case it will remain "null".  Servers that support it SHOULD
      update the MessageSubmission EmailSubmission object each time the status of any of
      the recipients changes, even if some recipients are still being
      retried.  This value is a map from the email address of each
      recipient to a _DeliveryStatus_ object.  A *DeliveryStatus* object
      has the following properties:

      *  *smtpReply*: "String" The SMTP reply string returned for this
         recipient when the server last tried to relay the message, email, or in
         a later DSN response for the message. email.  This SHOULD be the
         response to the RCPT TO stage, unless this was accepted and the
         message
         email as a whole 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, sorry.

         would become:

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

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

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

         +  Then a single space character.

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

         +  Then a single space character.

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

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

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

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

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

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

         Note, successful relaying to an external SMTP server SHOULD NOT
         be taken as an indication that the message email has successfully
         reached the final mailbox.  In this case though, the server MAY
         receive a DSN response, if requested.  If a DSN is received for
         the recipient with Action equal to "delivered", as per
         [RFC3464] section 2.3.3, then the _delivered_ property SHOULD
         be set to "yes"; if the Action equals "failed", the property
         SHOULD be set to "no".  Receipt of any other DSN SHOULD NOT
         affect this property.  The server MAY also set this property
         based on other feedback channels.

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

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

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

         If an MDN is received for this recipient with Disposition-Type
         (as per [RFC3798] 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*: "String[]" (server-set) A list of blob ids for DSNs
      received for this submission, in order of receipt, oldest first.

   o  *mdnBlobIds*: "String[]" (server-set) A list of blob ids for MDNs
      received for this submission, in order of receipt, oldest first.

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

   For efficiency, a server MAY destroy MessageSubmission EmailSubmission objects a
   certain amount of time after the message email is successfully sent or it has
   finished retrying sending the message. email.  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:

5.1.  getMessageSubmissions  EmailSubmission/get

   Standard _getFoos_ _/get_ method.

5.2.  getMessageSubmissionUpdates  EmailSubmission/changes

   Standard _getFooUpdates_ _/changes_ method.

5.3.  getMessageSubmissionList  EmailSubmission/query

   Standard _getFooList_ _/query_ method.

   The

   A *FilterCondition* object (optionally passed as the _filter_
   argument) has the following properties, any of which
   may be omitted:

   o  *messageIds*:  *emailIds*: "String[]" The MessageSubmission _messageId_ EmailSubmission _emailId_ property must
      be in this list to match the condition.

   o  *threadIds*: "String[]" The MessageSubmission EmailSubmission _threadId_ property
      must be in this list to match the condition.

   o  *undoStatus*: "String" The MessageSubmission EmailSubmission _undoStatus_ property
      must be identical to the value given to match the condition.

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

   o  *after*: "UTCDate" The _sendAt_ property of the MessageSubmission EmailSubmission
      object must be after this date to match the condition.

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

   The following properties MUST be supported for sorting:

   o  "messageId"  "emailId"

   o  "threadId"

   o  "sentAt"

5.4.  getMessageSubmissionListUpdates  EmailSubmission/queryChanges

   Standard _getFooListUpdates_ _/queryChanges_ method.

5.5.  setMessageSubmissions  EmailSubmission/set

   Standard _setFoos_ _/set_ method, with the following two extra arguments:

   o  *onSuccessUpdateMessage*: "String[Message]|null"  *onSuccessUpdateEmail*: "String[Email]|null" A map of
      _MessageSubmission
      _EmailSubmission id_ to an object containing properties to update
      on the Message Email object referenced by the MessageSubmission EmailSubmission if the
      create/update/destroy succeeds.  (For references to
      MessageSubmission
      EmailSubmission creations, this is equivalent to a back reference
      so the id will be the creation id prefixed with a "#".)

   o  *onSuccessDestroyMessage*:  *onSuccessDestroyEmail*: "String[]|null" A list of
      _MessageSubmission
      _EmailSubmission ids_ for which the message email with the corresponding messageId
      emailId should be destroyed if the create/update/
      destroy create/update/destroy succeeds.
      (For references to MessageSubmission EmailSubmission creations, this is equivalent
      to a back reference so the id will be the creation id prefixed
      with a "#".)

   A single implicit _setMessages_ _Email/set_ call MUST be made after all
   MessageSubmission
   EmailSubmission create/update/destroy requests have been processed to
   perform any changes requested in these two arguments.  The
   _messagesSet_ response
   to this MUST be returned after the
   _messageSubmissionsSet_ _EmailSubmission/set_ response.

   A message

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

   If the referenced message email is destroyed at any point after the
   MessageSubmission
   EmailSubmission object is created, this MUST NOT change the behaviour
   of the message email submission (i.e. it does not cancel a future send).

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

   The following extra _SetError_ types are defined:

   For *create*:

   o  "tooLarge" - The message email size is larger than the server supports. supports
      sending.  A _maxSize_ "Number" property MUST be present on the
      SetError specifying the maximum size of a message an email that may be sent,
      in
      bytes. octets.

   o  "tooManyRecipients" - The envelope (supplied or generated) has
      more recipients than the server allows.  A _maxRecipients_
      "Number" property MUST 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.

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

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

   o  "notPermittedToSend"  "forbiddenToSend" - The user does not have permission to send at
      all right now for some reason.  A _description_ "String" property
      MAY be present on the SetError object to display to the user why
      they are not permitted.  The server MAY choose to localise this
      string into the user's preferred language, if known.

   o  "messageNotFound"  "emailNotFound" - The _messageId_ _emailId_ is not a valid id for a
      message an email in
      the account.

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

   For *update*:

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

   For *destroy*:

   o  "forbidden": The server does not allow clients to destroy
      MessageSubmission objects.

6.  Identities

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

   o  *id*: "String" (immutable; server-set) The id of the identity.

   o  *name*: "String" (default: """") The "From" _name_ the client
      SHOULD use when creating a new message from this identity.

   o  *email*: "String" The "From" email address the client MUST use
      when creating a new message from this identity.  This property is
      immutable.  The "email" property MAY alternatively be of the form
      "*@example.com", in which case the client may use any valid email
      address ending in "@example.com".

   o  *replyTo*: "Emailer[]|null" (default: "null") The Reply-To value
      the client SHOULD set when creating a new message from this
      identity.

   o  *bcc*: "Emailer[]|null" (default: "null") The Bcc value the client
      SHOULD set when creating a new message from this identity.

   o  *textSignature*: "String" (default: """") Signature the client
      SHOULD insert into new plain-text messages that will be sent from
      this identity.  Clients MAY ignore this and/or combine this with a
      client-specific signature preference.

   o  *htmlSignature*: "String" (default: """") Signature the client
      SHOULD insert into new HTML messages that will be sent from this
      identity.  This text MUST be an HTML snippet to be inserted into
      the "<body></body>" section of the new email.  Clients MAY ignore
      this and/or combine this with a client-specific signature
      preference.

   o  *mayDelete*: "Boolean" (server-set) Is the user allowed to delete
      this identity?  Servers may wish to set this to "false" for the
      user's username or other default address.

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

   The following JMAP methods are supported:

6.1.  getIdentities  Identity/get

   Standard _getFoos_ _/get_ method.  The _ids_ argument may be "null" to fetch
   all at once.

6.2.  getIdentityUpdates  Identity/changes

   Standard _getFooUpdates_ _/changes_ method.

6.3.  setIdentities  Identity/set

   Standard _setFoos_ _/set_ method.  The following extra _SetError_ types are
   defined:

   For *create*:

   o  "maxQuotaReached": The user has reached a server-defined limit on
      the number of identities.

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

   For *destroy*:

   o  "forbidden": Returned if the identity's _mayDelete_ value is
      "false".

7.  SearchSnippets  Search snippets

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

   A *SearchSnippet* object has the following properties:

   o  *messageId*:  *emailId*: "String" The message email id the snippet applies to.

   o  *subject*: "String|null" If text from the filter matches the
      subject, this is the subject of the message email HTML-escaped, with
      matching words/phrases wrapped in "<mark></mark>" tags.  If it
      does not match, this is "null".

   o  *preview*: "String|null" If text from the filter matches the
      plain-text or HTML body, this is the relevant section of the body
      (converted to plain text if originally HTML), HTML-escaped, with
      matching words/phrases wrapped in "<mark></mark>" tags, up to 256
      characters long.  If it does not match, this is "null".

   o  *attachments*: "String|null" If text from the filter matches the
      text extracted from an attachment, this is the relevant section of
      the attachment (converted to plain text), with matching words/
      phrases wrapped in "<mark></mark>" tags, up to 256 characters
      long.  If it does not match, this is "null".

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

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

   The following JMAP method is supported:

7.1.  getSearchSnippets  SearchSnippet/get

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

   o  *accountId*: "String|null" The id of the account to use for this
      call.  If "null", defaults to the primary account.

   o  *messageIds*:  *emailIds*: "String[]" The list of ids of messages emails to fetch the
      snippets for.

   o  *filter*: "FilterCondition|FilterOperator|null" "FilterOperator|FilterCondition|null" The same filter as
      passed to getMessageList; Email/query; see the description of this method for
      details.

   The response to "getSearchSnippets" is called "searchSnippets".  It has the following arguments:

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

   o  *filter*: "FilterCondition|FilterOperator|null" "FilterOperator|FilterCondition|null" Echoed back from
      the call.

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

   o  *notFound*: "String[]|null" An array of message email ids requested which
      could not be found, or "null" if all ids were found.

   Since snippets are only based on immutable properties, there is no
   state string or update mechanism needed.

   The following additional errors may be returned instead of the
   _searchSnippets_ response:

   "accountNotFound": Returned if an _accountId_ was explicitly included
   with the request, but it does not correspond to a valid account.

   "accountNotSupportedByMethod": Returned if the _accountId_ given
   corresponds to a valid account, but the account does not support this
   data type.

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

   "cannotDoFilter":

   "unsupportedFilter": Returned if the server is unable to process the
   given _filter_ for any reason.

   "invalidArguments": Returned if the request does not include one of
   the required arguments, or one of the arguments is of the wrong type,
   or otherwise invalid.  A "description" property MAY be present on the
   response object to help debug with an explanation of what the problem
   was.

8.  Vacation Response response

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

   o  *id*: "String" (immutable) The id of the object.  There is only
      ever one vacation response object, and its id is ""singleton"".

   o  *isEnabled* "Boolean" Should a vacation response be sent if a
      message an
      email arrives between the _fromDate_ and _toDate_?

   o  *fromDate*: "UTCDate|null" If _isEnabled_ is "true", the date/time
      in UTC after which messages emails that arrive should receive the user's
      vacation response, in UTC. response.  If "null", the vacation response is effective
      immediately.

   o  *toDate*: "UTCDate|null" If _isEnabled_ is "true", the date/time
      in UTC after which messages emails that arrive should no longer receive the
      user's vacation response, in UTC. response.  If "null", the vacation response is
      effective indefinitely.

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

   o  *textBody*: "String|null" The plain text part of the message to
      send in response to messages emails when the vacation response is enabled.
      If this is "null", when the vacation message is sent a plain-text
      body part SHOULD be generated from the _htmlBody_ but the server
      MAY choose to send the response as HTML only.

   o  *htmlBody*: "String|null" The HTML message to send in response to
      messages
      emails when the vacation response is enabled.  If this is "null",
      when the vacation message is sent an HTML body part MAY be
      generated from the _textBody_, or the server MAY choose to send
      the response as plain-text only.

   The following JMAP methods are supported:

8.1.  getVacationResponse  VacationResponse/get

   Standard _getFoos_ _/get_ method.

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

8.2.  setVacationResponse

   Standard _setFoos_ method.  The following extra _SetError_ types are
   defined:

   For *create* or *destroy*:

   o  "singleton": This is a singleton object, so you cannot create
      another one or destroy have the existing one. id ""singleton"".

8.2.  VacationResponse/set

   Standard _/set_ method.

9.  Security considerations

   All security considerations of JMAP {TODO: insert RFC ref} apply to
   this specification.

9.1.  EmailBodyPart value

   Service providers typically perform security filtering on incoming
   email and it's important 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_ 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 host.

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

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

10.  References

10.1.  Normative References

   [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>.

   [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>.

   [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
              Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
              <https://www.rfc-editor.org/info/rfc3339>.

   [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>.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
              2003, <https://www.rfc-editor.org/info/rfc3629>.

   [RFC3798]  Hansen, T., Ed. and G. Vaudreuil, Ed., "Message
              Disposition Notification", RFC 3798, DOI 10.17487/RFC3798,
              May 2004, <https://www.rfc-editor.org/info/rfc3798>.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
              <https://www.rfc-editor.org/info/rfc4648>.

   [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>.

   [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>.

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <https://www.rfc-editor.org/info/rfc7159>.

   [RFC7493]  Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
              DOI 10.17487/RFC7493, March 2015,
              <https://www.rfc-editor.org/info/rfc7493>.

10.2.  URIs

   [1] server.html TODO

   [2] server.html

   [3] https://www.iana.org/assignments/imap-keywords/imap-
       keywords.xhtml

Author's Address

   Neil Jenkins
   FastMail
   Level 2, 114 William St
   Melbourne  VIC 3000
   Australia

   Email: neilj@fastmailteam.com
   URI:   https://www.fastmail.com