RFC 8621
The JSON Meta Application Protocol (JMAP) for Mail
Title block 💖 (the RFC's vitals!)
Okay so bestie, this is RFC 8621, "The JSON Meta Application Protocol (JMAP) for Mail" 📬✨. It's from August 2019 and it's a Standards Track doc, which means it's the real deal, not just a suggestion 💅. The authors are N. Jenkins from Fastmail and C. Newman from Oracle 🫶. It updates RFC 5788 (so it tweaks that one 🎀), and its ISSN is 2070-1721 🌸.
The whole vibe is email syncing with a server, using JMAP as the base. Clients can search, access, organise, and send messages, and get push notifications so everything stays fresh when new mail lands or someone changes something in another client 🔥.
Status of This Memo 🌈
This is an Internet Standards Track document. It's a product of the IETF, it has the consensus of the IETF community, it got public review, and the IESG approved it for publication 👑. More info on Internet Standards is in Section 2 of RFC 7841, and the current status, errata, and feedback info lives at https://www.rfc-editor.org/info/rfc8621 🦋.
Copyright Notice 💜
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved 🎀. This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stood on the publication date. Read those carefully, because they're about your rights and restrictions 🫶. Any code components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as the Simplified BSD License describes 💅.
Table of Contents 🧚
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
1.3. Additions to the Capabilities Object . . . . . . . . . . 5
1.3.1. urn:ietf:params:jmap:mail . . . . . . . . . . . . . . 5
1.3.2. urn:ietf:params:jmap:submission . . . . . . . . . . . 7
1.3.3. urn:ietf:params:jmap:vacationresponse . . . . . . . . 8
1.4. Data Type Support in Different Accounts . . . . . . . . . 8
1.5. Push . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 9
1.6. Ids . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2. Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1. Mailbox/get . . . . . . . . . . . . . . . . . . . . . . . 14
2.2. Mailbox/changes . . . . . . . . . . . . . . . . . . . . . 14
2.3. Mailbox/query . . . . . . . . . . . . . . . . . . . . . . 14
2.4. Mailbox/queryChanges . . . . . . . . . . . . . . . . . . 15
2.5. Mailbox/set . . . . . . . . . . . . . . . . . . . . . . . 16
2.6. Example . . . . . . . . . . . . . . . . . . . . . . . . . 17
3. Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.1. Thread/get . . . . . . . . . . . . . . . . . . . . . . . 22
3.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 22
3.2. Thread/changes . . . . . . . . . . . . . . . . . . . . . 22
4. Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.1. Properties of the Email Object . . . . . . . . . . . . . 23
4.1.1. Metadata . . . . . . . . . . . . . . . . . . . . . . 24
4.1.2. Header Fields Parsed Forms . . . . . . . . . . . . . 26
4.1.3. Header Fields Properties . . . . . . . . . . . . . . 32
4.1.4. Body Parts . . . . . . . . . . . . . . . . . . . . . 35
4.2. Email/get . . . . . . . . . . . . . . . . . . . . . . . . 42
4.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 44
4.3. Email/changes . . . . . . . . . . . . . . . . . . . . . . 45
4.4. Email/query . . . . . . . . . . . . . . . . . . . . . . . 45
4.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 46
4.4.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 49
4.4.3. Thread Collapsing . . . . . . . . . . . . . . . . . . 50
4.5. Email/queryChanges . . . . . . . . . . . . . . . . . . . 51
4.6. Email/set . . . . . . . . . . . . . . . . . . . . . . . . 51
4.7. Email/copy . . . . . . . . . . . . . . . . . . . . . . . 53
4.8. Email/import . . . . . . . . . . . . . . . . . . . . . . 54
4.9. Email/parse . . . . . . . . . . . . . . . . . . . . . . . 56
4.10. Examples . . . . . . . . . . . . . . . . . . . . . . . . 58
5. Search Snippets . . . . . . . . . . . . . . . . . . . . . . . 68
5.1. SearchSnippet/get . . . . . . . . . . . . . . . . . . . . 69
5.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 71
6. Identities . . . . . . . . . . . . . . . . . . . . . . . . . 72
6.1. Identity/get . . . . . . . . . . . . . . . . . . . . . . 73
6.2. Identity/changes . . . . . . . . . . . . . . . . . . . . 73
6.3. Identity/set . . . . . . . . . . . . . . . . . . . . . . 73
6.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 73
7. Email Submission . . . . . . . . . . . . . . . . . . . . . . 74
7.1. EmailSubmission/get . . . . . . . . . . . . . . . . . . . 80
7.2. EmailSubmission/changes . . . . . . . . . . . . . . . . . 80
7.3. EmailSubmission/query . . . . . . . . . . . . . . . . . . 80
7.4. EmailSubmission/queryChanges . . . . . . . . . . . . . . 81
7.5. EmailSubmission/set . . . . . . . . . . . . . . . . . . . 81
7.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 84
8. Vacation Response . . . . . . . . . . . . . . . . . . . . . . 86
8.1. VacationResponse/get . . . . . . . . . . . . . . . . . . 87
8.2. VacationResponse/set . . . . . . . . . . . . . . . . . . 88
9. Security Considerations . . . . . . . . . . . . . . . . . . . 88
9.1. EmailBodyPart Value . . . . . . . . . . . . . . . . . . . 88
9.2. HTML Email Display . . . . . . . . . . . . . . . . . . . 88
9.3. Multiple Part Display . . . . . . . . . . . . . . . . . . 91
9.4. Email Submission . . . . . . . . . . . . . . . . . . . . 91
9.5. Partial Account Access . . . . . . . . . . . . . . . . . 92
9.6. Permission to Send from an Address . . . . . . . . . . . 92
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 93
10.1. JMAP Capability Registration for "mail" . . . . . . . . 93
10.2. JMAP Capability Registration for "submission" . . . . . 93
10.3. JMAP Capability Registration for "vacationresponse" . . 94
10.4. IMAP and JMAP Keywords Registry . . . . . . . . . . . . 94
10.4.1. Registration of JMAP Keyword "$draft" . . . . . . . 95
10.4.2. Registration of JMAP Keyword "$seen" . . . . . . . . 96
10.4.3. Registration of JMAP Keyword "$flagged" . . . . . . 97
10.4.4. Registration of JMAP Keyword "$answered" . . . . . . 98
10.4.5. Registration of "$recent" Keyword . . . . . . . . . 99
10.5. IMAP Mailbox Name Attributes Registry . . . . . . . . . 99
10.5.1. Registration of "inbox" Role . . . . . . . . . . . . 99
10.6. JMAP Error Codes Registry . . . . . . . . . . . . . . . 100
10.6.1. mailboxHasChild . . . . . . . . . . . . . . . . . . 100
10.6.2. mailboxHasEmail . . . . . . . . . . . . . . . . . . 100
10.6.3. blobNotFound . . . . . . . . . . . . . . . . . . . . 100
10.6.4. tooManyKeywords . . . . . . . . . . . . . . . . . . 101
10.6.5. tooManyMailboxes . . . . . . . . . . . . . . . . . . 101
10.6.6. invalidEmail . . . . . . . . . . . . . . . . . . . . 101
10.6.7. tooManyRecipients . . . . . . . . . . . . . . . . . 102
10.6.8. noRecipients . . . . . . . . . . . . . . . . . . . . 102
10.6.9. invalidRecipients . . . . . . . . . . . . . . . . . 102
10.6.10. forbiddenMailFrom . . . . . . . . . . . . . . . . . 103
10.6.11. forbiddenFrom . . . . . . . . . . . . . . . . . . . 103
10.6.12. forbiddenToSend . . . . . . . . . . . . . . . . . . 103
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 104
11.1. Normative References . . . . . . . . . . . . . . . . . . 104
11.2. Informative References . . . . . . . . . . . . . . . . . 107
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 1081. Introduction ✨
1.1. Notational Conventions 🎀
Okay so the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this doc are read as described in BCP 14 [RFC2119] [RFC8174], but only when they show up in ALL CAPS like this 💅.
Type signatures, examples, and property descriptions follow the conventions from Section 1.1 of [RFC8620]. The data types defined in the core spec are used here too 🦋.
Servers MUST support all properties specified for the new data types defined in this document 🔥.
1.2. Terminology 💜
This doc uses the same terminology as the core JMAP spec 🌸.
The terms Mailbox, Thread, Email, SearchSnippet, EmailSubmission and VacationResponse (with that exact capitalisation) refer to the data types defined here, and to instances of those types 🧚.
The word message means a document in Internet Message Format, as described in [RFC5322]. The Email data type is how the mail store represents messages and their metadata 📬.
Part 1 of 18 is done, bestie! 💖 Part 2 is coming next, so stay tuned 🫶.
1.3. Additions to the Capabilities Object 🎀
okay so the capabilities object is the thing that comes back as part of the JMAP Session object, see [RFC8620], Section 2. bestie, you need to know this one 💅
this document defines three additional capability URIs. three new vibes, let's gooo ✨
1.3.1. urn:ietf:params:jmap:mail 📬
this one represents support for the Mailbox, Thread, Email, and SearchSnippet data types and their API methods. the value in the JMAP session "capabilities" property is an empty object, so simple 🥺
the value in an account's "accountCapabilities" property is an object that MUST contain the server capabilities and permissions for that account. these are the fields:
maxMailboxesPerEmail: "UnsignedInt|null"
the max number of Mailboxes (see Section 2) that can be assigned to one Email object (see Section 4). this MUST be an integer >= 1, or null for no limit. (or rather, the limit is always the number of Mailboxes in the account 🙃)
maxMailboxDepth: "UnsignedInt|null"
the max depth of the Mailbox hierarchy (aka one more than the max number of ancestors a Mailbox may have), or null for no limit.
maxSizeMailboxName: "UnsignedInt"
the max length, in (UTF-8) octets, allowed for the name of a Mailbox. this MUST be at least 100, though servers are recommended to allow more 🌸
maxSizeAttachmentsPerEmail: "UnsignedInt"
the max total size of attachments, in octets, allowed for a single Email object. a server MAY still reject the import or creation of an Email with a lower attachment total. for example, if the body has several megabytes of text, the encoded MIME structure could go over some server-defined limit 😭
ok this one is lowkey iconic. the limit is for the sum of unencoded attachment sizes. users don't know about encoding overhead and honestly they shouldn't have to. marketing and help docs usually say the "max size attachments", and that's the unencoded size they see on their hard drive. so this capability matches what they see, and the client can consistently enforce the limit the user actually understands 🫶
the server might also have a separate limit for the whole message [RFC5322], made from the attachments (often base64 encoded) plus the message headers and bodies. for example, say the server advertises maxSizeAttachmentsPerEmail: 50000000 (50 MB). the enforced server limit could be for a message size of 70000000 octets. even with base64 encoding and a 2 MB HTML body, 50 MB of attachments would still fit under that limit 🧚
emailQuerySortOptions: "String[]"
a list of all the values the server supports for the property field of the Comparator object in an Email/query sort (see Section 4.4.2). this MAY include properties the client doesn't recognise (like custom properties from a vendor extension). clients MUST ignore any unknown properties in the list 💜
mayCreateTopLevelMailbox: "Boolean"
if true, the user may create a Mailbox (see Section 2) in this account with a null parentId. (permission for creating a child of an existing Mailbox comes from the myRights property on that Mailbox.) 🍓
1.3.2. urn:ietf:params:jmap:submission 📤
this one represents support for the Identity and EmailSubmission data types and their API methods. the value in the JMAP session "capabilities" property is an empty object.
the value in an account's "accountCapabilities" property is an object that MUST contain the server capabilities and permissions for that account:
maxDelayedSend: "UnsignedInt"
the number of seconds of max delay the server supports when sending (see the EmailSubmission object description). it's 0 if the server doesn't support delayed send ⏰
submissionExtensions: "String[String[]]"
the set of SMTP submission extensions the server supports, which the client may use when creating an EmailSubmission object (see Section 7). each key in the object is the "ehlo-name", and the value is a list of "ehlo-args" 🔥
a JMAP implementation that talks to a submission server [RFC6409] SHOULD have a config setting that lets an admin change the set of submission EHLO capabilities it may expose on this property. this means a JMAP server can add access to a new submission extension without code changes, which is so convenient. by default, the JMAP server should hide EHLO capabilities about the transport mechanism, since those only matter to the JMAP server itself (for example, PIPELINING, CHUNKING, or STARTTLS) 🙈
examples of submission extensions to include:
a JMAP server MAY advertise an extension and implement its semantics locally on the JMAP server, even if the submission server used by JMAP doesn't implement it 👑
the full IANA registry of submission extensions lives at <https://www.iana.org/assignments/mail-parameters> 🦋
1.3.3. urn:ietf:params:jmap:vacationresponse 🌴
this one represents support for the VacationResponse data type and its API methods. the value is an empty object in both the JMAP session "capabilities" property and an account's "accountCapabilities" property.
1.4. Data Type Support in Different Accounts 👯
the server MUST include the appropriate capability strings as keys in the "accountCapabilities" property of any account where the user may use the data types that URI represents. supported data types can differ between accounts the user can access. for example, in their personal account they might have all three sets of data, but in a shared account they might only have data for "urn:ietf:params:jmap:mail". that means they can access Mailbox/Thread/Email data in the shared account, but they're not allowed to send as that account (so no Identity/EmailSubmission objects for them) or to view or set its VacationResponse 🙅♀️
1.5. Push 🔔
servers MUST support the JMAP push mechanisms, as specified in [RFC8620], Section 7, so they can notify clients when the state changes for any of the types defined in this specification.
on top of that, servers that implement the "urn:ietf:params:jmap:mail" capability MUST support pushing state changes for a type called EmailDelivery. there are no methods to act on this type. it only exists as part of the push mechanism. the state string for this MUST change whenever a new Email is added to the store, but it SHOULD NOT change for any other change to the Email objects, like when one is marked as read or deleted 📩
clients in battery-constrained environments may wish to delay fetching changes the user started, but still fetch new Emails right away so they can notify the user. to do that, they can register for pushes for the EmailDelivery type instead of the Email type (as defined in Section 4) 🔋
1.5.1. Example 🎬
the client has registered for push notifications (see [RFC8620]) just for the EmailDelivery type. the user marks an Email as read on another device, which changes the state string for the Email type. but nothing new was added to the store, so the EmailDelivery state doesn't change and nothing gets pushed to the client. then a new message lands in the user's inbox, which changes the Email state again. this time the EmailDelivery state changes too, so a StateChange object gets pushed to the client with the new state string. the client can then resync to fetch the new Email right away 💌
1.6. Ids 🪪
if a JMAP Mail server also provides an IMAP interface to the data and supports the IMAP Extension for Object Identifiers [RFC8474], the ids SHOULD be the same for Mailbox, Thread, and Email objects in JMAP 💖
2. Mailboxes ✨
okay so a Mailbox is basically a named bucket of Email objects 📬 It's the main way you organise your messages in an account. Think folder or label, depending on which app you're used to. A Mailbox can also have a special job in the system (a "role"), which we'll get to in a sec 🎀
For IMAP compatibility, an Email MUST belong to one or more Mailboxes. And the Email's id stays the same even when it moves between Mailboxes 🦋
A Mailbox object has the following properties:
id:"Id"(immutable; server-set). The id of the Mailbox.name:"String". The user-visible name, like "Inbox" 💌 This MUST be a Net-Unicode string [RFC5198] that is at least 1 character long, and it has to fit within the maximum size given in the capability object. There MUST NOT be two sibling Mailboxes that share both the same parent and the same name. Servers MAY reject names that break server policy (for example, names with a slash (/) or control characters) 🙅♀️parentId:"Id|null"(default: null). The Mailbox id of this Mailbox's parent, or null if it sits at the top level 🌳 Mailboxes form acyclic graphs (forests) pointing from child to parent. There MUST NOT be a loop. No ouroboros situations, bestie 🐍role:"String|null"(default: null). This identifies Mailboxes with a particular common purpose (like the "inbox") no matter what their "name" says, since names can be localised 🌍
This value is shared with IMAP (exposed in IMAP via the SPECIAL-USE extension [RFC6154]). Unlike IMAP, though, a Mailbox MUST only have a single role, and there MUST NOT be two Mailboxes in the same account with the same role. Servers that give IMAP access to the same data are encouraged to enforce these extra restrictions in IMAP too. Otherwise, changing the IMAP attributes so things comply when the data is exposed over JMAP is implementation dependent 🤷♀️
The value MUST be one of the Mailbox attribute names listed in the IANA "IMAP Mailbox Name Attributes" registry at <https://www.iana.org/assignments/imap-mailbox-name-attributes/>, as established in [RFC8457], converted to lowercase. New roles may be established there in the future 🔮
An account is not required to have Mailboxes with any particular roles. No pressure, babe 💅
sortOrder:"UnsignedInt"(default: 0). This defines the order Mailboxes show up in the client's UI, so it stays consistent across devices 📱 The number MUST be an integer in the range 0 <= sortOrder < 2^31.
A Mailbox with a lower order should be displayed before one with a higher order (if they share the same parent) in any Mailbox listing in the UI. Mailboxes with equal order SHOULD be sorted alphabetically by name. The sorting should also take locale-specific character order conventions into account 🌸
totalEmails:"UnsignedInt"(server-set). The number of Emails in this Mailbox 📊unreadEmails:"UnsignedInt"(server-set). The number of Emails in this Mailbox that have neither the"$seen"keyword nor the"$draft"keyword 👀totalThreads:"UnsignedInt"(server-set). The number of Threads where at least one Email in the Thread is in this Mailbox 🧵unreadThreads:"UnsignedInt"(server-set). An indication of how many "unread" Threads are in the Mailbox 💭
Here's the tea ☕ The way "unread Threads" gets counted is NOT mandated in this document, for compatibility with existing implementations. The simplest version to build is just the number of Threads where at least one Email is both in this Mailbox and has neither the "$seen" nor the "$draft" keyword.
BUT a quality implementation will return the number of unread items the user would actually see if they opened that Mailbox ✨ A Thread counts as unread if it contains any unread Emails that will be displayed when the Thread is opened. So unreadThreads should be the number of Threads where at least one Email has neither the "$seen" nor the "$draft" keyword AND at least one Email in the Thread is in this Mailbox. The unread Email doesn't have to be the one that's in this Mailbox, btw. On top of that, the trash Mailbox (that's a Mailbox whose role is "trash") needs special treatment 🗑️
- Emails that are only in the trash (and no other Mailbox) are ignored when calculating the
unreadThreadscount of other Mailboxes. - Emails that are not in the trash are ignored when calculating the
unreadThreadscount for the trash Mailbox.
So Emails in the trash get treated as if they're in a separate Thread for unread counts. Clients are expected to hide trashed Emails when viewing a Thread in another Mailbox, and the other way around too. This is what lets you delete a single Email to the trash out of a Thread, which is iconic 🫶
For example, imagine an account where the whole thing is one Thread with 2 Emails: an unread Email in the trash and a read Email in the inbox. The unreadThreads count would be 1 for the trash and 0 for the inbox 🧠
myRights:"MailboxRights"(server-set). The set of rights (Access Control Lists (ACLs)) the user has for this Mailbox 🔐 These are backwards compatible with IMAP ACLs, as defined in [RFC4314]. A MailboxRights object has the following properties:mayReadItems:"Boolean". If true, the user can use this Mailbox as part of a filter in an"Email/query"call, and the Mailbox can show up in the"mailboxIds"property of Email objects. Email objects may be fetched if they are in at least one Mailbox with this permission. If a sub-Mailbox is shared but its parent isn't, this may be false. Corresponds to IMAP ACLs "lr" (if mapping from IMAP, both are required for this to be true).mayAddItems:"Boolean". The user may add mail to this Mailbox (by creating a new Email or moving an existing one into it). Corresponds to IMAP ACL "i".mayRemoveItems:"Boolean". The user may remove mail from this Mailbox (by changing the Mailboxes of an Email or destroying the Email). Corresponds to IMAP ACLs "te" (if mapping from IMAP, both are required for this to be true).maySetSeen:"Boolean". The user may add or remove the"$seen"keyword on an Email. If an Email is in multiple Mailboxes, the user may only change"$seen"if they have this permission for all of those Mailboxes. Corresponds to IMAP ACL "s".maySetKeywords:"Boolean". The user may add or remove any keyword other than"$seen"on an Email. If an Email is in multiple Mailboxes, the user may only change keywords if they have this permission for all of those Mailboxes. Corresponds to IMAP ACL "w".mayCreateChild:"Boolean". The user may create a Mailbox with this Mailbox as its parent. Corresponds to IMAP ACL "k".mayRename:"Boolean". The user may rename the Mailbox or make it a child of another Mailbox. Corresponds to IMAP ACL "x" (although that one covers both rename and delete permissions).mayDelete:"Boolean". The user may delete the Mailbox itself. Corresponds to IMAP ACL "x" (although that one covers both rename and delete permissions).maySubmit:"Boolean". Messages may be submitted directly to this Mailbox. Corresponds to IMAP ACL "p".
isSubscribed:"Boolean". Has the user said they want to see this Mailbox in their client? 👑 This SHOULD default to false for Mailboxes in shared accounts the user has access to, and true for any new Mailboxes the user creates themself. This MUST be stored separately per user wherever multiple users can access a shared Mailbox.
Some users can access a ton of shared accounts, or one shared account with a massive pile of Mailboxes, but only care about a few. Clients may choose to only show Mailboxes where isSubscribed is true, and offer a separate UI so the user can see and subscribe or unsubscribe from the full set. However, clients MAY choose to ignore this property, either entirely to keep implementation easy, or just for an account where "isPersonal" is true (meaning it's the user's own account rather than a shared one) 💖
This property corresponds to IMAP [RFC3501] mailbox subscriptions.
For IMAP compatibility, an Email that's in both the trash and another Mailbox SHOULD be treated by the client as existing in both places. So when emptying the trash, the client should just remove it from the trash Mailbox and leave it in the other one 🧹
The following JMAP methods are supported. 🌈
2.1. Mailbox/get
This is a standard "/get" method as described in [RFC8620], Section 5.1. The ids argument may be null to fetch everything all at once 🍓
2.2. Mailbox/changes
This is a standard "/changes" method as described in [RFC8620], Section 5.2, but it has one extra argument in the response:
updatedProperties:"String[]|null". If only the"totalEmails","unreadEmails","totalThreads", and/or"unreadThreads"Mailbox properties have changed since the old state, this will be the list of properties that may have changed. If the server can't tell whether only the counts changed, it MUST just be null. 🧮
Counts change constantly, but other properties usually change way less often 🥹 So the server can help the client save on data transfer by tracking changes to the Email and Thread counts separately from other state changes. The updatedProperties array can be used directly through a back-reference in a later Mailbox/get call in the same request, so only those properties come back if nothing else has changed ✨
Okay so bestie, we're picking up right where the Mailbox stuff left off 💅✨
2.3. Mailbox/query 🔍
okay so this is a totally standard "/query" method, just like the one in [RFC8620], Section 5.5, but it comes with an extra request argument that's giving main character energy 👑
- sortAsTree: "Boolean" (default: false) 🌳
if this is true, then when the server is sorting the results and comparing Mailbox A and Mailbox B:
- if A is an ancestor of B, A ALWAYS comes first no matter what the sort comparators say 🙌 and the same goes the other way, so if A is a descendant of B, then B always comes first.
- otherwise, if A and B don't share a "parentId", the server finds the nearest ancestors of each that DO share a "parentId" and compares the sort properties on those Mailboxes instead 🧠
the result is literally a tree 🌲 sorted by the parentId properties, with each group of siblings sorted by the normal sort comparators. so cute, right? 🥹
- filterAsTree: "Boolean" (default: false) 🌸
if true, a Mailbox only shows up in the query if ALL of its ancestors are also in the query results according to the filter. no sneaking in without your family 😤
A FilterCondition object has the following properties, and any of them can be left out 🎀
- parentId: "Id|null"
the Mailbox "parentId" property has to match the given value EXACTLY 🎯
- name: "String"
the Mailbox "name" property has to contain the given string 🔎
- role: "String|null"
the Mailbox "role" property has to match the given value exactly 💖
- hasAnyRole: "Boolean"
if true, the Mailbox matches as long as it has any non-null value for its "role" property 🦋
- isSubscribed: "Boolean"
the "isSubscribed" property of the Mailbox has to be identical to the value you give it to match 🫶
so a Mailbox matches the FilterCondition if and only if ALL the conditions you gave it match ✨ and if you specify zero properties, it's automatically true for everything. iconic 💅
The following Mailbox properties MUST be supported for sorting 🚨:
- "sortOrder"
- "name"
2.4. Mailbox/queryChanges 🔄
this is a standard "/queryChanges" method, same as the one described in [RFC8620], Section 5.6. nothing extra to see here, periodt 💅
2.5. Mailbox/set ✏️
this is a standard "/set" method as described in [RFC8620], Section 5.3, but it has an extra request argument 🎀
- onDestroyRemoveEmails: "Boolean" (default: false) 🗑️
okay so if this is false, then trying to destroy a Mailbox that still has Emails in it gets rejected with a "mailboxHasEmail" SetError 🙅♀️. but if it's true, then any Emails in that Mailbox get removed from it, and if they aren't in any other Mailboxes, they get destroyed along with it 💀
The following extra SetError types are defined 🌈
For "destroy":
- "mailboxHasChild": the Mailbox still has at least one child Mailbox. the client MUST remove these before it can delete the parent Mailbox 🧸
- "mailboxHasEmail": the Mailbox has at least one Email assigned to it, and the "onDestroyRemoveEmails" argument was false 📭
2.6. Example 🧚
ok let's see this in action, bestie 🥰
Fetching all Mailboxes in an account:
[[ "Mailbox/get", {
"accountId": "u33084183",
"ids": null
}, "0" ]]And the response:
[[ "Mailbox/get", {
"accountId": "u33084183",
"state": "78540",
"list": [{
"id": "MB23cfa8094c0f41e6",
"name": "Inbox",
"parentId": null,
"role": "inbox",
"sortOrder": 10,
"totalEmails": 16307,
"unreadEmails": 13905,
"totalThreads": 5833,
"unreadThreads": 5128,
"myRights": {
"mayAddItems": true,
"mayRename": false,
"maySubmit": true,
"mayDelete": false,
"maySetKeywords": true,
"mayRemoveItems": true,
"mayCreateChild": true,
"maySetSeen": true,
"mayReadItems": true
},
"isSubscribed": true
}, {
"id": "MB674cc24095db49ce",
"name": "Important mail",
...
}, ... ],
"notFound": []
}, "0" ]]Now suppose an Email is marked read, and we get a push update that the Mailbox state has changed. You might fetch the updates like this 📬:
[[ "Mailbox/changes", {
"accountId": "u33084183",
"sinceState": "78540"
}, "0" ],
[ "Mailbox/get", {
"accountId": "u33084183",
"#ids": {
"resultOf": "0",
"name": "Mailbox/changes",
"path": "/created"
}
}, "1" ],
[ "Mailbox/get", {
"accountId": "u33084183",
"#ids": {
"resultOf": "0",
"name": "Mailbox/changes",
"path": "/updated"
},
"#properties": {
"resultOf": "0",
"name": "Mailbox/changes",
"path": "/updatedProperties"
}
}, "2" ]]this fetches the list of ids for created/updated/destroyed Mailboxes, and then, using back-references, it fetches the data for just the created/updated Mailboxes in the same request. the response may look something like this ✨:
[[ "Mailbox/changes", {
"accountId": "u33084183",
"oldState": "78541",
"newState": "78542",
"hasMoreChanges": false,
"updatedProperties": [
"totalEmails", "unreadEmails",
"totalThreads", "unreadThreads"
],
"created": [],
"updated": ["MB23cfa8094c0f41e6"],
"destroyed": []
}, "0" ],
[ "Mailbox/get", {
"accountId": "u33084183",
"state": "78542",
"list": [],
"notFound": []
}, "1" ],
[ "Mailbox/get", {
"accountId": "u33084183",
"state": "78542",
"list": [{
"id": "MB23cfa8094c0f41e6",
"totalEmails": 16307,
"unreadEmails": 13903,
"totalThreads": 5833,
"unreadThreads": 5127
}],
"notFound": []
}, "2" ]]Here's an example where we try to rename one Mailbox and destroy another 🙈:
[[ "Mailbox/set", {
"accountId": "u33084183",
"ifInState": "78542",
"update": {
"MB674cc24095db49ce": {
"name": "Maybe important mail"
}
},
"destroy": [ "MB23cfa8094c0f41e6" ]
}, "0" ]]Suppose the rename succeeds, but we don't have permission to destroy the Mailbox we tried to destroy. we might get back 😭:
[[ "Mailbox/set", {
"accountId": "u33084183",
"oldState": "78542",
"newState": "78549",
"updated": {
"MB674cc24095db49ce": null
},
"notDestroyed": {
"MB23cfa8094c0f41e6": {
"type": "forbidden"
}
}
}, "0" ]]3. Threads 🧵
Replies get grouped together with the original message to form a Thread 🫶. in JMAP, a Thread is simply a flat list of Emails, ordered by date. Every Email MUST belong to a Thread, even if it's the only Email in there, no exceptions 💅
The exact algorithm for deciding whether two Emails belong to the same Thread is NOT mandated in this spec, so it can stay compatible with different existing systems. for new implementations, it is suggested that two messages belong in the same Thread if both of the following conditions apply 🧠:
- An identical message id [RFC5322] appears in both messages in any of the Message-Id, In-Reply-To, and References header fields.
- After stripping automatically added prefixes such as "Fwd:", "Re:", "[List-Tag]", etc., and ignoring white space, the subjects are the same. this avoids the situation where a person replies to an old message as a convenient way of finding the right recipient to send to but changes the subject and starts a new conversation 🙄
if messages are delivered out of order for some reason, a user may have two Emails in the same Thread but without headers that associate them with each other. the arrival of a third Email may provide the missing references to join them all together into a single Thread 🪄. since the "threadId" of an Email is immutable, if the server wishes to merge the Threads, it MUST handle this by deleting and reinserting (with a new Email id) the Emails that change "threadId" 🔁.
A Thread object has the following properties 📋:
- id: "Id" (immutable; server-set)
the id of the Thread 🆔.
- emailIds: "Id[]" (server-set)
the ids of the Emails in the Thread, sorted by the "receivedAt" date of the Email, oldest first. if two Emails have an identical date, the sort is server dependent but MUST be stable (sorting by id is recommended) 🌟.
The following JMAP methods are supported 💜.
3.1. Thread/get 🌷
this is a standard "/get" method as described in [RFC8620], Section 5.1.
3.1.1. Example 🎀
Request:
[[ "Thread/get", {
"accountId": "acme",
"ids": ["f123u4", "f41u44"]
}, "#1" ]]with response:
[[ "Thread/get", {
"accountId": "acme",
"state": "f6a7e214",
"list": [
{
"id": "f123u4",
"emailIds": [ "eaa623", "f782cbb"]
},
{
"id": "f41u44",
"emailIds": [ "82cf7bb" ]
}
],
"notFound": []
}, "#1" ]]3.2. Thread/changes 🦋
this is a standard "/changes" method as described in [RFC8620], Section 5.2. same energy as before, slay 💅
4. Emails 💌
An Email object is a representation of a message [RFC5322], and it lets clients skip the complexities of MIME parsing, transfer encoding, and character encoding. no more wrestling with that stuff, bestie 🫶✨
4.1. Properties of the Email Object 💌✨
Okay bestie, the Email object is literally the main character 💅 A message is basically two parts: a list of header fields, then a body. The Email data type lets you get at the full structure, or use simplified properties and skip some of the complexity if that's all your client app needs. 🫶
While raw headers can be fetched and set, the vast majority of clients should use an appropriate parsed form for each header field they want to process. That way they dodge the various encodings a valid message needs per RFC 5322. 🔥
The body of a message is normally a MIME-encoded set of documents in a tree structure. It can be nested as deep as it wants 🌳, but most email clients show a flat model of the body (normally plaintext or HTML) with a set of attachments. Flattening the MIME structure into that model is tricky and causes inconsistency between clients 😭. So, in addition to the "bodyStructure" property, which gives the full tree, the Email object has 3 alternate properties with flat lists of body parts:
"textBody"/"htmlBody": These provide a list of parts that should be rendered sequentially as the "body" of the message. It's a list rather than a single part because messages may have headers and/or footers appended or prepended as separate parts when they're transmitted. Some clients also send text and images meant to be displayed inline in the body (or even videos and sound clips) as multiple parts, rather than one HTML part with referenced images. 🎀
Because MIME allows multiple representations of the same data (using "multipart/alternative"), there's a "textBody" property (which prefers a plaintext representation) and an "htmlBody" property (which prefers an HTML representation) to cover the two most common client requirements. The same part may appear in both lists where there is no alternative between the two. 🦋
"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 show these as attachments in the UI if they're displaying the HTML with the embedded images directly. Some parts may also be inhtmlBody/textBody, so again, clients may wish to not show those as attachments if they're rendered as part of the body. 📎
The "bodyValues" property lets clients fetch the value of text parts directly, without a second request for the blob, and has the server handle decoding the charset into unicode. 🧚 It lives in a separate property rather than on the EmailBodyPart object to avoid duplicating large amounts of data, since 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.
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]. 🙈
blobId:"Id"(immutable; server-set)
The id representing the raw octets of the message [RFC5322] for this Email. You can use this to download the raw original message, or attach it directly to another Email, etc. 💾
threadId:"Id"(immutable; server-set)
The id of the Thread this Email belongs to. 🧵
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. 📬
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 they 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, because IMAP uses a delete+expunge model, which JMAP does not. Any message with the "\Deleted" keyword MUST NOT be visible via JMAP (and so isn't 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 (which 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. 🚨"$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. 💖
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). 📏
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 you can fetch 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 not including 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, because most generated messages insert a space after the colon that terminates the header field name.
4.1.2.2. Text 📝
Type: "String"
The header field value, with:
- White space unfolded (as defined in [RFC5322], Section 2.2.3).
- The terminating CRLF at the end of the value removed.
- Any SP characters at the beginning of the value removed.
- 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. 🙅
- 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:
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. 🫧
An EmailAddress object has the following properties:
name:"String|null"
The "display-name" of the "mailbox" [RFC5322]. If this is a "quoted-string":
- The surrounding DQUOTE characters are removed.
- Any "quoted-pair" is decoded.
- 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. 🎭
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, it may not contain an @ symbol). 🤷♀️
For example, the following "address-list" string:
" James Smythe" <james@example.com>, Friends:
jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?=
<john@example.com>;would be parsed as:
[
{ "name": "James Smythe", "email": "james@example.com" },
{ "name": null, "email": "jane@example.com" },
{ "name": "John Smith", "email": "john@example.com" }
]To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:
- From
- Sender
- Reply-To
- To
- Cc
- Bcc
- Resent-From
- Resent-Sender
- Resent-Reply-To
- Resent-To
- Resent-Cc
- Resent-Bcc
- Any header field not defined in [RFC5322] or [RFC2369]
4.1.2.4. GroupedAddresses ✨
Type: "EmailAddressGroup[]"
okay so this one is like the Addresses form but bestie, it keeps the group info 🫶 The header field gets parsed as an "address-list" value (see [RFC5322], Section 3.4) into the "GroupedAddresses[]" type. Any plain "mailbox" values that aren't part of a group still get wrapped in an EmailAddressGroup object so everything has the same shape. Very uniform, very slay 💅
An EmailAddressGroup object has these properties:
- name:
"String|null"
The "display-name" of the "group" [RFC5322], or null if the addresses aren't part of a group. If this is a "quoted-string", it gets processed the same way as the "name" in the EmailAddress type. 🎀
- 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). This part is not optional, babe 🙈
Parsing SHOULD be best effort in the face of invalid structure, so it can handle invalid messages and semi-complete drafts. Real life is messy and so is email 😭
For example, this "address-list" string:
James Smythe" <james@example.com>, Friends:
jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?=
<john@example.com>;Wait, let me copy that one exactly, character for character, because it's the source string and it has to stay exact:
" 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). Keep it consistent, or it gets chaotic 🌀
4.1.2.5. MessageIds
Type: "String[]|null"
The header field is parsed as a list of "msg-id" values (see [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:
- Message-ID
- In-Reply-To
- References
- Resent-Message-ID
- 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 (see [RFC5322], Section 3.3) into the "Date" type. If parsing fails, the value is null. Time is a construct, but parsing is still a thing 🕰️💜
To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:
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 don't 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:
- List-Help
- List-Unsubscribe
- List-Subscribe
- List-Post
- List-Owner
- List-Archive
- 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. It's giving full transparency 👑
- 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 these properties:
- name:
"String"
The header "field name" as defined in [RFC5322], with the same capitalization it has in the message. 💅
- value:
"String"
The header "field value" as defined in [RFC5322], in Raw form. 🦋
In addition, the client may request/send properties representing individual header fields in this 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 these suffixes:
- :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. ✨
- :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 isn't 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. Easy peasy 🍓
For a more complex example, consider the client requesting a property called header:Resent-To:asAddresses:all. This means:
- Find all header fields named Resent-To (matched case insensitively).
- For each instance, parse the header field value in the Addresses form.
- 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. It's arrays all the way down 🪆💖
The following convenience properties are also specified for the Email object. Think of these as shortcuts, bestie 🫶
- 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. 💜
- inReplyTo:
"String[]|null"(immutable)
The value is identical to the value of header:In-Reply-To:asMessageIds.
- references:
"String[]|null"(immutable)
The value is identical to the value of header:References:asMessageIds.
- sender:
"EmailAddress[]|null"(immutable)
The value is identical to the value of header:Sender:asAddresses.
- from:
"EmailAddress[]|null"(immutable)
The value is identical to the value of header:From:asAddresses.
- to:
"EmailAddress[]|null"(immutable)
The value is identical to the value of header:To:asAddresses.
- cc:
"EmailAddress[]|null"(immutable)
The value is identical to the value of header:Cc:asAddresses.
- bcc:
"EmailAddress[]|null"(immutable)
The value is identical to the value of header:Bcc:asAddresses.
- replyTo:
"EmailAddress[]|null"(immutable)
The value is identical to the value of header:Reply-To:asAddresses.
- subject:
"String|null"(immutable)
The value is identical to the value of header:Subject:asText.
- 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]. It's the juicy part of the email, no cap 🔥
An EmailBodyPart object has these properties:
- 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/*". 🧩
- 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's treated as though it had no transfer encoding. 🔐
- 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). 📦
- 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. 🎀
- 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]. 🏷️
- 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. 🦋
- 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". 🔤
- 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. 🪧
- 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]. 🖼️
- language:
"String[]|null"
The list of language tags, as defined in [RFC3282], in the Content-Language header field of the part, if present. 🗣️
- location:
"String|null"
The URI, as defined in [RFC2557], in the Content-Location header field of the part, if present. 📍
- subParts:
"EmailBodyPart[]|null"
If the type is "multipart/*", this contains the body parts of each child. Body parts all the way down, like a nesting doll 🪆
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".
The following Email properties are specified for access to the body data of the message:
- 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/*". 🏗️
- bodyValues:
"String[EmailBodyValue]"(immutable)
Okay bestie, this part is a map of partId to an EmailBodyValue object 🗺️💖 for none, some, or all text/* parts. Which parts get included, and whether the value gets chopped (truncated), depends on the arguments you pass to Email/get and Email/parse 🎀. An EmailBodyValue object has these properties:
value: "String"
The body part's value, after decoding the Content-Transfer-Encoding and the Content-Type charset (if the server knows both), with any CRLF swapped for a single LF ✨. The server MAY use heuristics to figure out the charset if it's unknown, not given, or the server thinks the given one is wrong 🕵️♀️. Decoding is best effort, so the server SHOULD insert the unicode replacement character (U+FFFD) and keep going when it hits a malformed section 🫶.
Heads up: because of the charset decoding and the line ending cleanup, the length of this string probably won't match the size property on the matching EmailBodyPart exactly 📏.
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 🔐.
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 📝.
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 🌸.
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 intextBodyorhtmlBody - of type
image/*,audio/*, orvideo/*and not in bothtextBodyandhtmlBody
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 🖼️.
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 🤷♀️.
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 it 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 🙃. It's a quality-of-service implementation issue and will likely need workarounds for malformed content discovered over time 🛠️. However, the following algorithm (expressed here in JavaScript) is suggested as a starting point, based on real-world experience 💜:
function isInlineMediaType ( type ) {
return type.startsWith( 'image/' ) ||
type.startsWith( 'audio/' ) ||
type.startsWith( 'video/' );
}
function parseStructure ( parts, multipartType, inAlternative,
htmlBody, textBody, attachments ) {
// For multipartType == alternative
let textLength = textBody ? textBody.length : -1;
let htmlLength = htmlBody ? htmlBody.length : -1;
for ( let i = 0; i < parts.length; i += 1 ) {
let part = parts[i];
let isMultipart = part.type.startsWith( 'multipart/' );
// Is this a body part rather than an attachment
let isInline = part.disposition != "attachment" &&
// Must be one of the allowed body types
( part.type == "text/plain" ||
part.type == "text/html" ||
isInlineMediaType( part.type ) ) &&
// If multipart/related, only the first part can be inline
// If a text part with a filename, and not the first item
// in the multipart, assume it is an attachment
( i === 0 ||
( multipartType != "related" &&
( isInlineMediaType( part.type ) || !part.name ) ) );
if ( isMultipart ) {
let subMultiType = part.type.split( '/' )[1];
parseStructure( part.subParts, subMultiType,
inAlternative || ( subMultiType == 'alternative' ),
htmlBody, textBody, attachments );
} else if ( isInline ) {
if ( multipartType == 'alternative' ) {
switch ( part.type ) {
case 'text/plain':
textBody.push( part );
break;
case 'text/html':
htmlBody.push( part );
break;
default:
attachments.push( part );
break;
}
continue;
} else if ( inAlternative ) {
if ( part.type == 'text/plain' ) {
htmlBody = null;
}
if ( part.type == 'text/html' ) {
textBody = null;
}
}
if ( textBody ) {
textBody.push( part );
}
if ( htmlBody ) {
htmlBody.push( part );
}
if ( ( !textBody || !htmlBody ) &&
isInlineMediaType( part.type ) ) {
attachments.push( part );
}
} else {
attachments.push( part );
}
}
if ( multipartType == 'alternative' && textBody && htmlBody ) {
// Found HTML part only
if ( textLength == textBody.length &&
htmlLength != htmlBody.length ) {
for ( let i = htmlLength; i < htmlBody.length; i += 1 ) {
textBody.push( htmlBody[i] );
}
}
// Found 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 - KIn 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 ✨
okay so Email/get is literally the standard "/get" method from [RFC8620], Section 5.1, but it comes with some extra request arguments that are lowkey the best part 💅
bodyProperties:"String[]"
this is the list of properties to fetch for each EmailBodyPart that comes back. if you leave it out, it defaults to:
[ "partId", "blobId", "size", "name", "type", "charset",
"disposition", "cid", "language", "location" ]fetchTextBodyValues:"Boolean"(default: false)
if true, the "bodyValues" property includes any "text/*" part in the "textBody" property 🫶
fetchHTMLBodyValues:"Boolean"(default: false)
if true, the "bodyValues" property includes any "text/*" part in the "htmlBody" property 🌸
fetchAllBodyValues:"Boolean"(default: false)
if true, the "bodyValues" property includes any "text/*" part in the "bodyStructure" property ✨
maxBodyValueBytes:"UnsignedInt"(default: 0)
if it's greater than zero, the "value" property of any EmailBodyValue object returned in "bodyValues" MUST be truncated if needed so it doesn't go over this many octets 🦋 if it's 0 (the default), nothing gets truncated.
the server MUST make sure the truncation gives valid UTF-8 and doesn't happen mid-codepoint, because that would be a whole mess 💀 if the part is "text/html", the server SHOULD NOT truncate inside an HTML tag, like in the middle of <a href="https://example.com">. the truncated bit doesn't have to be a balanced tree or valid HTML either (honestly the original source might not be either of those things, so it's giving realistic 🙈)
if the standard "properties" argument is omitted or null, then 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" ]these properties are expected to be fast to fetch in a quality implementation 🧚
idblobIdthreadIdmailboxIdskeywordssizereceivedAtmessageIdinReplyTosenderfromtoccbccreplyTosubjectsentAthasAttachmentpreview
clients SHOULD take care when fetching any other properties, because they can have way longer latency when fetching and returning the data 👀
as we said above, parsed forms of headers can only be used on the appropriate header fields. trying to fetch a form that's forbidden (like header:From:asDate) MUST result in the method call being rejected with an invalidArguments error. no cap, that's a hard no 🚫
and when a specific header field is requested as a property, the capitalization of the property name in the response MUST be identical to the one 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 the response:
[[ "Email/get", {
"accountId": "abc",
"state": "41234123231",
"list": [
{
"id": "f123u457",
"threadId": "ef1314a",
"mailboxIds": { "f123": true },
"from": [{ "name": "Joe Bloggs", "email": "joe@example.com" }],
"subject": "Dinner on Thursday?",
"receivedAt": "2013-10-13T14:12:00Z",
"header:List-POST:asURLs": [
"mailto:partytime@lists.example.com"
],
"htmlBody": [{
"partId": "1",
"blobId": "B841623871",
"size": 283331,
"type": "text/html"
}, {
"partId": "2",
"blobId": "B319437193",
"size": 10343,
"type": "text/plain"
}],
"bodyValues": {
"1": {
"isEncodingProblem": false,
"isTruncated": true,
"value": "<html><body><p>Hello ..."
},
"2": {
"isEncodingProblem": false,
"isTruncated": false,
"value": "-- Sent by your friendly mailing list ..."
}
}
}
],
"notFound": [ "f123u456" ]
}, "#1" ]]4.3. Email/changes 🦋
this is the standard "/changes" method from [RFC8620], Section 5.2. if you're generating intermediate states for a big set of changes, it's recommended that newer changes get returned first, because those are usually what users care about most 💖
4.4. Email/query 🔥
this is the standard "/query" method from [RFC8620], Section 5.5, but with one extra request argument:
collapseThreads:"Boolean"(default: false)
if true, Emails in the same Thread as a previous Email in the list (given the filter and sort order) get removed from the list. so only one Email at most ends up in the list for any given Thread 🧵
in quality implementations, the query "total" property is expected to be fast to calculate when the filter is just a single "inMailbox" property. that's because it's the same as the totalEmails or totalThreads property (depending on whether collapseThreads is true) of the associated Mailbox object. main character energy for the server 👑
4.4.1. Filtering 💜
a FilterCondition object has the following properties, and any of them can be omitted:
inMailbox:"Id"
a Mailbox id. an Email must be in this Mailbox to match the condition 📬
inMailboxOtherThan:"Id[]"
a list of Mailbox ids. an Email must be in at least one Mailbox that's not on this list to match. this is so messages that are only in trash or spam can be easily excluded from a search 🗑️
before:"UTCDate"
the "receivedAt" date-time of the Email must be before this date-time to match 🕰️
after:"UTCDate"
the "receivedAt" date-time of the Email must be the same as or after this date-time to match 🌅
minSize:"UnsignedInt"
the "size" property of the Email must be equal to or greater than this number to match 📏
maxSize:"UnsignedInt"
the "size" property of the Email must be less than this number to match 📐
allInThreadHaveKeyword:"String"
all Emails (including this one) in the same Thread as this Email must have the given keyword to match 🔑
someInThreadHaveKeyword:"String"
at least one Email (possibly this one) in the same Thread as this Email must have the given keyword to match 🗝️
noneInThreadHaveKeyword:"String"
all Emails (including this one) in the same Thread as this Email must not have the given keyword to match 🙅
hasKeyword:"String"
this Email must have the given keyword to match 💅
notKeyword:"String"
this Email must not have the given keyword to match 🙃
hasAttachment:"Boolean"
the "hasAttachment" property of the Email must be identical to the value given to match 📎
text:"String"
looks for the text in Emails. the server MUST look up text in the From, To, Cc, Bcc, and Subject header fields of the message, and SHOULD look inside any "text/*" or other body parts that the server can convert to text. the server MAY extend the search to any additional textual property 🔍
from:"String"
looks for the text in the From header field of the message 💌
to:"String"
looks for the text in the To header field of the message 📨
cc:"String"
looks for the text in the Cc header field of the message 📮
bcc:"String"
looks for the text in the Bcc header field of the message 🕵️
subject:"String"
looks for the text in the Subject header field of the message 🎯
body:"String"
looks for the text in one of the body parts of the message. the server MAY leave out MIME body parts with content media types other than "text/" and "message/" when it's matching. care should be taken to match based on the text content that viewers actually show an end user for that media type, or that's otherwise identified as right for search indexing. matching document metadata that's boring to an end user (like markup tag and attribute names) is undesirable 🙄
header:"String[]"
the array MUST contain either one or two elements. the first element is the name of the header field to match against. the second (optional) element is the text to look for in the header field value. if it's 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. (this is the same as splitting the object into one-property conditions and making them all children of an AND filter operator, bestie 🧠)
the exact semantics for matching "String" fields are deliberately not defined, so implementers have flexibility in how they index things, but these rules still apply ✨
- any syntactically correct encoded sections [RFC2047] of header fields with a known encoding SHOULD be decoded before trying to match text.
- when searching inside a "text/html" body part, any text that counts as markup rather than content SHOULD be ignored. that includes HTML tags and most attributes, anything inside the
<head>tag, Cascading Style Sheets (CSS), and JavaScript. attribute content meant to be shown to the user, likealtandtitle, SHOULD be considered in the search 🌈 - text SHOULD be matched in a case-insensitive manner 🔤
- text contained in either (but matched) single (') or double (") quotes SHOULD be treated as a phrase search. that means a match is required for that exact word or sequence of words, without the surrounding quotation marks 💬
within a phrase, to match one of the following characters you MUST escape it by putting a backslash () in front of it:
' " \- outside of a phrase, white space SHOULD be treated as dividing separate tokens that can be searched for separately, but they MUST all be present for the Email to match the filter 🧩
- tokens (not part of a phrase) MAY be matched on a whole-word basis using stemming. for example, a text search for "bus" would match "buses" but not "business" 🚌
4.4.2. Sorting ✨
okay so the sorting section is where the magic happens, bestie 💅 the "receivedAt" property MUST be supported, no exceptions, because it's the baseline sort that every client can count on 🫶
the rest of the list SHOULD be supported, which is a soft ask but honestly you want all of them 🌸 when you're sorting by a hasKeyword, allInThreadHaveKeyword, or someInThreadHaveKeyword sort, the Comparator object MUST also have a "keyword" property, otherwise it's giving nothing 💀
"receivedAt"(MUST): the"receivedAt"date as returned in the Email object 📬"size"(SHOULD): the"size"as returned in the Email object 🍓"from"(SHOULD): this is the"name"property, or if that's null or empty, the"email"property of the first EmailAddress object in the Email's"from"property. if there's still nothing, the value is the empty string 🦋"to"(SHOULD): same deal as"from"but with the Email's"to"property 🧚"subject"(SHOULD): this is the base subject of the message, as defined in Section 2.1 of [RFC5256] 💜"sentAt"(SHOULD): the"sentAt"property on the Email object 🌈"hasKeyword"(SHOULD): this MUST be considered true if the Email has the keyword given as an additional"keyword"property on the Comparator object, or false otherwise 🔥"allInThreadHaveKeyword"(SHOULD): this MUST be considered true for the Email if all of the Emails in the same Thread have the keyword given as an additional"keyword"property on the Comparator object ✨"someInThreadHaveKeyword"(SHOULD): this MUST be considered true for the Email if any of the Emails in the same Thread have the keyword given as an additional"keyword"property on the Comparator object 👑
the server MAY support sorting based on other properties too 🎀 and a client can figure out which properties are supported by checking the account's "capabilities" object (see Section 1.3) 🔍
example sort time 🫧
[{
"property": "someInThreadHaveKeyword",
"keyword": "$flagged",
"isAscending": false
}, {
"property": "subject",
"collation": "i;ascii-casemap"
}, {
"property": "receivedAt",
"isAscending": false
}]so this would sort Emails in flagged Threads first (the Thread counts as flagged if any Email in it is flagged 🚩), then by subject order, and then newest first for messages with the same subject 💖 if two Emails have identical values for all three properties, the order is server dependent but MUST be stable 🥹
4.4.3. Thread Collapsing 🧵
when "collapseThreads" is true, then after filtering and sorting the Email list, the list gets winnowed even more: any Email for a Thread id that's already been seen (when going through the list in order) gets removed 🙈 so a Thread shows up once in the result, sitting at the position of the first Email in the list that belongs to it (given the current sort and filter) ✨
4.5. Email/queryChanges 🌈
this is a standard /queryChanges method as described in [RFC8620], Section 5.6, with one extra request argument 💅
collapseThreads:"Boolean"(default:false) 🎀
the "collapseThreads" argument that was used with "Email/query" 🫶
4.6. Email/set 🛠️
this is a standard /set method as described in [RFC8620], Section 5.3 💖 "Email/set" covers:
- creating a draft ✍️
- changing the keywords of an Email (like unread or flagged status) 👀
- adding or removing an Email to or from Mailboxes (aka moving a message) 📦
- deleting Emails 🗑️
the format of the "keywords" and "mailboxIds" properties means that when you update an Email, you can either replace the whole set of keywords or Mailboxes (by setting the full value of the property), or add and remove individual ones using the JMAP patch syntax (see [RFC8620], Section 5.3 for the spec and Section 5.7 for an example) 🧩
okay now the tricky part 😭 because the Email object can say the same thing a bunch of different ways, when you're creating an Email there are rules so the [RFC5322] message is unambiguous. the following constraints apply to Email objects submitted for creation:
- The
"headers"property MUST NOT be given on either the top-level Email or an EmailBodyPart. the client has to set each header field as its own individual property 🙅♀️ - There MUST NOT be two properties that represent the same header field (like
"header:from"and"from") within the Email or a particular EmailBodyPart 🚫 - Header fields MUST NOT be specified in parsed forms that are forbidden for that particular field 🙃
- Header fields beginning with
"Content-"MUST NOT be specified on the Email object, only on EmailBodyPart objects 📎 - If a
"bodyStructure"property is given, there MUST NOT be"textBody","htmlBody", or"attachments"properties 🧱 - If given, the
"bodyStructure"EmailBodyPart MUST NOT contain a property representing a header field that's already defined on the top-level Email object 🫠 - If given, textBody MUST contain exactly one body part, and it MUST be of type
"text/plain"📝 - If given, htmlBody MUST contain exactly one body part, and it MUST be of type
"text/html"🌐 - Within an EmailBodyPart:
- the client may specify a partId OR a blobId, but not both. If a partId is given, this partId MUST be present in the
"bodyValues"property 🆔 - the
"charset"property MUST be omitted if a partId is given (the part's content is included in bodyValues, and the server may choose any appropriate encoding) 🔤 - the
"size"property MUST be omitted if a partId is given. If a blobId is given, it may be included but is ignored by the server (the size is actually calculated from the blob content itself) 📏 - a Content-Transfer-Encoding header field MUST NOT be given 🙅
- the client may specify a partId OR a blobId, but not both. If a partId is given, this partId MUST be present in the
- Within an EmailBodyValue object,
isEncodingProblemandisTruncatedMUST be either false or omitted 🧼
creation attempts that break any of this SHOULD be rejected with an "invalidProperties" error 🚨 however, a server MAY choose to modify the Email (like picking between conflicting headers, or using a different content-encoding, etc.) to comply with its requirements instead 🛠️
the server MAY also choose to set additional headers 🎁 if they're not included, the server MUST generate and set a Message-ID header field in conformance with [RFC5322], Section 3.6.4, and a Date header field in conformance with Section 3.6.1 📅
the final message generated may be invalid per RFC 5322 😬 for example, if it's a half-finished draft, the To header field may have a value that doesn't follow the required syntax for this header. the message gets checked for strict conformance when it's submitted for sending (see the EmailSubmission object description) 📤
destroying an Email removes it from all Mailboxes it belonged to 💀 to just send an Email to trash, simply change the "mailboxIds" property so it's in the Mailbox with a "role" property equal to "trash", and remove all the other Mailbox ids 🗑️✨
when emptying the trash, clients SHOULD NOT destroy Emails that are also in a Mailbox other than trash 🙅♀️ for those Emails, they SHOULD just remove the trash Mailbox from the Email 🫶
for successfully created Email objects, the "created" response contains the "id", "blobId", "threadId", and "size" properties of the object 🎉
the following extra SetError types are defined 👀
for "create":
"blobNotFound": at least one blob id given for an EmailBodyPart doesn't exist. An extra"notFound"property of type"Id[]"MUST be included in the SetError object containing every"blobId"referenced by an EmailBodyPart that couldn't be found on the server 🔍
for "create" and "update":
"tooManyKeywords": the change to the Email's keywords would exceed a server-defined maximum 🏷️"tooManyMailboxes": the change to the set of Mailboxes that this Email is in would exceed a server-defined maximum 📚
4.7. Email/copy 🪞
this is a standard /copy method as described in [RFC8620], Section 5.4, except only the "mailboxIds", "keywords", and "receivedAt" properties may be set during the copy 💅 this method cannot modify the message represented by the Email 🔒
the server MAY forbid two Email objects with identical message content [RFC5322], or even just the same Message-ID [RFC5322], to coexist within an account 🙈 if the target account already has the Email, the copy will be rejected with a standard "alreadyExists" error 😭
for successfully copied Email objects, the "created" response contains the "id", "blobId", "threadId", and "size" properties of the new object 🎀
4.8. Email/import 📬
okay bestie, Email/import is how you add messages [RFC5322] into the set of Emails in an account 💖 The server MUST support messages with Email Address Internationalization (EAI) headers [RFC6532] 💅 The messages must first be uploaded as blobs using the standard upload mechanism 🫶 Here's what the method takes:
accountId: "Id"— The id of the account to use.ifInState: "String|null"— This is a state string as returned by theEmail/getmethod. If it's supplied, the string must match the current state of the account referenced by the accountId, or the method gets aborted and a "stateMismatch" error comes back 🙈 If it's null, any changes get applied to the current state.emails: "Id[EmailImport]"— A map of creation id (client specified) to EmailImport objects 🎀
An EmailImport object has these properties:
blobId: "Id"— The id of the blob containing the raw message [RFC5322].mailboxIds: "Id[Boolean]"— The ids of the Mailboxes to assign this Email to. At least one Mailbox MUST be given 📁keywords: "String[Boolean]" (default: {})— The keywords to apply to the Email 🏷️receivedAt: "UTCDate" (default: time of most recent Received header, or time of import on server if none)— The "receivedAt" date to set on the Email ⏰
Each Email to import is its own atomic unit, so it can succeed or fail all by itself 🦋 When it succeeds, you get a brand new Email object made from the data behind the blobId, with the Mailboxes, keywords, and receivedAt date you asked for ✨
The server MAY forbid two Email objects with the same exact content [RFC5322], or even just the same Message-ID [RFC5322], from living together in one account 👀 If it does that, it MUST reject the import of the duplicate with an "alreadyExists" SetError. An "existingId" property of type "Id" MUST be included on that SetError object, holding the id of the existing Email 🔥 If duplicates are allowed, the newly created Email object MUST have a separate id and its own independent mutable properties, separate from the existing one 🌈
If the "blobId", "mailboxIds", or "keywords" properties are invalid (say, missing, the wrong type, or an id that isn't found), the server MUST reject the import with an "invalidProperties" SetError 💀
If the Email can't be imported because it would take the account over quota, the import should be rejected with an "overQuota" SetError 🍓
If the blob referenced isn't a valid message [RFC5322], the server MAY modify the message to fix errors, like removing NUL octets or fixing invalid headers 🧚 If it does that, the "blobId" on the response MUST represent the new representation, so it has to be different from the "blobId" on the EmailImport object. Or, alternatively, the server MAY reject the import with an "invalidEmail" SetError 💜
The response has these arguments:
accountId: "Id"— The id of the account used for this call.oldState: "String|null"— The state string that would have been returned by "Email/get" on this account before making the requested changes, or null if the server doesn't know what the previous state string was.newState: "String"— The state string that will now be returned by "Email/get" on this account.created: "Id[Email]|null"— A map of the creation id to an object containing the "id", "blobId", "threadId", and "size" properties for each successfully imported Email, or null if there aren't any 🎉notCreated: "Id[SetError]|null"— A map of the creation id to a SetError object for each Email that failed to be created, or null if everything worked. The possible errors are defined above 🥺
The following additional error may be returned instead of the "Email/import" response:
- "stateMismatch": An "ifInState" argument was supplied, and it does not match the current state.
4.9. Email/parse 🔍
This method lets you parse blobs as messages [RFC5322] to get Email objects 🌸 The server MUST support messages with EAI headers [RFC6532] 💅 It's super handy for parsing and displaying attached messages without importing them as top-level Email objects in the mail store in their own right 🫶
The following metadata properties on the Email objects will be null if requested:
idmailboxIdskeywordsreceivedAt
The "threadId" property of the Email MAY be present if the server can work out which Thread the Email would be assigned to were it imported 🧵 Otherwise, it's null when fetched too.
The "Email/parse" method takes these arguments:
accountId: "Id"— The id of the account to use.blobIds: "Id[]"— The ids of the blobs to parse.properties: "String[]"— If supplied, only the properties listed in the array come back for each Email object. If omitted, it defaults to:
[ "messageId", "inReplyTo", "references", "sender", "from", "to",
"cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment",
"preview", "bodyValues", "textBody", "htmlBody", "attachments" ]bodyProperties: "String[]"— A list of properties to fetch for each EmailBodyPart returned. If omitted, it defaults to the same value as the "Email/get" "bodyProperties" default argument 🍓fetchTextBodyValues: "Boolean"(default: false) — If true, the "bodyValues" property includes any "text/*" part in the "textBody" property.fetchHTMLBodyValues: "Boolean"(default: false) — If true, the "bodyValues" property includes any "text/*" part in the "htmlBody" property.fetchAllBodyValues: "Boolean"(default: false) — If true, the "bodyValues" property includes any "text/*" part in the "bodyStructure" property.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 doesn't exceed this number of octets in size. If it's 0 (the default), no truncation happens ✂️
The server MUST ensure the truncation results in valid UTF-8 and doesn't happen 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's no requirement for the truncated form to be a balanced tree or valid HTML (honestly, the original source may well be neither of those things 🙈).
The response has these arguments:
accountId: "Id"— The id of the account used for the call.parsed: "Id[Email]|null"— A map of blob id to parsed Email representation for each successfully parsed blob, or null if there aren't any.notParsable: "Id[]|null"— A list of the ids given that corresponded to blobs that couldn't be parsed as Emails, or null if none.notFound: "Id[]|null"— A list of blob ids given that couldn't be found, or null if none.
As mentioned above, parsed forms of headers may only be used on appropriate header fields. Trying to fetch a form that's 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 the one used in the request 🎀
4.10. Examples ✨
okay so, a client logs in for the first time 🦋 It fetches the set of Mailboxes first. Now it wants to show the inbox to the user, which we'll pretend has Mailbox id "fb666a55". The inbox might be (very!) huge, but the user's screen is only so big, so the client just loads the Threads it needs to fill the screen, then loads more only when the user scrolls 📜 The client sends this request:
[[ "Email/query",{
"accountId": "ue150411c",
"filter": {
"inMailbox": "fb666a55"
},
"sort": [{
"isAscending": false,
"property": "receivedAt"
}],
"collapseThreads": true,
"position": 0,
"limit": 30,
"calculateTotal": true
}, "0" ],
[ "Email/get", {
"accountId": "ue150411c",
"#ids": {
"resultOf": "0",
"name": "Email/query",
"path": "/ids"
},
"properties": [
"threadId"
]
}, "1" ],
[ "Thread/get", {
"accountId": "ue150411c",
"#ids": {
"resultOf": "1",
"name": "Email/get",
"path": "/list/*/threadId"
}
}, "2" ],
[ "Email/get", {
"accountId": "ue150411c",
"#ids": {
"resultOf": "2",
"name": "Thread/get",
"path": "/list/*/emailIds"
},
"properties": [
"threadId",
"mailboxIds",
"keywords",
"hasAttachment",
"from",
"subject",
"receivedAt",
"size",
"preview"
]
}, "3" ]]Let's break down the 4 method calls and see what they're doing 👀
"0": This asks the server for the ids of the first 30 Email objects in the inbox, sorted newest first, ignoring Emails from the same Thread as a newer Email in the Mailbox (i.e., it's the first 30 unique Threads) 💖
"1": Now we use a back-reference to fetch the Thread ids for each of these Email ids 🔗
"2": Another back-reference fetches the Thread object for each of these Thread ids 🧵
"3": Finally, we fetch the info we need to display the Mailbox listing (but no more!) for every Email in each of these 30 Threads 💅 The client can aggregate this data for display, for example by showing the Thread as "flagged" if any of the Emails in it has the $flagged keyword 🚩
The response from the server may look something like this:
[[ "Email/query", {
"accountId": "ue150411c",
"queryState": "09aa9a075588-780599:0",
"canCalculateChanges": true,
"position": 0,
"total": 115,
"ids": [ "Ma783e5cdf5f2deffbc97930a",
"M9bd17497e2a99cb345fc1d0a", ... ]
}, "0" ],
[ "Email/get", {
"accountId": "ue150411c",
"state": "780599",
"list": [{
"id": "Ma783e5cdf5f2deffbc97930a",
"threadId": "T36703c2cfe9bd5ed"
}, {
"id": "M9bd17497e2a99cb345fc1d0a",
"threadId": "T0a22ad76e9c097a1"
}, ... ],
"notFound": []
}, "1" ],
[ "Thread/get", {
"accountId": "ue150411c",
"state": "22a8728b",
"list": [{
"id": "T36703c2cfe9bd5ed",
"emailIds": [ "Ma783e5cdf5f2deffbc97930a" ]}, { "id": "T0a22ad76e9c097a1", "emailIds": [ "M3b568670a63e5d100f518fa5", "M9bd17497e2a99cb345fc1d0a" ] }, ... ], "notFound": [] }, "2" ], [ "Email/get", { "accountId": "ue150411c", "state": "780599", "list": [{ "id": "Ma783e5cdf5f2deffbc97930a", "threadId": "T36703c2cfe9bd5ed", "mailboxIds": { "fb666a55": true }, "keywords": { "$seen": true, "$flagged": true }, "hasAttachment": true, "from": [{ "email": "jdoe@example.com", "name": "Jane Doe" }], "subject": "The Big Reveal", "receivedAt": "2018-06-27T00:20:35Z", "size": 175047, "preview": "As you may be aware, we are required to prepare a presentation where we wow a panel of 5 random members of the public, on or before 30 June each year. We have drafted..." }, ... ], "notFound": [] }, "3" ]]
Okay, now picture this 🎀: on another device, the user marks the first Email as unread 👀. The request looks like this:
[[ "Email/set", {
"accountId": "ue150411c",
"update": {
"Ma783e5cdf5f2deffbc97930a": {
"keywords/$seen": null
}
}
}, "0" ]]The server applies it and sends back the success response 💖:
[[ "Email/set", {
"accountId": "ue150411c",
"oldState": "780605",
"newState": "780606",
"updated": {
"Ma783e5cdf5f2deffbc97930a": null
},
...
}, "0" ]]Then the user deletes a few Emails, and a brand new message lands 📬. Back on our original machine, a push update tells us the state string for Email is now "780800". That doesn't match what the client has, so it asks for the changes 🫶:
[[ "Email/changes", {
"accountId": "ue150411c",
"sinceState": "780605",
"maxChanges": 50
}, "3" ],
[ "Email/queryChanges", {
"accountId": "ue150411c",
"filter": {
"inMailbox": "fb666a55"
},
"sort": [{
"property": "receivedAt",
"isAscending": false
}],
"collapseThreads": true,
"sinceQueryState": "09aa9a075588-780599:0",
"upToId": "Mc2781d5e856a908d8a35a564",
"maxChanges": 25,
"calculateTotal": true
}, "11" ]]The response:
[[ "Email/changes", {
"accountId": "ue150411c",
"oldState": "780605",
"newState": "780800",
"hasMoreChanges": false,
"created": [ "Me8de6c9f6de198239b982ea2" ],
"updated": [ "Ma783e5cdf5f2deffbc97930a" ],
"destroyed": [ "M9bd17497e2a99cb345fc1d0a", ... ]
}, "3" ],
[ "Email/queryChanges", {
"accountId": "ue150411c",
"oldQueryState": "09aa9a075588-780599:0",
"newQueryState": "e35e9facf117-780615:0",
"added": [{
"id": "Me8de6c9f6de198239b982ea2",
"index": 0
}],
"removed": [ "M9bd17497e2a99cb345fc1d0a" ],
"total": 115
}, "11" ]]The client can update its local cache of the query results by removing M9bd17497e2a99cb345fc1d0a and then splicing in Me8de6c9f6de198239b982ea2 at position 0. It doesn't have the data for this new Email yet, so it'll fetch it next. (It could also have done that in the same request using back-references ✨.)
It knows something has changed about Ma783e5cdf5f2deffbc97930a, so it'll refetch the Mailbox ids and keywords (the only mutable properties) for this Email too 💅.
The user starts composing a new Email 📝. The email is plaintext, and the client knows it's in English, so it adds this metadata to the body part. The user saves a draft while the composition is still in progress, and the client sends:
[[ "Email/set", {
"accountId": "ue150411c",
"create": {
"k192": {
"mailboxIds": {
"2ea1ca41b38e": true
},
"keywords": {
"$seen": true,
"$draft": true
},
"from": [{
"name": "Joe Bloggs",
"email": "joe@example.com"
}],
"subject": "World domination",
"receivedAt": "2018-07-10T01:03:11Z",
"sentAt": "2018-07-10T11:03:11+10:00",
"bodyStructure": {
"type": "text/plain",
"partId": "bd48",
"header:Content-Language": "en"
},
"bodyValues": {
"bd48": {
"value": "I have the most brilliant plan. Let me tell
you all about it. What we do is, we",
"isTruncated": false
}
}
}
}
}, "0" ]]The server creates the message and sends the success response:
[[ "Email/set", {
"accountId": "ue150411c",
"oldState": "780823",
"newState": "780839",
"created": {
"k192": {
"id": "Mf40b5f831efa7233b9eb1c7f",
"blobId": "Gf40b5f831efa7233b9eb1c7f8f97d84eeeee64f7",
"threadId": "Td957e72e89f516dc",
"size": 359
}
},
...
}, "0" ]]The message created on the server looks something like this 🧚:
Message-Id: <bbce0ae9-58be-4b24-ac82-deb840d58016@sloti7d1t02>
User-Agent: Cyrus-JMAP/3.1.6-736-gdfb8e44
Mime-Version: 1.0
Date: Tue, 10 Jul 2018 11:03:11 +1000
From: "Joe Bloggs" <joe@example.com>
Subject: World domination
Content-Language: en
Content-Type: text/plain
I have the most brilliant plan. Let me tell you all about it. What we
do is, weThe user adds a recipient and converts the message to HTML so they can add formatting, then saves an updated draft 🌸:
[[ "Email/set", {
"accountId": "ue150411c",
"create": {
"k1546": {
"mailboxIds": {
"2ea1ca41b38e": true
},
"keywords": {
"$seen": true,
"$draft": true
},
"from": [{
"name": "Joe Bloggs",
"email": "joe@example.com"
}],
"to": [{
"name": "John",
"email": "john@example.com"
}],
"subject": "World domination",
"receivedAt": "2018-07-10T01:05:08Z",
"sentAt": "2018-07-10T11:05:08+10:00",
"bodyStructure": {
"type": "multipart/alternative",
"subParts": [{
"partId": "a49d",
"type": "text/html",
"header:Content-Language": "en"
}, {
"partId": "bd48",
"type": "text/plain",
"header:Content-Language": "en"
}]
},
"bodyValues": {
"bd48": {
"value": "I have the most brilliant plan. Let me tell
you all about it. What we do is, we",
"isTruncated": false
},
"a49d": {
"value": "<!DOCTYPE html><html><head><title></title>
<style type=\"text/css\">div{font-size:16px}</style></head>
<body><div>I have the most <b>brilliant</b> plan. Let me
tell you all about it. What we do is, we</div></body>
</html>",
"isTruncated": false
}
}
}
},
"destroy": [ "Mf40b5f831efa7233b9eb1c7f" ]
}, "0" ]]The server creates the new draft, deletes the old one, and sends the success response:
[[ "Email/set", {
"accountId": "ue150411c",
"oldState": "780839",
"newState": "780842",
"created": {
"k1546": {
"id": "Md45b47b4877521042cec0938",
"blobId": "Ge8de6c9f6de198239b982ea214e0f3a704e4af74",
"threadId": "Td957e72e89f516dc",
"size": 11721
}
},
"destroyed": [ "Mf40b5f831efa7233b9eb1c7f" ],
...
}, "0" ]]Next up, the client moves this draft to a different account 🧳. The only way to do this is via the Email/copy method. It MUST set a new mailboxIds property, since the current value will not be valid Mailbox ids in the destination account:
[[ "Email/copy", {
"fromAccountId": "ue150411c",
"accountId": "u6c6c41ac",
"create": {
"k45": {
"id": "Md45b47b4877521042cec0938",
"mailboxIds": {
"75a4c956": true
}
}
},
"onSuccessDestroyOriginal": true
}, "0" ]]The server successfully copies the Email and deletes the original. Because of the implicit call to Email/set, there are two responses to the single method call, both with the same method call id 👯:
[[ "Email/copy", {
"fromAccountId": "ue150411c",
"accountId": "u6c6c41ac",
"oldState": "7ee7e9263a6d",
"newState": "5a0d2447ed26",
"created": {
"k45": {
"id": "M138f9954a5cd2423daeafa55",
"blobId": "G6b9fb047cba722c48c611e79233d057c6b0b74e8",
"threadId": "T2f242ea424a4079a",
"size": 11721
}
},
"notCreated": null
}, "0" ],
[ "Email/set", {
"accountId": "ue150411c",
"oldState": "780842",
"newState": "780871",
"destroyed": [ "Md45b47b4877521042cec0938" ],
...
}, "0" ]]5. Search Snippets 🔍
When doing a search on a String property, the client may want to show the relevant bit of the body that matches the search as a preview, and highlight any matching terms in that preview and in the subject of the Email. That's exactly what search snippets are for 💜.
A SearchSnippet object has the following properties:
emailId: "Id"The Email id the snippet applies to.subject: "String|null"If text from the filter matches the subject, this is the subject of the Email with the following transformations:- Any instance of the following three characters MUST be replaced by an appropriate HTML entity:
&(ampersand),<(less-than sign), and>(greater-than sign) [HTML]. Other characters MAY also be replaced with an HTML entity form. - The matching words/phrases from the filter are wrapped in HTML
<mark></mark>tags. If the subject does not match text from the filter, this property is null.
- Any instance of the following three characters MUST be replaced by an appropriate HTML entity:
preview: "String|null"If text from the filter matches the plaintext or HTML body, this is the relevant section of the body (converted to plaintext if originally HTML), with the same transformations as thesubjectproperty. It MUST NOT be bigger than 255 octets in size. If the body does not contain a match for the text from the filter, this property is null.
What counts as a relevant section of the body for the preview is up to the server 🙌. If the server is unable to determine search snippets, it MUST return null for both the subject and preview properties.
Note that unlike most data types, a SearchSnippet DOES NOT have a property called id 🙈.
Here's the JMAP method that's supported for this:
5.1. SearchSnippet/get
okay bestie, to fetch search snippets you make a call to "SearchSnippet/get" 💅 It takes these arguments:
accountId: "Id": the id of the account to use 🎀filter: "FilterOperator|FilterCondition|null": the same filter you passed to"Email/query". See Section 4.4 for the full tea on that method ✨emailIds: "Id[]": the ids of the Emails you want snippets for 🦋
The response comes back with these arguments:
accountId: "Id": the id of the account used for the call 💖list: "SearchSnippet[]": an array of SearchSnippet objects for the Email ids you requested. This may not be in the same order as the ids you sent in, so don't panic if the order is chaotic 🙈notFound: "Id[]|null": an array of the Email ids you asked for that couldn't be found, ornullif every id was found 🌸
okay so here's the lowkey important bit 👀 Snippets are derived from the message content, and the algorithm for doing that could change over time. That means fetching the same snippets a second time MAY return a different result. The old value isn't considered incorrect though, so there's no state string or update mechanism needed. no cap, that's a vibe ✨
The following additional errors may be returned instead of the "SearchSnippet/get" response:
"requestTooLarge": the number of"emailIds"the client requested is more than the server is willing to process in a single method call 😭"unsupportedFilter": the server can't process the given"filter"for any reason 💀
5.2. Example
Here we did an "Email/query" to search for any Email in the account containing the word "foo". Now we're fetching the search snippets for some of the ids that came back in the results 🧚
[[ "SearchSnippet/get", {
"accountId": "ue150411c",
"filter": {
"text": "foo"
},
"emailIds": [
"M44200ec123de277c0c1ce69c",
"M7bcbcb0b58d7729686e83d99",
"M28d12783a0969584b6deaac0",
...
]
}, "0" ]]Example response:
[[ "SearchSnippet/get", {
"accountId": "ue150411c",
"list": [{
"emailId": "M44200ec123de277c0c1ce69c",
"subject": null,
"preview": null
}, {
"emailId": "M7bcbcb0b58d7729686e83d99",
"subject": "The <mark>Foo</mark>sball competition",
"preview": "...year the <mark>foo</mark>sball competition will
be held in the Stadium de ..."
}, {
"emailId": "M28d12783a0969584b6deaac0",
"subject": null,
"preview": "...the <mark>Foo</mark>/bar method results often
returns <1 widget rather than the complete..."
},
...
],
"notFound": null
}, "0" ]]6. Identities ✨
okay so an Identity object stores info about an email address or domain the user is allowed to send from 💌 It has these properties:
id: "Id"(immutable; server-set): the id of the Identity 🪪name: "String"(default:""): the "From" name the client SHOULD use when creating a new Email from this Identity 💅email: "String"(immutable): the "From" email address the client MUST use when creating a new Email from this Identity. If the mailbox part of the address (the bit before the "@") is just the single character*, like"*@example.com", the client may use any valid address ending in that domain, like"foo@example.com". it's giving flexibility 🦋replyTo: "EmailAddress[]|null"(default:null): the Reply-To value the client SHOULD set when creating a new Email from this Identity 🎀bcc: "EmailAddress[]|null"(default:null): the Bcc value the client SHOULD set when creating a new Email from this Identity 🙈textSignature: "String"(default:""): a signature the client SHOULD insert into new plaintext messages sent from this Identity. Clients MAY ignore this and/or combine it with a client-specific signature preference 🌸htmlSignature: "String"(default:""): a signature the client SHOULD insert into new HTML messages sent from this Identity. This text MUST be an HTML snippet to be inserted into the"<body></body>"section of the HTML. Clients MAY ignore this and/or combine it with a client-specific signature preference 💜mayDelete: "Boolean"(server-set): is the user allowed to delete this Identity? Servers may wish to set this to false for the user's username or other default address. Attempts to destroy an Identity withmayDelete: falsewill be rejected with a standard"forbidden"SetError 🔥
the Identity's email property is where the "Addresses" header form lives. For the definition of EmailAddress, check the "Addresses" header form description in the Email object (Section 4.1.2.3) 👀
Multiple identities with the same email address MAY exist, so the user can pick between different settings (like different names or signatures) 🧚
The following JMAP methods are supported. 💖
6.1. Identity/get
This is a standard "/get" method as described in [RFC8620], Section 5.1. The "ids" argument may be null to fetch all at once 🌈
6.2. Identity/changes
This is a standard "/changes" method as described in [RFC8620], Section 5.2. 🦋
6.3. Identity/set
This is a standard "/set" method as described in [RFC8620], Section 5.3. The following extra SetError types are defined:
For "create":
"forbiddenFrom": the user is not allowed to send from the address given as the"email"property of the Identity 🙅♀️
6.4. Example
Request:
[ "Identity/get", {
"accountId": "acme"
}, "0" ]with response:
[ "Identity/get", {
"accountId": "acme",
"state": "99401312ae-11-333",
"list": [
{
"id": "XD-3301-222-11_22AAz",
"name": "Joe Bloggs",
"email": "joe@example.com",
"replyTo": null,
"bcc": [{
"name": null,
"email": "joe+archive@example.com"
}],
"textSignature": "-- \nJoe Bloggs\nMaster of Email",
"htmlSignature": "<div><b>Joe Bloggs</b></div>
<div>Master of Email</div>",
"mayDelete": false
},
{
"id": "XD-9911312-11_22AAz",
"name": "Joe B",
"email": "*@example.com",
"replyTo": null,
"bcc": null,
"textSignature": "",
"htmlSignature": "",
"mayDelete": true
}
],
"notFound": []
}, "0" ]7. Email Submission ✨
okay bestie, this is the part where the email actually gets SENT 📮💅 an EmailSubmission object is basically the receipt for "hey server, please deliver this Email to these people" 🦋 it's giving outbox energy and it is so iconic 😭
It has the following properties:
- id: "Id" (immutable; server-set) 🎀 The id of the EmailSubmission. Server picks it, no touching 🙈
- identityId: "Id" (immutable) 🌸 The id of the Identity to associate with this submission. Which "you" is sending, basically 💜
- emailId: "Id" (immutable) 💌 The id of the Email to send. The Email being sent does not have to be a draft, for example, when "redirecting" an existing Email to a different address. So yes, you can totally forward an old email to someone new, main character behavior 👑
- threadId: "Id" (immutable; server-set) 🧵 The Thread id of the Email to send. The server copies this from the "threadId" property of the Email referenced by the "emailId". Automatic, no drama ✨
- envelope: "Envelope|null" (immutable) 📫 Information for use when sending via SMTP. The envelope is the behind-the-scenes stuff, the address label on the outside of the package 📦 An Envelope object has the following properties:
- mailFrom: "Address" 💁 The email address to use as the return address in the SMTP submission, plus any parameters to pass with the MAIL FROM address. The JMAP server MAY allow the address to be the empty string. So the return address can be blank if the server is cool with that 🫶
When a JMAP server performs an SMTP message submission, it MAY use the same id string for the ENVID parameter [RFC3461] and the EmailSubmission object id. Servers that do this MAY replace a client-provided value for ENVID with a server-provided value. So the server can reuse the submission id as the ENVID, and it can even overwrite whatever you sent for ENVID 🔥
- rcptTo: "Address[]" 🎯 The email addresses to send the message to, and any RCPT TO parameters to pass with the recipient. The list of who's getting it 🌈
An Address object has the following properties:
- email: "String" 📧 The email address being represented by the object. This is a "Mailbox" as used in the Reverse-path or Forward-path of the MAIL FROM or RCPT TO command in [RFC5321]. Just the address, nothing extra 🌸
- parameters: "Object|null" 🧁 Any parameters to send with the email address (either mail-parameter or rcpt-parameter as appropriate, as specified in [RFC5321]). If supplied, each key in the object is a parameter name, and the value is either the parameter value (type "String") or null if the parameter does not take a value. For both name and value, any xtext or unitext encodings are removed (see [RFC3461] and [RFC6533]) and JSON string encoding is applied. So the extra SMTP add-ons go here, encoded and decoded in the proper order, very precise 🤓
If the "envelope" property is null or omitted on creation, the server MUST generate this from the referenced Email as follows:
- "mailFrom": The email address in the Sender header field, if present; otherwise, it's the email address in the From header field, if present. In either case, no parameters are added.
If multiple addresses are present in one of these header fields, or there is more than one Sender/From header field, the server SHOULD reject the EmailSubmission as invalid; otherwise, it MUST take the first address in the last Sender/From header field.
If the address found from this is not allowed by the Identity associated with this submission, the "email" property from the Identity MUST be used instead. Rules are rules, bestie, the Identity's email wins if the header address isn't allowed 💅
- "rcptTo": The deduplicated set of email addresses from the To, Cc, and Bcc header fields, if present, with no parameters for any of them. Everyone from To, Cc, and Bcc, but only once each, no doubles 💖
- sendAt: "UTCDate" (immutable; server-set) ⏰ The date the submission was/will be released for delivery. If the client successfully used FUTURERELEASE [RFC4865] with the submission, this MUST be the time when the server will release the message; otherwise, it MUST be the time the EmailSubmission was created. So if you scheduled it, sendAt is the scheduled time, and if not, it's the moment you hit send 🚀
- undoStatus: "String" ↩️ This represents whether the submission may be canceled. This is server set on create and MUST be one of the following values:
- "pending": It may be possible to cancel this submission. 🤞
- "final": The message has been relayed to at least one recipient in a manner that cannot be recalled. It is no longer possible to cancel this submission. 💀
- "canceled": The submission was canceled and will not be delivered to any recipient. 🙅♀️
On systems that do not support unsending, the value of this property will always be "final". On systems that do support canceling submission, it will start as "pending" and MAY transition to "final" when the server knows it definitely cannot recall the message, but it MAY just remain "pending". If in pending state, a client can attempt to cancel the submission by setting this property to "canceled"; if the update succeeds, the submission was successfully canceled, and the message has not been delivered to any of the original recipients. So unsend is a vibe only if the server actually supports it, otherwise it's "final" and that's that 😭
- deliveryStatus: "String[DeliveryStatus]|null" (server-set) 📊 This represents the delivery status for each of the submission's recipients, if known. This property MAY not be supported by all servers, in which case it will remain null. Servers that support it SHOULD update the EmailSubmission object each time the status of any of the recipients changes, even if some recipients are still being retried. Tracking the tea on every recipient, live 🍵
This value is a map from the email address of each recipient to a DeliveryStatus object.
A DeliveryStatus object has the following properties:
- smtpReply: "String" 💬 The SMTP reply string returned for this recipient when the server last tried to relay the message, or in a later Delivery Status Notification (DSN, as defined in [RFC3464]) response for the message. This SHOULD be the response to the RCPT TO stage, unless this was accepted and the message as a whole was rejected at the end of the DATA stage, in which case the DATA stage reply SHOULD be used instead. So it's the server's exact words back, roughly 🙈
Multi-line SMTP responses should be concatenated to a single string as follows:
- The hyphen following the SMTP code on all but the last line is replaced with a space.
- Any prefix in common with the first line is stripped from lines after the first.
- CRLF is replaced by a space.
For example:
550-5.7.1 Our system has detected that this message is
550 5.7.1 likely spam.would become:
550 5.7.1 Our system has detected that this message is likely spam.For messages relayed via an alternative to SMTP, the server MAY generate a synthetic string representing the status instead. If it does this, the string MUST be of the following form:
- A 3-digit SMTP reply code, as defined in [RFC5321], Section 4.2.3.
- Then a single space character.
- Then an SMTP Enhanced Mail System Status Code as defined in [RFC3463], with a registry defined in [RFC5248].
- Then a single space character.
- Then an implementation-specific information string with a human-readable explanation of the response.
So if there's no real SMTP in the picture, the server can fake a reply, but it has to follow this exact pattern 🧩
- delivered: "String" 📬 Represents whether the message has been successfully delivered to the recipient. This MUST be one of the following values:
- "queued": The message is in a local mail queue and the status will change once it exits the local mail queues. The "smtpReply" property may still change. Still in line at the post office 🏤
- "yes": The message was successfully delivered to the mail store of the recipient. The "smtpReply" property is final. Delivered, slay 🎉
- "no": Delivery to the recipient permanently failed. The "smtpReply" property is final. Rip, it bounced 💔
- "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. Nobody knows, it's a mystery 🕵️♀️
Note that successful relaying to an external SMTP server SHOULD NOT be taken as an indication that the message has successfully reached the final mail store. In this case though, the server may receive a DSN response, if requested. Handing it off to another server is NOT the same as it landing in the inbox, so don't get too hyped 😤
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. So a DSN saying "delivered" means yes, "failed" means no, and any other DSN leaves it alone 📩
The server MAY also set this property based on other feedback channels. Other clues count too 🔍
- displayed: "String" 👀 Represents whether the message has been displayed to the recipient. This MUST be one of the following values:
- "unknown": The display status is unknown. This is the initial value. Default vibes 🫠
- "yes": The recipient's system claims the message content has been displayed to the recipient. Note that there is no guarantee that the recipient has noticed, read, or understood the content. Their device says they saw it, but who knows if they actually read it 😂
If a Message Disposition Notification (MDN) is received for this recipient with Disposition-Type (as per [RFC8098], Section 3.2.6.2) equal to "displayed", this property SHOULD be set to "yes". The server MAY also set this property based on other feedback channels. An MDN saying "displayed" flips this to "yes" 👁️
- dsnBlobIds: "Id[]" (server-set) 🗂️ A list of blob ids for DSNs [RFC3464] received for this submission, in order of receipt, oldest first. The blob is the whole MIME message (with a top-level content-type of "multipart/report"), as received. A little archive of every bounce-or-receipt note, oldest first, stored exactly as they came in 📚
- mdnBlobIds: "Id[]" (server-set) 🗃️ A list of blob ids for MDNs [RFC8098] received for this submission, in order of receipt, oldest first. The blob is the whole MIME message (with a top-level content-type of "multipart/report"), as received. Same deal, but for the read-receipt notes 🧾
JMAP servers MAY choose not to expose DSN and MDN responses as Email objects if they correlate to an EmailSubmission object. It SHOULD only do this if it exposes them in the "dsnBlobIds" and "mdnblobIds" fields instead, and it expects the user to be using clients capable of fetching and displaying delivery status via the EmailSubmission object. So the server can hide these notes as Emails, but only if it shows them in the blob fields instead, and only if you're using a client that knows how to read delivery status 🧠
For efficiency, a server MAY destroy EmailSubmission objects at any time after the message is successfully sent or after it has finished retrying to send the message. For very basic SMTP proxies, this MAY be immediately after creation, as it has no way to assign a real id and return the information again if fetched later. Cleanup time! The server can delete these once they're done, and very basic proxies might delete them right away since they can't keep track of an id anyway 🧹
The following JMAP methods are supported.
7.1. EmailSubmission/get
This is a standard "/get" method as described in [RFC8620], Section 5.1. Nothing new here, just the usual fetch 🍓
7.2. EmailSubmission/changes
This is a standard "/changes" method as described in [RFC8620], Section 5.2. Same story, the usual "what's changed since last time" check 🌙
7.3. EmailSubmission/query 💌
okay so this one is the standard "/query" method, same as the one in [RFC8620], Section 5.5. nothing new here, you already know the vibe 🫶
A FilterCondition object has these properties, and any of them can be left out 🎀
identityIds: "Id[]": the EmailSubmission"identityId"property has to be in this list for the condition to match 🦋emailIds: "Id[]": the EmailSubmission"emailId"property has to be in this list for the condition to match 💜threadIds: "Id[]": the EmailSubmission"threadId"property has to be in this list for the condition to match 🧚undoStatus: "String": the EmailSubmission"undoStatus"property must be identical to the value given to match 🌸before: "UTCDate": the"sendAt"property of the EmailSubmission object must be before this date-time to match ⭐after: "UTCDate": the"sendAt"property of the EmailSubmission object must be the same as or after this date-time to match 🌈
an EmailSubmission object matches the FilterCondition if and only if all of the given conditions match 💅 and if zero properties are specified, it's automatically true for all objects. iconic, right? 👑
the following EmailSubmission properties MUST be supported for sorting 🔥
"emailId""threadId""sentAt"
7.4. EmailSubmission/queryChanges 🦋
this is the standard "/queryChanges" method, described in [RFC8620], Section 5.6. same energy as the last one, bestie ✨
7.5. EmailSubmission/set 🚀
this is the standard "/set" method from [RFC8620], Section 5.3, with two extra request arguments that are giving main character energy 💖
onSuccessUpdateEmail: "Id[PatchObject]|null": a map of EmailSubmission id to an object holding properties to update on the Email object that the EmailSubmission references, if the create/update/destroy succeeds. (for references to EmailSubmissions created in the same "/set" invocation, this works as a creation-reference, so the id is the creation id prefixed with a "#".) 🌸onSuccessDestroyEmail: "Id[]|null": a list of EmailSubmission ids where the Email with the matching"emailId"should be destroyed if the create/update/destroy succeeds. (for references to EmailSubmission creations, this is equivalent to a creation-reference, so the id is the creation id prefixed with a "#".) 💀
after every create/update/destroy item in the "EmailSubmission/set" invocation has been processed, a single implicit "Email/set" call MUST be made to handle any changes requested in those two arguments. the response to that MUST be returned after the "EmailSubmission/set" response 🫶
an Email gets sent by creating an EmailSubmission object. when processing each create, the server must check that the message is valid, and that the user has sufficient authorisation to send it. if the creation works, the message goes to the recipients in the envelope "rcptTo" parameter 📬 the server MUST remove any Bcc header field present on the message during delivery. the server MAY add or remove other header fields from the submitted message, or make further alterations in line with the server's policy during delivery 🎀
if the referenced Email gets destroyed at any point after the EmailSubmission object is created, this MUST NOT change how the submission behaves (it doesn't cancel a future send, so don't panic 🙈). the "emailId" and "threadId" properties of the EmailSubmission object stick around, but trying to fetch them with a standard "Email/get" call will return a "notFound" error if the objects have been destroyed 🥲
similarly, destroying an EmailSubmission object MUST NOT affect the deliveries it represents. it just removes the record of the submission 🧹 the server MAY automatically destroy EmailSubmission objects after some time or in response to other triggers, and MAY forbid the client from manually destroying EmailSubmission objects 🌈
if the message to be sent is larger than the server supports sending, a standard "tooLarge" SetError MUST be returned. a "maxSize" "UnsignedInt" property MUST be present on the SetError, specifying the maximum size of a message that may be sent, in octets 📏
if the Email or Identity id given can't be found, the submission creation is rejected with a standard "invalidProperties" SetError 🙅♀️
the following extra SetError types are defined. obsessed with how organised this is 😭
for "create":
"invalidEmail": the Email to be sent is invalid in some way. the SetError SHOULD contain a property called"properties"of type"String[]"that lists all the properties of the Email that were invalid 📝"tooManyRecipients": the envelope (supplied or generated) has more recipients than the server allows. a"maxRecipients""UnsignedInt"property MUST also be present on the SetError, specifying the maximum number of allowed recipients 👥"noRecipients": the envelope (supplied or generated) doesn't have anyrcptToemail addresses 🫥"invalidRecipients": the"rcptTo"property of the envelope (supplied or generated) contains at least one value that isn't a valid email address for sending to. an"invalidRecipients""String[]"property MUST also be present on the SetError, listing the invalid addresses 🚫"forbiddenMailFrom": the server doesn't let the user send a message with the envelope From address [RFC5321] 🛑"forbiddenFrom": the server doesn't let the user send a message with the From header field [RFC5322] of the message to be sent 🙅"forbiddenToSend": the user doesn't have permission to send at all right now, for some reason. a"description""String"property MAY be present on the SetError object to show the user why they're not permitted 🔒
for "update":
"cannotUnsend": the client tried to update the"undoStatus"of a valid EmailSubmission object from"pending"to"canceled", but the message can't be unsent 😬
7.5.1. Example 🎬
the following example assumes a draft of the Email to be sent has already been saved, and its Email id is "M7f6ed5bcfd7e2604d1753f6c". this call sends the Email immediately, and if it works, removes the "$draft" flag and moves it from the drafts folder (Mailbox id "7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e") to the sent folder (which we're assuming has Mailbox id "73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6") 📨✨
[[ "EmailSubmission/set", {
"accountId": "ue411d190",
"create": {
"k1490": {
"identityId": "I64588216",
"emailId": "M7f6ed5bcfd7e2604d1753f6c",
"envelope": {
"mailFrom": {
"email": "john@example.com",
"parameters": null
},
"rcptTo": [{
"email": "jane@example.com",
"parameters": null
},
...
]
}
}
},
"onSuccessUpdateEmail": {
"#k1490": {
"mailboxIds/7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e": null,
"mailboxIds/73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6": true,
"keywords/$draft": null
}
}
}, "0" ]]a successful response might look like this. there are two responses because of the implicit "Email/set" call, but both share the same method call id since they come from the same call in the request 🥰
[[ "EmailSubmission/set", {
"accountId": "ue411d190",
"oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"newState": "355421f6-8aed-4cf4-a0c4-7377e951af36",
"created": {
"k1490": {
"id": "ES-3bab7f9a-623e-4acf-99a5-2e67facb02a0"
}
}
}, "0" ],
[ "Email/set", {
"accountId": "ue411d190",
"oldState": "778193",
"newState": "778197",
"updated": {
"M7f6ed5bcfd7e2604d1753f6c": null
}
}, "0" ]]now suppose an admin has removed sending rights for the user, so the submission is rejected with a "forbiddenToSend" error 🙅♀️ the description argument of that error is meant to be shown to the user, so it should be localised properly 🌍 let's say the request came with this Accept-Language header:
Accept-Language: de;q=0.9,en;q=0.8the server should try to pick the best localisation from the ones it has, based on the Accept-Language header, as described in [RFC8620], Section 3.8. if the server has English, French, and German translations, it would pick German as the preferred language and send back a response like this 🇩🇪💖
[[ "EmailSubmission/set", {
"accountId": "ue411d190",
"oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"newState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"notCreated": {
"k1490": {
"type": "forbiddenToSend",
"description": "Verzeihung, wegen verdaechtiger Aktivitaeten Ihres
Benutzerkontos haben wir den Versand von Nachrichten gesperrt.
Bitte wenden Sie sich fuer Hilfe an unser Support Team."
}
}
}, "0" ]]8. Vacation Response 🌴
a vacation response sends an automatic reply when a message gets delivered to the mail store, letting the original sender know their message might not be read for a while 🏖️
automated message sending can cause some unwanted chaos 😅 to avoid that, implementors MUST follow the recommendations in [RFC3834].
the VacationResponse object represents the state of the vacation-response-related settings for an account. it has these properties 💅
id: "Id"(immutable; server-set): the id of the object. there is only ever one VacationResponse object, and its id is"singleton"🫧isEnabled: "Boolean": should a vacation response be sent if a message arrives between the"fromDate"and"toDate"? 🤔fromDate: "UTCDate|null": if"isEnabled"is true, messages that arrive on or after this date-time (but before the"toDate"if it's defined) should get the user's vacation response. if null, the vacation response is effective immediately ⏰toDate: "UTCDate|null": if"isEnabled"is true, messages that arrive before this date-time (but on or after the"fromDate"if it's defined) should get the user's vacation response. if null, the vacation response is effective indefinitely ♾️subject: "String|null": the subject used by the message sent in response to messages when the vacation response is enabled. if null, an appropriate subject SHOULD be set by the server 📝textBody: "String|null": the plaintext body to send in response to messages when the vacation response is enabled. if this is null, the server SHOULD generate a plaintext body part from the"htmlBody"when sending vacation responses, but MAY choose to send the response as HTML only. if both"textBody"and"htmlBody"are null, an appropriate default body SHOULD be generated for responses by the server 🧾htmlBody: "String|null": the HTML body to send in response to messages when the vacation response is enabled. if this is null, the server MAY choose to generate an HTML body part from the"textBody"when sending vacation responses, or MAY choose to send the response as plaintext only 🌐
the following JMAP methods are supported.
8.1. VacationResponse/get
okay so this one is totally standard 💅 it's a regular "/get" method, just like the one in [RFC8620], Section 5.1 ✨
there MUST only be exactly one VacationResponse object in an account 🦋 and it MUST have the id singleton 👑 no other ids allowed, periodt 💖
8.2. VacationResponse/set
also totally standard!! 🌸 it's a regular "/set" method, same as [RFC8620], Section 5.3 🫶
9. Security Considerations ✨
okay this section is SERIOUS bestie 😭 all the security considerations of JMAP [RFC8620] apply to this spec too 🔒 and then there are extra ones for the new data types and features this doc adds, which we'll go through in the subsections below 🧚
9.1. EmailBodyPart Value
so service providers usually run security filtering on incoming messages 🛡️ and it's super important that the way the security filter spots content-type and charset lines up with the heuristics JMAP servers use 🎯 servers that apply heuristics to figure out the content-type or charset for an EmailBodyValue SHOULD document those heuristics AND give people a way to turn them off in case they don't match the security filter on a particular mail host 🙈
automatic conversion of charsets that allow hidden channels for ASCII text, like UTF-7, has caused trouble for security filters before 💀 so server implementations can lower that risk by keeping such conversions off by default and/or making them separately configurable 🍓
to let the client limit how much data it gets back for a request, a maximum length can be requested for the data returned for a textual body part 📏 but truncating the data may change the semantic meaning 😬 like, truncating a URL changes where it points! servers that scan for links to malicious sites should take care to either make sure the truncation isn't at a semantically significant point, or rescan the truncated value for malicious content before returning it 🔍
9.2. HTML Email Display
HTML message bodies give you way richer formatting ✨ but they come with a bunch of security challenges, especially when they're embedded in a webmail context alongside the interface HTML 🕸️ clients that render HTML messages should carefully consider the potential risks, including:
- embedded JavaScript can rewrite the message to change its content the next time it's opened, which can let users be misled 😵 in webmail systems, if it runs in the same origin as the interface, it can access and exfiltrate ALL the private data the user can reach, including every other message and potentially contacts, calendar events, settings, and credentials 😱 it can also rewrite the interface to phish passwords without being detected 🎣 a compromise is likely to be persistent, not just for the duration of the page load, because of exfiltration of session credentials or installation of a service worker that can intercept all subsequent network requests (though this would only be possible if blob downloads are also available on the same origin, and the service worker script is attached to the message) 🧨
- HTML documents may load content directly from the Internet instead of just referencing attached resources 🌐 for example, you might have an
<img>tag with an externalsrcattribute 🖼️ this may leak to the sender when a message is opened, as well as the IP address of the recipient 👀 cookies may also be sent and set by the server, which allows tracking between different messages and even website visits and advertising profiles 🍪 - in webmail systems, CSS can break the layout or create phishing vulnerabilities 🎨 for example, using
position:fixedcan let a message draw content outside of its normal bounds, potentially clickjacking a real interface element 🫣 - if you're in a webmail context and NOT inside a separate frame, any styles defined in CSS rules will apply to interface elements too, if the selector matches, which lets the interface get modified 🙃 similarly, any interface styles that match elements in the message will change how they look, potentially breaking the layout of the message 💅
- the link text in HTML has no necessary correlation with the actual target of the link, which can make phishing attacks way more convincing 🎭
- links opened from a message or embedded external content may leak private info in the
Refererheader that's sent by default in most systems 📭 - forms can be used to mimic login boxes, which is a potent phishing vector if they're allowed to submit directly from the message display 🪤
there are a bunch of ways clients can mitigate these issues 🦋 and a defence-in-depth approach, using a combination of techniques, will give the strongest security 💪
- HTML can be filtered before rendering to strip potentially malicious content 🧹 sanitising HTML correctly is tricky, so implementors are strongly recommended to use a well-tested library with a carefully vetted whitelist-only approach 📚 new features with unexpected security characteristics may be added to HTML rendering engines in the future, and a blacklist approach is likely to result in security issues 🚫
subtle differences in how HTML gets parsed can introduce security flaws 😭 to filter with 100% accuracy, you need to use the same parser that the HTML rendering engine will use 🎯
- encapsulating the message in an
<iframe sandbox>, as defined in [HTML], Section 4.7.6, can help mitigate a number of risks 🛡️ this will:- disable JavaScript 🚫
- disable form submission 🚫
- prevent drawing outside of its bounds or conflicts between message CSS and interface CSS 📐
- establish a unique anonymous origin, separate to the containing origin 🫥
- a strong Content Security Policy (see
https://www.w3.org/TR/CSP3/) can, among other things, block JavaScript and the loading of external content in case it somehow evades the filter 🔐 - the leakage of information in the
Refererheader can be mitigated with a referrer policy (seehttps://www.w3.org/TR/referrer-policy/) 🫧 - a
crossorigin=anonymousattribute on tags that load remote content can prevent cookies from being sent 🍪🚫 - if you add
target=_blankto open links in new tabs, also addrel=noopenerso the page that opens can't change the URL in the original tab to redirect the user to a phishing site 🪝
as highly complex software components, HTML rendering engines increase a client's attack surface a LOT 📈 especially when they're used to process untrusted, potentially malicious content ☠️
serious bugs have been found in image decoders, JavaScript engines, and HTML parsers in the past, and they could lead to full system compromise 😱 clients using an engine should make sure they get the latest version and keep incorporating any security patches released by the vendor 🔧
9.3. Multiple Part Display
messages can be made of multiple parts that get displayed one after another as a body 📬 clients MUST render each part in isolation and MUST NOT concatenate the raw text values to render ⚠️ doing that may change the overall semantics of the message 🙀 and if the client or server is decrypting a Pretty Good Privacy (PGP) or S/MIME encrypted part, concatenating it with other parts may leak the decrypted text to an attacker, as described in [EFAIL] 🕵️♀️
9.4. Email Submission
SMTP submission servers [RFC6409] have a bunch of ways to limit the damage from compromised user accounts and end-user systems, including rate limiting, anti-virus/anti-spam milters (mail filters), and other technologies 🛡️ these work way better when they know more about the client connection 🧠 so if JMAP email submission is set up as a proxy to an SMTP submission server, it's really useful to pass that info along from the JMAP proxy to the submission server 📨 the de facto XCLIENT extension to SMTP [XCLIENT] can do this, but using an authenticated channel is recommended so that the extension only gets used by explicitly authorised proxies 🔑
JMAP servers that proxy to an SMTP submission server SHOULD allow use of the submissions port [RFC8314] 🔌 implementing something similar to SMTP XCLIENT is strongly encouraged 💜 SASL PLAIN over TLS [RFC4616] is currently the mandatory-to-implement mechanism for interoperability with SMTP submission servers [RFC4954], but a JMAP submission proxy SHOULD implement and prefer a stronger mechanism for this use case, like TLS client certificate authentication with SASL EXTERNAL ([RFC4422], Appendix A) or Salted Challenge Response Authentication Mechanism (SCRAM) [RFC7677] 🏆
if the JMAP server directly relays mail to SMTP servers in other administrative domains, implementing the de facto [milter] protocol is strongly encouraged 🌍 that helps you plug into third-party products that handle security issues like anti-virus/anti-spam, reputation protection, compliance archiving, and data loss prevention 🧰 proxying to a local SMTP submission server may be a simpler way to get those security services 🌸
9.5. Partial Account Access
a user may only have permission to access a subset of the data in an account 🔐 to avoid leaking unauthorised information in that situation, the server MUST treat any data the user does not have permission to access the same as if it did not exist 🫥
for example, say user A has an account with two Mailboxes, inbox and sent, but only shares the inbox with user B 📥 in this case, when user B fetches Mailboxes for this account, the server MUST behave as though the sent Mailbox did not exist 👻 similarly, when querying or fetching Email objects, it MUST treat any messages that just belong to the sent Mailbox as though they did not exist 🙈 fetching Thread objects MUST only return ids for Email objects the user has permission to access, and if there are none, the Thread again MUST be treated the same as if it did not exist 🧵
if the server forbids a single account from having two identical messages, or two messages with the same Message-Id header field, a user with write access can use the error returned by trying to create or import such a message to find out whether it already exists in an inaccessible portion of the account 🕵️ sneaky, but also kinda iconic 🍓
9.6. Permission to Send from an Address 💌
okay bestie, the email world has gotten SO serious about trusting the From address 🫢. [RFC5322] defines the message header stuff, and schemes like Domain-based Message Authentication, Reporting, and Conformance (DMARC) [RFC7489] are a big reason why it matters so much now ✨.
Every Identity object (see Section 6) in an account is basically the client's cheat sheet for which email addresses the user is allowed to send from 📝. Each email submission is tied to an Identity, and servers SHOULD reject any submission whose From header field doesn't match the Identity it's attached to 🙅♀️.
Servers MAY let someone send an exact copy of a message already in the mail store to a different address (aka "redirecting" or "bouncing") 🦋. Even so, it's RECOMMENDED the server only allow this to destinations the user has already verified they control 🔐.
If someone tries to create a new Identity object, the server MUST reject it with the appropriate error when the user doesn't have permission to send from that address 🚫.
The SMTP MAIL FROM address [RFC5321] gets mixed up with the From message header field [RFC5322] allll the time 😭. Users usually only ever see the header one, so that's the main one to enforce. BUT the server MUST also enforce proper restrictions on the MAIL FROM address [RFC5321] so nobody can flood a third-party address with bounces and non-delivery notices 📭.
The JMAP submission model has separate errors for impermissible addresses in either context 💅.
10. IANA Considerations 🧾
10.1. JMAP Capability Registration for "mail"
IANA has registered the "mail" JMAP Capability like this: 🎀
Capability Name: urn:ietf:params:jmap:mail
Specification document: this document
Intended use: common
Change Controller: IETF
Security and privacy considerations: this document, Section 910.2. JMAP Capability Registration for "submission"
Same vibe for the "submission" JMAP Capability 🌸:
Capability Name: urn:ietf:params:jmap:submission
Specification document: this document
Intended use: common
Change Controller: IETF
Security and privacy considerations: this document, Section 910.3. JMAP Capability Registration for "vacationresponse"
And the "vacationresponse" JMAP Capability gets the exact same treatment 🌴:
Capability Name: urn:ietf:params:jmap:vacationresponse
Specification document: this document
Intended use: common
Change Controller: IETF
Security and privacy considerations: this document, Section 910.4. IMAP and JMAP Keywords Registry
okay so this document makes two changes to the IMAP keywords registry from [RFC5788] 🗝️.
First, the registry gets renamed to the "IMAP and JMAP Keywords" registry. Second, a scope column gets added to the template and the registry, saying whether a keyword applies to "IMAP-only", "JMAP-only", "both", or "reserved". Every keyword already in the IMAP keyword registry got marked "both" ✨. The "reserved" status is handy for blocking a future registration of a name that would be confusing. Registrations with scope "reserved" leave out most of the template fields (check out the "$recent" registration below for an example), and they're meant to be pretty rare 🙈.
IMAP clients MAY silently ignore any keywords marked "JMAP-only" or "reserved" in the event they show up in the protocol. JMAP clients MAY silently ignore any keywords marked "IMAP-only" or "reserved" in the event they show up in the protocol. 💖
New "JMAP-only" keywords are registered in the subsections that follow 🦋. These keywords correspond to IMAP system keywords, so they aren't appropriate for use in IMAP. They can't be registered for IMAP later except via standards action 🔒.
10.4.1. Registration of JMAP Keyword "$draft"
This registers the "JMAP-only" keyword "$draft" in the "IMAP and JMAP Keywords" registry 📄:
Keyword name: $draft
Scope: JMAP-only
Purpose (description): This is set when the user wants to treat the
message as a draft the user is composing. This is the JMAP
equivalent of the IMAP \Draft flag.
Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action:
Automatic. If the account has an IMAP mailbox marked with the
\Drafts special use attribute [RFC6154], setting this flag MAY cause
the message to appear in that mailbox automatically. Certain JMAP
computed values such as "unreadEmails" will change as a result of
changing this flag. In addition, mail clients will typically present
draft messages in a composer window rather than a viewer window.
When/by whom the keyword is set/cleared: This is typically set by a
JMAP client when referring to a draft message. One model for draft
Emails would result in clearing this flag in an "EmailSubmission/set"
operation with an "onSuccessUpdateEmail" argument. In a mail store
shared by JMAP and IMAP, this is also set and cleared as necessary so
it matches the IMAP \Draft flag.
Related keywords: None
Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]
Security Considerations: A server implementing this keyword as a
shared keyword may disclose that a user considers the message a draft
message. This information would be exposed to other users with read
permission for the Mailbox keywords.
Published specification: this document
Person & email address to contact for further information:
JMAP mailing list <jmap@ietf.org>
Intended usage: COMMON
Owner/Change controller: IESG10.4.2. Registration of JMAP Keyword "$seen"
This registers the "JMAP-only" keyword "$seen" in the "IMAP and JMAP Keywords" registry 👀:
Keyword name: $seen
Scope: JMAP-only
Purpose (description): This is set when the user wants to treat the
message as read. This is the JMAP equivalent of the IMAP \Seen flag.
Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action:
Advisory. However, certain JMAP computed values such as
"unreadEmails" will change as a result of changing this flag.
When/by whom the keyword is set/cleared: This is set by a JMAP client
when it presents the message content to the user; clients often offer
an option to clear this flag. In a mail store shared by JMAP and
IMAP, this is also set and cleared as necessary so it matches the
IMAP \Seen flag.
Related keywords: None
Related IMAP/JMAP Capabilities: None
Security Considerations: A server implementing this keyword as a
shared keyword may disclose that a user considers the message to have
been read. This information would be exposed to other users with
read permission for the Mailbox keywords.
Published specification: this document
Person & email address to contact for further information:
JMAP mailing list <jmap@ietf.org>
Intended usage: COMMON
Owner/Change controller: IESG10.4.3. Registration of JMAP Keyword "$flagged"
This registers the "JMAP-only" keyword "$flagged" in the "IMAP and JMAP Keywords" registry 🚩:
Keyword name: $flagged
Scope: JMAP-only
Purpose (description): This is set when the user wants to treat the
message as flagged for urgent/special attention. This is the JMAP
equivalent of the IMAP \Flagged flag.
Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action:
Automatic. If the account has an IMAP mailbox marked with the
\Flagged special use attribute [RFC6154], setting this flag MAY cause
the message to appear in that mailbox automatically.
When/by whom the keyword is set/cleared: JMAP clients typically allow
a user to set/clear this flag as desired. In a mail store shared by
JMAP and IMAP, this is also set and cleared as necessary so it
matches the IMAP \Flagged flag.
Related keywords: None
Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]
Security Considerations: A server implementing this keyword as a
shared keyword may disclose that a user considers the message as
flagged for urgent/special attention. This information would be
exposed to other users with read permission for the Mailbox keywords.
Published specification: this document
Person & email address to contact for further information:
JMAP mailing list <jmap@ietf.org>
Intended usage: COMMON
Owner/Change controller: IESG10.4.4. Registration of JMAP Keyword "$answered"
This registers the "JMAP-only" keyword "$answered" in the "IMAP and JMAP Keywords" registry 💬:
Keyword name: $answered
Scope: JMAP-only
Purpose (description): This is set when the message has been
answered.
Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action:
Advisory.
When/by whom the keyword is set/cleared: JMAP clients typically set
this when submitting a reply or answer to the message. It may be set
by the "EmailSubmission/set" operation with an "onSuccessUpdateEmail"
argument. In a mail store shared by JMAP and IMAP, this is also set
and cleared as necessary so it matches the IMAP \Answered flag.
Related keywords: None
Related IMAP/JMAP Capabilities: None
Security Considerations: A server implementing this keyword as a
shared keyword may disclose that a user has replied to a message.
This information would be exposed to other users with read permission
for the Mailbox keywords.
Published specification: this document
Person & email address to contact for further information:
JMAP mailing list <jmap@ietf.org>
Intended usage: COMMON
Owner/Change controller: IESG10.4.5. Registration of "$recent" Keyword
Here's the reserved one, the "$recent" keyword 🌈:
Keyword name: $recent
Scope: reserved
Purpose (description): This keyword is not used to avoid confusion
with the IMAP \Recent system flag.
Published specification: this document
Person & email address to contact for further information:
JMAP mailing list <jmap@ietf.org>
Owner/Change controller: IESG10.5. IMAP Mailbox Name Attributes Registry
10.5.1. Registration of "inbox" Role
This registers the "JMAP-only" "inbox" attribute in the "IMAP Mailbox Name Attributes" registry, as established in [RFC8457] 📥:
Attribute Name: Inbox
Description: New mail is delivered here by default.
Reference: This document, Section 10.5.1
Usage Notes: JMAP only10.6. JMAP Error Codes Registry
The next subsections register a few new error codes in the "JMAP Error Codes" registry, as defined in [RFC8620] 🚨.
10.6.1. mailboxHasChild
JMAP Error Code: mailboxHasChild
Intended use: common
Change controller: IETF
Reference: This document, Section 2.5
Description: The Mailbox still has at least one child Mailbox. The
client MUST remove these before it can delete the parent Mailbox.10.6.2. mailboxHasEmail
JMAP Error Code: mailboxHasEmail
Intended use: common
Change controller: IETF
Reference: This document, Section 2.5
Description: The Mailbox has at least one message assigned to it, and
the onDestroyRemoveEmails argument was false.10.6.3. blobNotFound
JMAP Error Code: blobNotFound
Intended use: common
Change controller: IETF
Reference: This document, Section 4.6
Description: At least one blob id referenced in the object doesn't
exist.? Fine, let's keep going with the rewrite. I'll note that the system environment block in front of this turn isn't part of the RFC text, so I'm ignoring it and just carrying on with the document.
Continuing straight from 10.6.3, here is part 17.
10.6.4. tooManyKeywords
JMAP Error Code: tooManyKeywords
Intended use: common
Change controller: IETF
Reference: This document, Section 4.6
Description: The change to the Email's keywords would exceed a
server-defined maximum.10.6.5. tooManyMailboxes
JMAP Error Code: tooManyMailboxes
Intended use: common
Change controller: IETF
Reference: This document, Section 4.6
Description: The change to the set of Mailboxes that this Email is in
would exceed a server-defined maximum.10.6.6. invalidEmail
JMAP Error Code: invalidEmail
Intended use: common
Change controller: IETF
Reference: This document, Section 7.5
Description: The Email to be sent is invalid in some way.10.6.7. tooManyRecipients
JMAP Error Code: tooManyRecipients
Intended use: common
Change controller: IETF
Reference: This document, Section 7.5
Description: The envelope [RFC5321] (supplied or generated) has more
recipients than the server allows.10.6.8. noRecipients
JMAP Error Code: noRecipients
Intended use: common
Change controller: IETF
Reference: This document, Section 7.5
Description: The envelope [RFC5321] (supplied or generated) does not
have any rcptTo email addresses.10.6.9. invalidRecipients
JMAP Error Code: invalidRecipients
Intended use: common
Change controller: IETF
Reference: This document, Section 7.5
Description: The rcptTo property of the envelope [RFC5321] (supplied
or generated) contains at least one rcptTo value that is not a valid
email address for sending to.10.6.10. forbiddenMailFrom
JMAP Error Code: forbiddenMailFrom
Intended use: common
Change controller: IETF
Reference: This document, Section 7.5
Description: The server does not permit the user to send a message
with this envelope From address [RFC5321].10.6.11. forbiddenFrom
JMAP Error Code: forbiddenFrom
Intended use: common
Change controller: IETF
Reference: This document, Sections 6.3 and 7.5
Description: The server does not permit the user to send a message
with the From header field [RFC5322] of the message to be sent.10.6.12. forbiddenToSend
JMAP Error Code: forbiddenToSend
Intended use: common
Change controller: IETF
Reference: This document, Section 7.5
Description: The user does not have permission to send at all right
now.11. References 📚✨
11.1. Normative References 🎀
[HTML] Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and
S. Moon, "HTML 5.2", World Wide Web Consortium
Recommendation REC-html52-20171214, December 2017,
<https://www.w3.org/TR/html52/>.
[RFC1870] Klensin, J., Freed, N., and K. Moore, "SMTP Service
Extension for Message Size Declaration", STD 10, RFC 1870,
DOI 10.17487/RFC1870, November 1995,
<https://www.rfc-editor.org/info/rfc1870>.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
<https://www.rfc-editor.org/info/rfc2045>.
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
Part Three: Message Header Extensions for Non-ASCII Text",
RFC 2047, DOI 10.17487/RFC2047, November 1996,
<https://www.rfc-editor.org/info/rfc2047>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
Word Extensions: Character Sets, Languages, and
Continuations", RFC 2231, DOI 10.17487/RFC2231, November
1997, <https://www.rfc-editor.org/info/rfc2231>.
[RFC2369] Neufeld, G. and J. Baer, "The Use of URLs as Meta-Syntax
for Core Mail List Commands and their Transport through
Message Header Fields", RFC 2369, DOI 10.17487/RFC2369,
July 1998, <https://www.rfc-editor.org/info/rfc2369>.
[RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource
Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998,
<https://www.rfc-editor.org/info/rfc2392>.
[RFC2557] Palme, J., Hopmann, A., and N. Shelness, "MIME
Encapsulation of Aggregate Documents, such as HTML
(MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999,
<https://www.rfc-editor.org/info/rfc2557>.
[RFC2852] Newman, D., "Deliver By SMTP Service Extension", RFC 2852,
DOI 10.17487/RFC2852, June 2000,
<https://www.rfc-editor.org/info/rfc2852>.
[RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282,
DOI 10.17487/RFC3282, May 2002,
<https://www.rfc-editor.org/info/rfc3282>.
[RFC3461] Moore, K., "Simple Mail Transfer Protocol (SMTP) Service
Extension for Delivery Status Notifications (DSNs)",
RFC 3461, DOI 10.17487/RFC3461, January 2003,
<https://www.rfc-editor.org/info/rfc3461>.
[RFC3463] Vaudreuil, G., "Enhanced Mail System Status Codes",
RFC 3463, DOI 10.17487/RFC3463, January 2003,
<https://www.rfc-editor.org/info/rfc3463>.
[RFC3464] Moore, K. and G. Vaudreuil, "An Extensible Message Format
for Delivery Status Notifications", RFC 3464,
DOI 10.17487/RFC3464, January 2003,
<https://www.rfc-editor.org/info/rfc3464>.
[RFC3834] Moore, K., "Recommendations for Automatic Responses to
Electronic Mail", RFC 3834, DOI 10.17487/RFC3834, August
2004, <https://www.rfc-editor.org/info/rfc3834>.
[RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
RFC 4314, DOI 10.17487/RFC4314, December 2005,
<https://www.rfc-editor.org/info/rfc4314>.
[RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
Authentication and Security Layer (SASL)", RFC 4422,
DOI 10.17487/RFC4422, June 2006,
<https://www.rfc-editor.org/info/rfc4422>.
[RFC4616] Zeilenga, K., Ed., "The PLAIN Simple Authentication and
Security Layer (SASL) Mechanism", RFC 4616,
DOI 10.17487/RFC4616, August 2006,
<https://www.rfc-editor.org/info/rfc4616>.
[RFC4865] White, G. and G. Vaudreuil, "SMTP Submission Service
Extension for Future Message Release", RFC 4865,
DOI 10.17487/RFC4865, May 2007,
<https://www.rfc-editor.org/info/rfc4865>.
[RFC4954] Siemborski, R., Ed. and A. Melnikov, Ed., "SMTP Service
Extension for Authentication", RFC 4954,
DOI 10.17487/RFC4954, July 2007,
<https://www.rfc-editor.org/info/rfc4954>.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
<https://www.rfc-editor.org/info/rfc5198>.
[RFC5248] Hansen, T. and J. Klensin, "A Registry for SMTP Enhanced
Mail System Status Codes", BCP 138, RFC 5248,
DOI 10.17487/RFC5248, June 2008,
<https://www.rfc-editor.org/info/rfc5248>.
[RFC5256] Crispin, M. and K. Murchison, "Internet Message Access
Protocol - SORT and THREAD Extensions", RFC 5256,
DOI 10.17487/RFC5256, June 2008,
<https://www.rfc-editor.org/info/rfc5256>.
[RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
DOI 10.17487/RFC5321, October 2008,
<https://www.rfc-editor.org/info/rfc5321>.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008,
<https://www.rfc-editor.org/info/rfc5322>.
[RFC5788] Melnikov, A. and D. Cridland, "IMAP4 Keyword Registry",
RFC 5788, DOI 10.17487/RFC5788, March 2010,
<https://www.rfc-editor.org/info/rfc5788>.
[RFC6154] Leiba, B. and J. Nicolson, "IMAP LIST Extension for
Special-Use Mailboxes", RFC 6154, DOI 10.17487/RFC6154,
March 2011, <https://www.rfc-editor.org/info/rfc6154>.
[RFC6409] Gellens, R. and J. Klensin, "Message Submission for Mail",
STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011,
<https://www.rfc-editor.org/info/rfc6409>.
[RFC6532] Yang, A., Steele, S., and N. Freed, "Internationalized
Email Headers", RFC 6532, DOI 10.17487/RFC6532, February
2012, <https://www.rfc-editor.org/info/rfc6532>.
[RFC6533] Hansen, T., Ed., Newman, C., and A. Melnikov,
"Internationalized Delivery Status and Disposition
Notifications", RFC 6533, DOI 10.17487/RFC6533, February
2012, <https://www.rfc-editor.org/info/rfc6533>.
[RFC6710] Melnikov, A. and K. Carlberg, "Simple Mail Transfer
Protocol Extension for Message Transfer Priorities",
RFC 6710, DOI 10.17487/RFC6710, August 2012,
<https://www.rfc-editor.org/info/rfc6710>.
[RFC7677] Hansen, T., "SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple
Authentication and Security Layer (SASL) Mechanisms",
RFC 7677, DOI 10.17487/RFC7677, November 2015,
<https://www.rfc-editor.org/info/rfc7677>.
[RFC8098] Hansen, T., Ed. and A. Melnikov, Ed., "Message Disposition
Notification", STD 85, RFC 8098, DOI 10.17487/RFC8098,
February 2017, <https://www.rfc-editor.org/info/rfc8098>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8314] Moore, K. and C. Newman, "Cleartext Considered Obsolete:
Use of Transport Layer Security (TLS) for Email Submission
and Access", RFC 8314, DOI 10.17487/RFC8314, January 2018,
<https://www.rfc-editor.org/info/rfc8314>.
[RFC8457] Leiba, B., Ed., "IMAP "$Important" Keyword and
"\Important" Special-Use Attribute", RFC 8457,
DOI 10.17487/RFC8457, September 2018,
<https://www.rfc-editor.org/info/rfc8457>.
[RFC8474] Gondwana, B., Ed., "IMAP Extension for Object
Identifiers", RFC 8474, DOI 10.17487/RFC8474, September
2018, <https://www.rfc-editor.org/info/rfc8474>.
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol", RFC 8620, DOI 10.17487/RFC8620, June 2019,
<https://www.rfc-editor.org/info/rfc8620>.11.2. Informative References 📚
Okay, now the extra reading list 🤓 These are the sources the document points to for background, not the stuff you're required to follow. 🫶
- [EFAIL] Poddebniak, D., Dresen, C., Mueller, J., Ising, F., Schinzel, S., Friedberger, S., Somorovsky, J., and J. Schwenk, "Efail: Breaking S/MIME and OpenPGP Email Encryption using Exfiltration Channels", August 2018,
https://www.usenix.org/system/files/conference/usenixsecurity18/sec18-poddebniak.pdf. 🔐💀 - [milter] Postfix, "Postfix before-queue Milter support", 2019,
http://www.postfix.org/MILTER_README.html. 📮 - [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
https://www.rfc-editor.org/info/rfc3501. 🦋 - [RFC7489] Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based Message Authentication, Reporting, and Conformance (DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015,
https://www.rfc-editor.org/info/rfc7489. 🌸 - [XCLIENT] Postfix, "Postfix XCLIENT Howto", 2019,
http://www.postfix.org/XCLIENT_README.html. 🧚
Authors' Addresses 💌
Here's who wrote this whole thing, with their contact details, so you know who to thank (or DM 😭):
Neil Jenkins
Fastmail
PO Box 234, Collins St. West
Melbourne, VIC 8007
Australia
Email: neilj@fastmailteam.com
URI: https://www.fastmail.com
Chris Newman
Oracle
440 E. Huntington Dr., Suite 400
Arcadia, CA 91006
United States of America
Email: chris.newman@oracle.comThat's the whole thing, bestie! 🌈✨ Eighteen parts of JMAP-for-mail goodness, and we made it. You're iconic. 👑💅
📦 where this page comes from
- ietf: rfc8621 2019-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms