Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8621

The JSON Meta Application Protocol (JMAP) for Mail

Pages: 108
Proposed Standard
Updates:  5788
Part 2 of 5 – Pages 22 to 45
First   Prev   Next

Top   ToC   RFC8621 - Page 22   prevText

4. Emails

An *Email* object is a representation of a message [RFC5322], which allows clients to avoid the complexities of MIME parsing, transfer encoding, and character encoding.
Top   ToC   RFC8621 - Page 23

4.1. Properties of the Email Object

Broadly, a message consists of two parts: a list of header fields and then a body. The Email data type provides a way to access the full structure or to use simplified properties and avoid some complexity if this is sufficient for the client application. While raw headers can be fetched and set, the vast majority of clients should use an appropriate parsed form for each of the header fields it wants to process, as this allows it to avoid the complexities of various encodings that are required in a valid message per RFC 5322. The body of a message is normally a MIME-encoded set of documents in a tree structure. This may be arbitrarily nested, but the majority of email clients present a flat model of a message body (normally plaintext or HTML) with a set of attachments. Flattening the MIME structure to form this model can be difficult and causes inconsistency between clients. Therefore, in addition to the "bodyStructure" property, which gives the full tree, the Email object contains 3 alternate properties with flat lists of body parts: o "textBody"/"htmlBody": These provide a list of parts that should be rendered sequentially as the "body" of the message. This is a list rather than a single part as messages may have headers and/or footers appended/prepended as separate parts when they are transmitted, and some clients send text and images intended to be displayed inline in the body (or even videos and sound clips) as multiple parts rather than a single HTML part with referenced images. Because MIME allows for multiple representations of the same data (using "multipart/alternative"), there is a "textBody" property (which prefers a plaintext representation) and an "htmlBody" property (which prefers an HTML representation) to accommodate the two most common client requirements. The same part may appear in both lists where there is no alternative between the two. o "attachments": This provides a list of parts that should be presented as "attachments" to the message. Some images may be solely there for embedding within an HTML body part; clients may wish to not present these as attachments in the user interface if they are displaying the HTML with the embedded images directly. Some parts may also be in htmlBody/textBody; again, clients may wish to not present these as attachments in the user interface if rendered as part of the body.
Top   ToC   RFC8621 - Page 24
   The "bodyValues" property allows for clients to fetch the value of
   text parts directly without having to do a second request for the
   blob and to have the server handle decoding the charset into unicode.
   This data is in a separate property rather than on the EmailBodyPart
   object to avoid duplication of large amounts of data, as the same
   part may be included twice if the client fetches more than one of
   bodyStructure, textBody, and htmlBody.

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

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

4.1.1. Metadata

These properties represent metadata about the message in the mail store and are not derived from parsing the message itself. o id: "Id" (immutable; server-set) The id of the Email object. Note that this is the JMAP object id, NOT the Message-ID header field value of the message [RFC5322]. o blobId: "Id" (immutable; server-set) The id representing the raw octets of the message [RFC5322] for this Email. This may be used to download the raw original message or to attach it directly to another Email, etc. o threadId: "Id" (immutable; server-set) The id of the Thread to which this Email belongs. o mailboxIds: "Id[Boolean]" The set of Mailbox ids this Email belongs to. An Email in the mail store MUST belong to one or more Mailboxes at all times (until it is destroyed). The set is represented as an object, with each key being a Mailbox id. The value for each key in the object MUST be true.
Top   ToC   RFC8621 - Page 25
   o  keywords: "String[Boolean]" (default: {})

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

      Keywords are shared with IMAP.  The six system keywords from IMAP
      get special treatment.  The following four keywords have their
      first character changed from "\" in IMAP to "$" in JMAP and have
      particular semantic meaning:

      *  "$draft": The Email is a draft the user is composing.

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

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

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

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

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

                              ( ) { ] % * " \

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

      The IANA "IMAP and JMAP Keywords" registry at
      <https://www.iana.org/assignments/imap-jmap-keywords/> as
      established in [RFC5788] assigns semantic meaning to some other
      keywords in common use.  New keywords may be established here in
      the future.  In particular, note:

      *  "$forwarded": The Email has been forwarded.

      *  "$phishing": The Email is highly likely to be phishing.
         Clients SHOULD warn users to take care when viewing this Email
         and disable links and attachments.
Top   ToC   RFC8621 - Page 26
      *  "$junk": The Email is definitely spam.  Clients SHOULD set this
         flag when users report spam to help train automated spam-
         detection systems.

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

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

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

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

      The date the Email was received by the message store.  This is the
      "internal date" in IMAP [RFC3501].

4.1.2. Header Fields Parsed Forms

Header field properties are derived from the message header fields [RFC5322] [RFC6532]. All header fields may be fetched in a raw form. Some header fields may also be fetched in a parsed form. The structured form that may be fetched depends on the header. The forms are defined in the subsections that follow.
4.1.2.1. Raw
Type: "String" The raw octets of the header field value from the first octet following the header field name terminating colon, up to but excluding the header field terminating CRLF. Any standards-compliant message MUST be either ASCII (RFC 5322) or UTF-8 (RFC 6532); however, other encodings exist in the wild. A server SHOULD replace any octet or octet run with the high bit set that violates UTF-8 syntax with the unicode replacement character (U+FFFD). Any NUL octet MUST be dropped. This form will typically have a leading space, as most generated messages insert a space after the colon that terminates the header field name.
Top   ToC   RFC8621 - Page 27
4.1.2.2. Text
Type: "String" The header field value with: 1. White space unfolded (as defined in [RFC5322], Section 2.2.3). 2. The terminating CRLF at the end of the value removed. 3. Any SP characters at the beginning of the value removed. 4. Any syntactically correct encoded sections [RFC2047] with a known character set decoded. Any NUL octets or control characters encoded per [RFC2047] are dropped from the decoded value. Any text that looks like syntax per [RFC2047] but violates placement or white space rules per [RFC2047] MUST NOT be decoded. 5. The resulting unicode converted to Normalization Form C (NFC) form. If any decodings fail, the parser SHOULD insert a unicode replacement character (U+FFFD) and attempt to continue as much as possible. To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields: o Subject o Comments o Keywords o List-Id o Any header field not defined in [RFC5322] or [RFC2369]
4.1.2.3. Addresses
Type: "EmailAddress[]" The header field is parsed as an "address-list" value, as specified in [RFC5322], Section 3.4, into the "EmailAddress[]" type. There is an EmailAddress item for each "mailbox" parsed from the "address- list". Group and comment information is discarded.
Top   ToC   RFC8621 - Page 28
   An *EmailAddress* object has the following properties:

   o  name: "String|null"

      The "display-name" of the "mailbox" [RFC5322].  If this is a
      "quoted-string":

      1.  The surrounding DQUOTE characters are removed.

      2.  Any "quoted-pair" is decoded.

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

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

   o  email: "String"

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

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

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

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

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

   would be parsed as:

        [
          { "name": "James Smythe", "email": "james@example.com" },
          { "name": null, "email": "jane@example.com" },
          { "name": "John Smith", "email": "john@example.com" }
        ]
Top   ToC   RFC8621 - Page 29
   To prevent obviously nonsense behaviour, which can lead to
   interoperability issues, this form may only be fetched or set for the
   following header fields:

   o  From

   o  Sender

   o  Reply-To

   o  To

   o  Cc

   o  Bcc

   o  Resent-From

   o  Resent-Sender

   o  Resent-Reply-To

   o  Resent-To

   o  Resent-Cc

   o  Resent-Bcc

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

4.1.2.4. GroupedAddresses
Type: "EmailAddressGroup[]" This is similar to the Addresses form but preserves group information. The header field is parsed as an "address-list" value, as specified in [RFC5322], Section 3.4, into the "GroupedAddresses[]" type. Consecutive "mailbox" values that are not part of a group are still collected under an EmailAddressGroup object to provide a uniform type.
Top   ToC   RFC8621 - Page 30
   An *EmailAddressGroup* object has the following properties:

   o  name: "String|null"

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

   o  addresses: "EmailAddress[]"

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

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

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

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

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

   would be parsed as:

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

   To prevent obviously nonsense behaviour, which can lead to
   interoperability issues, this form may only be fetched or set for the
   same header fields as the Addresses form (see Section 4.1.2.3).
Top   ToC   RFC8621 - Page 31
4.1.2.5. MessageIds
Type: "String[]|null" The header field is parsed as a list of "msg-id" values, as specified in [RFC5322], Section 3.6.4, into the "String[]" type. Comments and/ or folding white space (CFWS) and surrounding angle brackets ("<>") are removed. If parsing fails, the value is null. To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields: o Message-ID o In-Reply-To o References o Resent-Message-ID o Any header field not defined in [RFC5322] or [RFC2369]
4.1.2.6. Date
Type: "Date|null" The header field is parsed as a "date-time" value, as specified in [RFC5322], Section 3.3, into the "Date" type. If parsing fails, the value is null. To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields: o Date o Resent-Date o Any header field not defined in [RFC5322] or [RFC2369]
Top   ToC   RFC8621 - Page 32
4.1.2.7. URLs
Type: "String[]|null" The header field is parsed as a list of URLs, as described in [RFC2369], into the "String[]" type. Values do not include the surrounding angle brackets or any comments in the header field with the URLs. If parsing fails, the value is null. To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields: o List-Help o List-Unsubscribe o List-Subscribe o List-Post o List-Owner o List-Archive o Any header field not defined in [RFC5322] or [RFC2369]

4.1.3. Header Fields Properties

The following low-level Email property is specified for complete access to the header data of the message: o headers: "EmailHeader[]" (immutable) This is a list of all header fields [RFC5322], in the same order they appear in the message. An *EmailHeader* object has the following properties: * name: "String" The header "field name" as defined in [RFC5322], with the same capitalization that it has in the message. * value: "String" The header "field value" as defined in [RFC5322], in Raw form.
Top   ToC   RFC8621 - Page 33
   In addition, the client may request/send properties representing
   individual header fields of the form:

                        header:{header-field-name}

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

   o  :as{header-form}

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

   o  :all

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

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

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

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

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

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

   3.  The result is of type "EmailAddress[][]" -- each item in the
       array corresponds to the parsed value (which is itself an array)
       of the Resent-To header field instance.
Top   ToC   RFC8621 - Page 34
   The following convenience properties are also specified for the Email
   object:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   o  subject: "String|null" (immutable)

      The value is identical to the value of "header:Subject:asText".
Top   ToC   RFC8621 - Page 35
   o  sentAt: "Date|null" (immutable; default on creation: current
      server time)

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

4.1.4. Body Parts

These properties are derived from the message body [RFC5322] and its MIME entities [RFC2045]. An *EmailBodyPart* object has the following properties: o partId: "String|null" Identifies this part uniquely within the Email. This is scoped to the "emailId" and has no meaning outside of the JMAP Email object representation. This is null if, and only if, the part is of type "multipart/*". o blobId: "Id|null" The id representing the raw octets of the contents of the part, after decoding any known Content-Transfer-Encoding (as defined in [RFC2045]), or null if, and only if, the part is of type "multipart/*". Note that two parts may be transfer-encoded differently but have the same blob id if their decoded octets are identical and the server is using a secure hash of the data for the blob id. If the transfer encoding is unknown, it is treated as though it had no transfer encoding. o size: "UnsignedInt" The size, in octets, of the raw data after content transfer decoding (as referenced by the "blobId", i.e., the number of octets in the file the user would download). o headers: "EmailHeader[]" This is a list of all header fields in the part, in the order they appear in the message. The values are in Raw form. o name: "String|null" This is the decoded "filename" parameter of the Content- Disposition header field per [RFC2231], or (for compatibility with existing systems) if not present, then it's the decoded "name" parameter of the Content-Type header field per [RFC2047].
Top   ToC   RFC8621 - Page 36
   o  type: "String"

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

   o  charset: "String|null"

      The value of the charset parameter of the Content-Type header
      field, if present, or null if the header field is present but not
      of type "text/*".  If there is no Content-Type header field, or it
      exists and is of type "text/*" but has no charset parameter, this
      is the implicit charset as per the MIME standard: "us-ascii".

   o  disposition: "String|null"

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

   o  cid: "String|null"

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

   o  language: "String[]|null"

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

   o  location: "String|null"

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

   o  subParts: "EmailBodyPart[]|null"

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

   In addition, the client may request/send EmailBodyPart properties
   representing individual header fields, following the same syntax and
   semantics as for the Email object, e.g., "header:Content-Type".
Top   ToC   RFC8621 - Page 37
   The following Email properties are specified for access to the body
   data of the message:

   o  bodyStructure: "EmailBodyPart" (immutable)

      This is the full MIME structure of the message body, without
      recursing into "message/rfc822" or "message/global" parts.  Note
      that EmailBodyParts may have subParts if they are of type
      "multipart/*".

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

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

      *  value: "String"

         The value of the body part after decoding Content-Transfer-
         Encoding and the Content-Type charset, if both known to the
         server, and with any CRLF replaced with a single LF.  The
         server MAY use heuristics to determine the charset to use for
         decoding if the charset is unknown, no charset is given, or it
         believes the charset given is incorrect.  Decoding is best
         effort; the server SHOULD insert the unicode replacement
         character (U+FFFD) and continue when a malformed section is
         encountered.

         Note that due to the charset decoding and line ending
         normalisation, the length of this string will probably not be
         exactly the same as the "size" property on the corresponding
         EmailBodyPart.

      *  isEncodingProblem: "Boolean" (default: false)

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

      *  isTruncated: "Boolean" (default: false)

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

      See the Security Considerations section for issues related to
      truncation and heuristic determination of the content-type and
      charset.
Top   ToC   RFC8621 - Page 38
   o  textBody: "EmailBodyPart[]" (immutable)

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

   o  htmlBody: "EmailBodyPart[]" (immutable)

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

   o  attachments: "EmailBodyPart[]" (immutable)

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

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

      *  of type "image/*", "audio/*", or "video/*" and not in both
         "textBody" and "htmlBody"

      None of these parts include subParts, including "message/*" types.
      Attached messages may be fetched using the "Email/parse" method
      and the "blobId".

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

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

      This is true if there are one or more parts in the message that a
      client UI should offer as downloadable.  A server SHOULD set
      hasAttachment to true if the "attachments" list contains at least
      one item that does not have "Content-Disposition: inline".  The
      server MAY ignore parts in this list that are processed
      automatically in some way or are referenced as embedded images in
      one of the "text/html" parts of the message.

      The server MAY set hasAttachment based on implementation-defined
      or site-configurable heuristics.
Top   ToC   RFC8621 - Page 39
   o  preview: "String" (immutable; server-set)

      A plaintext fragment of the message body.  This is intended to be
      shown as a preview line when listing messages in the mail store
      and may be truncated when shown.  The server may choose which part
      of the message to include in the preview; skipping quoted sections
      and salutations and collapsing white space can result in a more
      useful preview.

      This MUST NOT be more than 256 characters in length.

      As this is derived from the message content by the server, and the
      algorithm for doing so could change over time, fetching this for
      an Email a second time MAY return a different result.  However,
      the previous value is not considered incorrect, and the change
      SHOULD NOT cause the Email object to be considered as changed by
      the server.

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

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

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

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

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

          if ( isMultipart ) {
              let subMultiType = part.type.split( '/' )[1];
              parseStructure( part.subParts, subMultiType,
                  inAlternative || ( subMultiType == 'alternative' ),
                  htmlBody, textBody, attachments );
          } else if ( isInline ) {
              if ( multipartType == 'alternative' ) {
                  switch ( part.type ) {
                  case 'text/plain':
                      textBody.push( part );
                      break;
                  case 'text/html':
                      htmlBody.push( part );
                      break;
                  default:
                      attachments.push( part );
                      break;
                  }
                  continue;
              } else if ( inAlternative ) {
                  if ( part.type == 'text/plain' ) {
                      htmlBody = null;
                  }
                  if ( part.type == 'text/html' ) {
                      textBody = null;
                  }
              }
              if ( textBody ) {
                  textBody.push( part );
              }
              if ( htmlBody ) {
                  htmlBody.push( part );
              }
              if ( ( !textBody || !htmlBody ) &&
                      isInlineMediaType( part.type ) ) {
                  attachments.push( part );
              }
          } else {
              attachments.push( part );
          }
      }
Top   ToC   RFC8621 - Page 41
      if ( multipartType == 'alternative' && textBody && htmlBody ) {
          // Found HTML part only
          if ( textLength == textBody.length &&
                  htmlLength != htmlBody.length ) {
              for ( let i = htmlLength; i < htmlBody.length; i += 1 ) {
                  textBody.push( htmlBody[i] );
              }
          }
          // Found plaintext part only
          if ( htmlLength == htmlBody.length &&
                  textLength != textBody.length ) {
              for ( let i = textLength; i < textBody.length; i += 1 ) {
                  htmlBody.push( textBody[i] );
              }
          }
      }
  }

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

  parseStructure( [ bodyStructure ], 'mixed', false,
      htmlBody, textBody, attachments );

   For instance, consider a message with both text and HTML versions
   that has gone through a list software manager that attaches a header
   and footer.  It might have a MIME structure something like:

            multipart/mixed
              text/plain, content-disposition=inline - A
              multipart/mixed
                multipart/alternative
                  multipart/mixed
                    text/plain, content-disposition=inline - B
                    image/jpeg, content-disposition=inline - C
                    text/plain, content-disposition=inline - D
                  multipart/related
                    text/html - E
                    image/jpeg - F
                image/jpeg, content-disposition=attachment - G
                application/x-excel - H
                message/rfc822 - J
              text/plain, content-disposition=inline - K
Top   ToC   RFC8621 - Page 42
   In this case, the above algorithm would decompose this to:

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

4.2. Email/get

This is a standard "/get" method as described in [RFC8620], Section 5.1 with the following additional request arguments: o bodyProperties: "String[]" A list of properties to fetch for each EmailBodyPart returned. If omitted, this defaults to: [ "partId", "blobId", "size", "name", "type", "charset", "disposition", "cid", "language", "location" ] o fetchTextBodyValues: "Boolean" (default: false) If true, the "bodyValues" property includes any "text/*" part in the "textBody" property. o fetchHTMLBodyValues: "Boolean" (default: false) If true, the "bodyValues" property includes any "text/*" part in the "htmlBody" property. o fetchAllBodyValues: "Boolean" (default: false) If true, the "bodyValues" property includes any "text/*" part in the "bodyStructure" property. o maxBodyValueBytes: "UnsignedInt" (default: 0) If greater than zero, the "value" property of any EmailBodyValue object returned in "bodyValues" MUST be truncated if necessary so it does not exceed this number of octets in size. If 0 (the default), no truncation occurs. The server MUST ensure the truncation results in valid UTF-8 and does not occur mid-codepoint. If the part is of type "text/html", the server SHOULD NOT truncate inside an HTML tag, e.g., in the middle of "<a href="https://example.com">". There is no requirement for the truncated form to be a balanced tree or valid HTML (indeed, the original source may well be neither of these things).
Top   ToC   RFC8621 - Page 43
   If the standard "properties" argument is omitted or null, the
   following default MUST be used instead of "all" properties:

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

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

   o  id

   o  blobId

   o  threadId

   o  mailboxIds

   o  keywords

   o  size

   o  receivedAt

   o  messageId

   o  inReplyTo

   o  sender

   o  from

   o  to

   o  cc

   o  bcc

   o  replyTo

   o  subject

   o  sentAt

   o  hasAttachment

   o  preview
Top   ToC   RFC8621 - Page 44
   Clients SHOULD take care when fetching any other properties, as there
   may be significantly longer latency in fetching and returning the
   data.

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

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

4.2.1. Example

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

4.3. Email/changes

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


(page 45 continued on part 3)

Next Section