| JMAP | N. Jenkins |
| Internet-Draft | FastMail |
| Updates: 5788 (if approved) | C. Newman |
| Intended status: Standards Track | Oracle |
| Expires: March 14, 2019 | September 10, 2018 |
JMAP for Mail
draft-ietf-jmap-mail-08
This document specifies a data model for synchronising email data with a server using JMAP.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 14, 2019.
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
JMAP <https://tools.ietf.org/html/draft-ietf-jmap-core-05> is a generic protocol for synchronising data, such as mail, calendars or contacts, between a client and a server. It is optimised for mobile and web environments, and aims to provide a consistent interface to different data types.
This specification defines a data model for synchronising mail between a client and a server using JMAP.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Type signatures, examples and property descriptions in this document follow the conventions established in Section 1.1 of <https://tools.ietf.org/html/draft-ietf-jmap-core-05>.
Object properties may also have a set of attributes defined along with the type signature. These have the following meanings:
Data types defined in the core specification are used in this document.
The same terminology is used in this document as in the core JMAP specification.
The capabilities object is returned as part of the standard JMAP Session object; see the JMAP Core specification.
This document defines three additional capability objects.
This represents support for the Mailbox, Thread, Email, and SearchSnippet data types and associated API methods. The value of this property is an object which MUST contain the following information on server capabilities:
This represents support for the Identity and MessageSubmission data types and associated API methods. The value of this property is an object which MUST contain the following information on server capabilities:
A JMAP server MAY advertise an extension and implement the semantics of that extension locally on the JMAP server even if a submission server used by JMAP doesn't implement it. The full IANA registry of submission extensions can be found at
<https://www.iana.org/assignments/mail-parameters/mail-parameters.xhtml#mail-parameters-2>
This represents support for the VacationResponse data type and associated API methods. The value of this property is an empty object.
The server MUST include the appropriate capability strings in the hasDataFor property of any account in which the user may use the data types represented by that URN. Supported data types may differ between accounts the user has access to. For example, in the user's personal account they may have access to all three sets of data, but in a shared account they may only have data for urn:ietf:params:jmap:mail. This means they can access Mailbox/Thread/Email data in the shared account but are not allowed to send as that account (and so do not have access to Identity/MessageSubmission objects) or view/set its vacation response.
Servers MUST support the standard JMAP push mechanisms to receive notifications when the state changes for any of the types defined in this specification.
In addition, servers MUST support a psuedo-type called "EmailDelivery" in the push mechanisms. The state string for this MUST change whenever a new Email is added to the store, but SHOULD NOT change upon any other change to the Email objects.
Clients in battery constrained environments may wish to delay fetching changes initiated by the user, but fetch new messages immediately so they can notify the user.
A mailbox represents a named set of emails. This is the primary mechanism for organising emails within an account. It is analogous to a folder or a label in other systems. A mailbox may perform a certain role in the system; see below for more details.
For compatibility with IMAP, an email MUST belong to one or more mailboxes. The email id does not change if the email changes mailboxes.
A Mailbox object has the following properties:
The result of this is that emails in the Trash are treated as though they are in a separate thread for the purposes of unread counts. It is expected that clients will hide emails in the Trash when viewing a thread in another mailbox and vice versa. This allows you to delete a single email to the Trash out of a thread. So for example, suppose you have an account where the entire contents is a single thread with 2 emails: an unread email in the Trash and a read email in the Inbox. The
unreadThreads count would be 1 for the Trash and 0 for the Inbox.
For IMAP compatibility, an email in both the Trash and another mailbox SHOULD be treated by the client as existing in both places (i.e. when emptying the trash, the client SHOULD just remove the Trash mailbox and leave it in the other mailbox).
The following JMAP methods are supported:
Standard "/get" method. The ids argument may be null to fetch all at once.
Standard "/changes" method, but with one extra argument to the response:
Since counts frequently change but the rest of the mailboxes state for most use cases changes rarely, the server can help the client optimise data transfer by keeping track of changes to email/thread counts separately to other state changes. The updatedProperties array may be used directly via a result reference in a subsequent Mailbox/get call in a single request.
Standard "/query" method.
A FilterCondition object has the following properties, any of which may be omitted:
A Mailbox object matches the filter if and only if all of the given conditions given match. If zero properties are specified, it is automatically true for all objects.
The following properties MUST be supported for sorting:
Standard "/queryChanges" method.
Standard "/set" method, but with the following additional argument:
The following extra SetError types are defined:
For destroy:
Fetching all mailboxes in an account:
[[ "Mailbox/get", {
"accountId": "u33084183",
"ids": null
}, "0" ]]
And response:
[[ "Mailbox/get", {
"accountId": "u33084183",
"state": "78540",
"list": [
{
"id": "23cfa8094c0f41e6",
"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": "674cc24095db49ce",
"name": "Important mail",
...
}
...
],
"notFound": []
}, "0" ]]
Now suppose a message 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, then using back references 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": ["23cfa8094c0f41e6"],
"destroyed": []
}, "0" ],
[ "Mailbox/get", {
"accountId": "u33084183",
"state": "78542",
"list": [],
"notFound": []
}, "1" ],
[ "Mailbox/get", {
"accountId": "u33084183",
"state": "78542",
"list": [{
"id": "23cfa8094c0f41e6",
"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": {
"674cc24095db49ce": {
"name": "Maybe important mail"
}
},
"destroy": [ "23cfa8094c0f41e6" ]
}, "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",
"created": null,
"notCreated": null,
"updated": {
"674cc24095db49ce": null
},
"notUpdated": null,
"destroyed": null,
"notDestroyed": {
"23cfa8094c0f41e6": {
"type": "forbidden"
}
}
}, "0" ]]
Replies are 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 is the only email in the thread.
The exact algorithm for determining whether two emails belong to the same thread is not mandated in this spec to allow for compatibility with different existing systems. For new implementations, it is suggested that two messages belong in the same thread if both of the following conditions apply:
If emails are delivered out of order for some reason, a user may receive two emails in the same thread but without headers that associate them with each other. The arrival of a third email in the thread 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:
The following JMAP methods are supported:
Standard "/get" method.
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" ]]
Standard "/changes" method.
The Email object is a representation of an [RFC5322] message, which allows clients to avoid the complexities of MIME parsing, transport encoding and character encoding.
Broadly, a message consists of two parts: a list of header fields, then a body. The JMAP Email object provides a way to access the full structure, or to use simplified properties and avoid some complexity if this is sufficient for the client application.
While raw headers can be fetched and set, the vast majority of clients should use an appropriate parsed form for each of the headers it wants to process, as this allows it to avoid the complexities of various encodings that are required in a valid RFC5322 message.
The body of a message is normally a MIME-encoded set of documents in a tree structure. This may be arbitrarily nested, but the majority of email clients present a flat model of an email body (normally plain text or HTML), with a set of attachments. Flattening the MIME structure to form this model can be difficult, and causes inconsistency between clients. Therefore in addition to the bodyStructure property, which gives the full tree, the Email object contains 3 alternate properties with flat lists of body parts:
Because MIME allows for multiple representations of the same data (using multipart/alternative), there is a textBody property (which prefers a plain text representation) and an htmlBody property (which prefers an HTML representation) to accommodate the two most common client requirements. The same part may appear in both lists where there is no alternative between the two.
The bodyValues property allows for clients to fetch the value of text parts directly without having to do a second request for the blob, and have the server handle decoding the charset into unicode. This data is in a separate property rather than on the EmailBodyPart object to avoid duplication of large amounts of data, as the same part may be included twice if the client fetches more than one of bodyStructure, textBody and htmlBody.
Due to the number of properties involved, the set of Email properties is specified over the following three sub-sections.
These properties represent metadata about the [RFC5322] message, and are not derived from parsing the message itself.
The IMAP
\Recent keyword is not exposed via JMAP. The IMAP \Deleted keyword is also not present: IMAP uses a delete+expunge model, which JMAP does not. Any message with the \Deleted keyword MUST NOT be visible via JMAP. Users may add arbitrary keywords to an email. For compatibility with IMAP, a keyword is a case-insensitive string of 1–255 characters in the ASCII subset %x21–%x7e (excludes control chars and space), and MUST NOT include any of these characters: ( ) { ] % * " \ Because JSON is case-sensitive, servers MUST return keywords in lower-case. The IANA Keyword Registry 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:
Header field properties are derived from the [RFC5322] and [RFC6532] message header fields. All header fields may be fetched in a raw form. Some headers may also be fetched in a parsed form. The structured form that may be fetched depends on the header. The following forms are defined:
Type: String
The raw octets of the header field value from the first octet following the header field name terminating colon, up to but excluding the header field terminating CRLF. Any standards-compliant message MUST be either ASCII (RFC5322) or UTF-8 (RFC6532), however other encodings exist in the wild. A server MAY use heuristics to determine a charset and decode the octets, or MAY 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.
Type: String
The header field value with:
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:
Type: EmailAddress[]
The header 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.
The EmailAddress object has the following properties:
Any syntactically correct [RFC2047] encoded sections with a known encoding MUST be decoded, following the same rules as for the Text form. Any [RFC6532] UTF-8 values MUST be decoded.
Parsing SHOULD be best-effort in the face of invalid structure to accommodate invalid messages and semi-complete drafts. EmailAddress objects MAY have an email property that does not conform to the addr-spec form (for example, may not contain an @ symbol).
For example, the following address-list string:
" James Smythe" <james@example.com>, Friends: jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?= <john@example.com>;
would be parsed as:
[
{ "name": "James Smythe", "email": "james@example.com" },
{ "name": null, "email": "jane@example.com" },
{ "name": "John Smîth", "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:
Type: EmailAddressGroup[]
This is similar to the Addresses form but preserves group information. The header is parsed as an address-list value, as specified in [RFC5322] section 3.4, into the GroupedAddresses[] type. Consecutive mailboxes that are not part of a group are still collected under an EmailAddressGroup object to provide a uniform type.
The EmailAddressGroup object has the following properties:
Any syntactically correct [RFC2047] encoded sections with a known encoding MUST be decoded, following the same rules as for the Text form. Any [RFC6532] UTF-8 values MUST be decoded.
Parsing SHOULD be best-effort in the face of invalid structure to accommodate invalid messages and semi-complete drafts.
For example, the following address-list string:
" James Smythe" <james@example.com>, Friends: jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?= <john@example.com>;
would be parsed as:
[
{ "name": null, "addresses": [
{ "name": "James Smythe", "email": "james@example.com" }
]},
{ "name": "Friends", "addresses": [
{ "name": null, "email": "jane@example.com" },
{ "name": "John Smîth", "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.
Type: String[]|null
The header is parsed as a list of msg-id values, as specified in [RFC5322] section 3.6.4, into the String[] type. 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:
Type: Date|null
The header is parsed as a date-time value, as specified in [RFC5322] section 3.3, into the Date type. If parsing fails, the value is null.
To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:
Type: String[]|null
The header is parsed as a list of URLs, as described in [RFC2369], into the String[] type. Values do not include the surrounding angle brackets or any comments in the header 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:
The following low-level Email property is specified for complete access to the header data of the message:
In addition, the client may request/send properties representing individual header fields of the form:
header:{header-field-name}
Where {header-field-name} means any series of one or more printable ASCII characters (i.e. characters that have values between 33 and 126, inclusive), except colon. The property may also have the following suffixes:
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 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 the empty array if requesting :all.
As a simple example, if the client requests a property called header:subject, this means find the last header field in the message named "subject" (matched case-insensitively) and return the value in Raw form, or null if no header of this name is found.
For a more complex example, consider the client requesting a property called header:Resent-To:asAddresses:all. This means:
The following convenience properties are also specified for the Email object:
These properties are derived from the [RFC5322] message body and its [RFC2045] MIME entities.
A EmailBodyPart object has the following properties:
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:
See the security considerations section for issues related to truncation and heuristic determination of content-type and charset.
None of these parts include subParts, including
message/* types. Attached messages may be fetched using the Email/parse method and the blobId. Note, an HTML body part may reference image parts in attachments using cid: links to reference the Content-Id or by referencing the Content-Location.The server MAY set hasAttachment based on implementation-defined or site configurable heuristics.
The exact algorithm for decomposing bodyStructure into textBody, htmlBody and attachments part lists is not mandated, as this is a quality-of-service implementation issue and likely to require workarounds for malformed content discovered over time. However, the following algorithm (expressed here in JavaScript) is suggested as a starting point, based on real-world experience:
function isInlineMediaType ( type ) {
return type.startsWith( 'image/' ) ||
type.startsWith( 'audio/' ) ||
type.startsWith( 'video/' );
}
function parseStructure ( parts, multipartType, inAlternative,
htmlBody, textBody, attachments ) {
// For multipartType == alternative
let textLength = textBody ? textBody.length : -1;
let htmlLength = htmlBody ? htmlBody.length : -1;
for ( let i = 0; i < parts.length; i += 1 ) {
let part = parts[i];
let isMultipart = part.type.startsWith( 'multipart/' );
// Is this a body part rather than an attachment
let isInline = part.disposition != "attachment" &&
// Must be one of the allowed body types
( part.type == "text/plain" ||
part.type == "text/html" ||
isInlineMediaType( part.type ) ) &&
// If multipart/related, only the first part can be inline
// If a text part with a filename, and not the first item in the
// multipart, assume it is an attachment
( i === 0 ||
( multipartType != "related" &&
( isInlineMediaType( part.type ) || !part.name ) ) );
if ( isMultipart ) {
let subMultiType = part.type.split( '/' )[1];
parseStructure( part.subParts, subMultiType,
inAlternative || ( subMultiType == 'alternative' ),
htmlBody, textBody, attachments );
} else if ( isInline ) {
if ( multipartType == 'alternative' ) {
switch ( part.type ) {
case 'text/plain':
textBody.push( part );
break;
case 'text/html':
htmlBody.push( part );
break;
default:
attachments.push( part );
break;
}
continue;
} else if ( inAlternative ) {
if ( part.type == 'text/plain' ) {
htmlBody = null;
}
if ( part.type == 'text/html' ) {
textBody = null;
}
}
if ( textBody ) {
textBody.push( part );
}
if ( htmlBody ) {
htmlBody.push( part );
}
if ( ( !textBody || !htmlBody ) &&
isInlineMediaType( part.type ) ) {
attachments.push( part );
}
} else {
attachments.push( part );
}
}
if ( multipartType == 'alternative' && textBody && htmlBody ) {
// Found HTML part only
if ( textLength == textBody.length &&
htmlLength != htmlBody.length ) {
for ( let i = htmlLength; i < htmlBody.length; i += 1 ) {
textBody.push( htmlBody[i] );
}
}
// Found plain text part only
if ( htmlLength == htmlBody.length &&
textLength != textBody.length ) {
for ( let i = textLength; i < textBody.length; i += 1 ) {
htmlBody.push( textBody[i] );
}
}
}
}
// Usage:
let htmlBody = [];
let textBody = [];
let attachments = [];
parseStructure( [ bodyStructure ], 'mixed', false,
htmlBody, textBody, attachments );
For instance, consider a message with both text and html versions that's then gone through a list software manager that attaches a header/footer. It might have a MIME structure something like:
multipart/mixed
text/plain, content-disposition=inline - A
multipart/mixed
multipart/alternative
multipart/mixed
text/plain, content-disposition=inline - B
image/jpeg, content-disposition=inline - C
text/plain, content-disposition=inline - D
multipart/related
text/html - E
image/jpeg - F
image/jpeg, content-disposition=attachment - G
application/x-excel - H
message/rfc822 - J
text/plain, content-disposition=inline - K
In this case, the above algorithm would decompose this to:
textBody => [ A, B, C, D, K ] htmlBody => [ A, E, K ] attachments => [ C, F, G, H, J ]
Standard "/get" method, with the following additional arguments:
[ "partId", "blobId", "size", "name", "type", "charset", "disposition", "cid", "language", "location" ]
If the standard properties argument is omitted or null, the following default MUST be used instead of "all" properties:
[ "id", "blobId", "threadId", "mailboxIds", "keywords", "size", "receivedAt", "messageId", "inReplyTo", "references", "sender", "from", "to", "cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment", "preview", "bodyValues", "textBody", "htmlBody", "attachments" ]
The following properties are expected to be fast to fetch in a quality implementation:
Clients SHOULD take care when fetching any other properties, as there may be significantly longer latency in fetching and returning the data.
As specified above, parsed forms of headers may only be used on appropriate header fields. Attempting to fetch a form that is forbidden (e.g. header:From:asDate) MUST result in the method call being rejected with an invalidArguments error.
Where a specific header is requested as a property, the capitalization of the property name in the response MUST be identical to that used in the request.
Request:
[ "Email/get", {
"ids": [ "f123u456", "f123u457" ],
"properties": [ "threadId", "mailboxIds", "from", "subject", "receivedAt", "header:List-POST:asURLs", "htmlBody", "bodyValues" ],
"bodyProperties": [ "partId", "blobId", "size", "type" ],
"fetchHTMLBodyValues": true,
"maxBodyValueBytes": 256
}, "#1" ]
and response:
[ "Email/get", {
"accountId": "abc",
"state": "41234123231",
"list": [
{
"id": "f123u457",
"threadId": "ef1314a",
"mailboxIds": { "f123": true },
"from": [{name: "Joe Bloggs", email: "joe@example.com"}],
"subject": "Dinner on Thursday?",
"receivedAt": "2013-10-13T14:12:00Z",
"header:List-POST:asURLs": [ "mailto:partytime@lists.example.com" ],
"htmlBody": [{
"partId": "1",
"blobId": "841623871",
"size": 283331,
"type": "text/html"
}, {
"partId": "2",
"blobId": "319437193",
"size": 10343,
"type": "text/plain"
}],
"bodyValues": {
"1": {
"isEncodingProblem": false,
"isTruncated": true,
"value": "<html><body><p>Hello ..."
},
"2": {
"isEncodingProblem": false,
"isTruncated": false,
"value": "-- \nSent by your friendly mailing list ..."
}
}
}
],
notFound: [ "f123u456" ]
}, "#1" ]
Standard "/changes" method. If generating intermediate states for a large set of changes, it is recommended that newer changes are returned first, as these are generally of more interest to users.
Standard "/query" method, but with the following additional arguments:
In quality implementations, the query "total" property is expected to be fast to calculate when the filter consists solely of a single inMailbox property, as it is the same as the totalEmails or totalThreads properties (depending on whether collapseThreads is true) of the associated Mailbox object.
A FilterCondition object has the following properties, any of which may be omitted:
If zero properties are specified on the FilterCondition, the condition MUST always evaluate to true. If multiple properties are specified, ALL must apply for the condition to be true (it is equivalent to splitting the object into one-property conditions and making them all the child of an AND filter operator).
The exact semantics for matching String fields is deliberately not defined to allow for flexibility in indexing implementation, subject to the following:
The following properties MUST be supported for sorting:
The following properties SHOULD be supported for sorting:
The server MAY support sorting based on other properties as well. A client can discover which properties are supported by inspecting the server's capabilities object (see section 1).
Example sort:
[{
"property": "someInThreadHaveKeyword",
"keyword": "$flagged",
"isAscending": false,
}, {
"property": "subject",
"collation": "i;ascii-casemap"
}, {
"property": "receivedAt",
"isAscending": false,
}]
This would sort emails in flagged threads first (the thread is considered flagged if any email within it is flagged), and then in subject order, then newest first for messages with the same subject. If two emails have both identical flagged status, subject and date, the order is server-dependent but must be stable.
When collapseThreads is true, then after filtering and sorting the email list, the list is further winnowed by removing any emails for a thread id that has already been seen (when passing through the list sequentially). A thread will therefore only appear once in the result, at the position of the first email in the list that belongs to the thread (given the current sort/filter).
The response has the following additional argument:
Standard "/queryChanges" method, with the following additional arguments:
The response has the following additional argument:
Standard "/set" method. The Email/set method encompasses:
The format of the keywords/mailboxIds properties means that when updating an email you can either replace the entire set of keywords/mailboxes (by setting the full value of the property) or add/remove individual ones using the JMAP patch syntax (see RFC XXXX, section 5.3 for the specification and section 5.7 for an example).
Due to the format of the Email object, when creating an email there are a number of ways to specify the same information. To ensure that the RFC5322 email to create is unambiguous, the following constraints apply to Email objects submitted for creation:
Creation attempts that violate any of this SHOULD be rejected with an invalidProperties error, however a server MAY choose to modify the Email (e.g. choose between conflicting headers, use a different content-encoding etc.) to comply with its requirements instead.
The server MAY also choose to set additional headers. If not included, the server MUST generate and set a Message-ID header field in conformance with [RFC5322] section 3.6.4, and a Date header field in conformance with section 3.6.1.
The final RFC5322 email generated may be invalid. For example, if it is a half-finished draft, the "To" field may data that does not currently conform to the required syntax for this header field. The message will be checked for strict conformance when submitted for sending (see the EmailSubmission object description).
Destroying an email removes it from all mailboxes to which it belonged. To just delete an email to trash, simply change the mailboxIds property so it is now in the mailbox with role == "trash", and remove all other mailbox ids.
When emptying the trash, clients SHOULD NOT destroy emails which 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:
For create and update:
Standard "/copy" method, except only the mailboxIds, keywords and receivedAt properties may be set during the copy. This method cannot modify the RFC5322 representation of an email.
The server MAY forbid two email objects with the same exact [RFC5322] content, or even just with the same [RFC5322] Message-ID, 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.
The Email/import method adds [RFC5322] messages to a user's set of emails. The messages must first be uploaded as a file using the standard upload mechanism. It takes the following arguments:
An EmailImport object has the following properties:
Each email to import is considered an atomic unit which may succeed or fail individually. Importing successfully creates a new email object from the data referenced by the blobId and applies the given mailboxes, keywords and receivedAt date.
The server MAY forbid two email objects with the same exact [RFC5322] content, or even just with the same [RFC5322] Message-ID, to coexist within an account. In this case, it MUST reject attempts to import an email considered a duplicate with an alreadyExists SetError. An existingId property of type String MUST be included on the error object with the id of the existing email. If duplicates are allowed, the newly created Email object MUST have a separate id and independent mutable properties to the existing object.
If the blobId, mailboxIds, or keywords properties are invalid (e.g. missing, wrong type, id not found), the server MUST reject the import with an invalidProperties SetError.
If the email cannot be imported because it would take the account over quota, the import should be rejected with an overQuota SetError.
If the blob referenced is not a valid [RFC5322] message, the server MAY modify the message to fix errors (such as removing NUL octets or fixing invalid headers). If it does this, the blobId on the response MUST represent the new representation and therefore be different to the blobId on the EmailImport object. Alternatively, the server MAY reject the import with an invalidEmail SetError.
The response has the following arguments:
This method allows you to parse blobs as [RFC5322] messages to get Email objects. This can be used to parse and display attached emails without having to import 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:
The threadId property of the Email MAY be present if the server can calculate which thread the Email would be assigned to were it to be imported. Otherwise, this too is null if fetched.
The Email/parse method takes the following arguments:
The response has the following arguments:
As specified above, parsed forms of headers may only be used on appropriate header fields. Attempting to fetch a form that is forbidden (e.g. header:From:asDate) MUST result in the method call being rejected with an invalidArguments error.
Where a specific header is requested as a property, the capitalization of the property name in the response MUST be identical to that used in the request.
A client logs in for the first time. It first fetches the set of mailboxes. Now it will display the inbox to the user, which we will presume has mailbox id "fb666a55". The inbox may be (very!) large, but the user's screen is only so big, so the client will just load the start and then can load in more as necessary. The client sends this request:
[[ "Email/query",{
"accountId": "ue150411c",
"filter": {
"inMailbox": "fb666a55"
},
"sort": [{
"isAscending": false,
"property": "receivedAt"
}],
"collapseThreads": true,
"position": 0,
"limit": 30,
"calculateTotal": true
}, "0" ],
[ "Email/get", {
"accountId": "ue150411c",
"#ids": {
"resultOf": "0",
"name": "Email/query",
"path": "/ids"
},
"properties": [
"threadId"
]
}, "1" ],
[ "Thread/get", {
"accountId": "ue150411c",
"#ids": {
"resultOf": "1",
"name": "Email/get",
"path": "/list/*/threadId"
}
}, "2" ],
[ "Email/get", {
"accountId": "ue150411c",
"#ids": {
"resultOf": "2",
"name": "Thread/get",
"path": "/list/*/emailIds"
},
"properties": [
"threadId",
"mailboxIds",
"keywords",
"hasAttachment",
"from",
"subject",
"receivedAt",
"size",
"preview"
]
}, "3" ]]
Let's break down the 4 method calls to see what they're doing:
The response from the server may look something like this:
[[ "Email/query", {
"accountId": "ue150411c",
"filter": {
"inMailbox": "fb666a55"
},
"sort": [{
"property": "receivedAt",
"isAscending": false
}],
"collapseThreads": true,
"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 the …",
},
...
],
"notFound": []
}, "3" ]]
Now, on another device the user marks the first message as unread, sending this API request:
[[ "Email/set", {
"accountId": "ue150411c",
"update": {
"Ma783e5cdf5f2deffbc97930a": {
"keywords/$seen": null
}
}
}, "0" ]]
The server applies this and sends the success response:
[[ "Email/set", {
"accountId": "ue150411c",
"oldState": "780605"
"newState": "780606",
"updated": {
"Ma783e5cdf5f2deffbc97930a": null
},
...
}, "0" ]]
The user also deletes a few messages, and then a new message arrives.
Back on our original machine, we receive a push update that the state string for Email is now 780800. As this does not match the client's current state, it issues a request for the changes:
[[ "Email/changes", {
"accountId": "ue150411c",
"sinceState": "780605",
"maxChanges": 50
}, "3" ],
[ "Email/queryChanges", {
"accountId": "ue150411c",
"filter": {
"inMailbox": "fb666a55"
},
"sort": [{
"property": "receivedAt",
"isAscending": false
}],
"collapseThreads": true,
"sinceQueryState": "09aa9a075588-780599:0",
"upToId": "Mc2781d5e856a908d8a35a564",
"maxChanges": 25,
"calculateTotal": true
}, "11" ]]
The response:
[ "Email/changes", {
"accountId": "ue150411c",
"oldState": "780605",
"newState": "780800",
"hasMoreChanges": false,
"created": [ "Me8de6c9f6de198239b982ea2" ],
"updated": [ "Ma783e5cdf5f2deffbc97930a" ],
"destroyed": [ "M9bd17497e2a99cb345fc1d0a", ... ],
}, "3" ],
[ "Email/queryChanges", {
"accountId": "ue150411c",
"oldQueryState": "09aa9a075588-780599:0"
"newQueryState": "e35e9facf117-780615:0",
"filter": {
"inMailbox": "fb666a55"
},
"sort": [{
"property": "receivedAt",
"isAscending": false
}],
"collapseThreads": true,
"upToId": "Mc2781d5e856a908d8a35a564",
"added": [{
"id": "Me8de6c9f6de198239b982ea2",
"index": 0
}],
"removed": [ "M9bd17497e2a99cb345fc1d0a" ],
"total": 115,
}, "11" ],
The client can update its local cache of the query results by removing "M9bd17497e2a99cb345fc1d0a" and then splicing in "Me8de6c9f6de198239b982ea2" at position 0. As it does not have the data for this new email, it will then fetch it (it also could have done this in the same request using backreferences).
It knows something has changed about "Ma783e5cdf5f2deffbc97930a", so it will refetch the mailboxes and keywords (the only mutable properties) for this email too.
The user composes a new message and saves a draft. The client sends:
[[ "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": "49db",
"type": "text/html"
}, {
"partId": "bd48",
"type": "text/plain"
}]
},
"bodyValues": {
"bd48": {
"value": "I have the most brilliant plan. Let me tell you all about it. What we do is, we",
"isTruncated": false
},
"49db": {
"value": "<!DOCTYPE html><html><head><title></title><style type=\"text/css\">div{font-size:16px}</style></head><body><div>I have the most brilliant plan. Let me tell you all about it. What we do is, we</div></body></html>",
"isTruncated": false
}
}
}
}
}, "0" ]]
The server creates the message and sends the success response:
[[ "Email/set", {
"accountId": "ue150411c",
"oldState": "780823",
"newState": "780839",
"created": {
"k1546": {
"id": "Md45b47b4877521042cec0938",
"blobId": "Ge8de6c9f6de198239b982ea214e0f3a704e4af74",
"threadId": "Td957e72e89f516dc",
"size": 11721
}
},
...
}, "0" ]]
The client moves this draft to a different account. The only way to do this is via the /copy method. It MUST set a new mailboxIds property, since the current value will not be valid mailbox ids in the destination account:
[[ "Email/copy", {
"fromAccountId": "ue150411c",
"toAccountId": "6c6c41ac",
"create": {
"k45": {
"id": "Md45b47b4877521042cec0938",
"mailboxIds": {
"75a4c956": true
}
}
},
"onSuccessDestroyOriginal": true
}, "0" ]]
The server successfully copies the email and deletes the original. Due to the implicit call to "Email/set", there are two responses to the single method call, both with the same client id:
[[ "Email/copy", {
"fromAccountId": "ue150411c",
"toAccountId": "6c6c41ac",
"created": {
"k45": {
"id": "M138f9954a5cd2423daeafa55",
"blobId": "G6b9fb047cba722c48c611e79233d057c6b0b74e8",
"threadId": "T2f242ea424a4079a",
"size": 11721
}
},
"notCreated": null
}, "0" ],
[ "Email/set", {
"accountId": "ue150411c",
"oldState": "780839"
"newState": "780871",
"destroyed": [ "Ma783e5cdf5f2deffbc97930a" ],
...
}, "0" ]]
When doing a search on a String property, the client may wish to show the relevant section of the body that matches the search as a preview instead of the beginning of the message, and to highlight any matching terms in both this and the subject of the email. Search snippets represent this data.
A SearchSnippet object has the following properties:
It is server-defined what is a relevant section of the body for preview. If the server is unable to determine search snippets, it MUST return null for both the subject and preview roperties.
Note, unlike most data types, a SearchSnippet DOES NOT have a property called id.
The following JMAP method is supported:
To fetch search snippets, make a call to SearchSnippet/get. It takes the following arguments:
The response has the following arguments:
Since snippets are only based on immutable properties, there is no state string or update mechanism needed.
The following standard errors may be returned instead of the searchSnippets response:
requestTooLarge: The number of emailIds requested by the client exceeds the maximum number the server is willing to process in a single method call.
unsupportedFilter: The server is unable to process the given filter for any reason.
Here we did an Email/query to search for any email in the account containing the word "foo", now we are fetching the search snippets for some of the ids that were returned in the results:
[[ "SearchSnippet/get", {
"accountId": "ue150411c",
"filter": {
"text": "foo"
},
"emailIds": [
"M44200ec123de277c0c1ce69c",
"M7bcbcb0b58d7729686e83d99",
"M28d12783a0969584b6deaac0",
...
]
}, "tag-0" ]
Example response:
[[ "SearchSnippet/get", {
"accountId": "ue150411c",
"filter": {
"text": "foo"
},
"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": "...mail <mark>Foo</mark>/changes results often return current-state-minus-1 rather than new..."
},
...
],
"notFound": null
}, "tag-0" ]]
An Identity object stores information about an email address (or domain) the user may send from. It has the following properties:
See the "Addresses" header form description in the Email object for the definition of EmailAddress.
Multiple identities with the same email address MAY exist, to allow for different settings the user wants to pick between (for example with different names/signatures).
The following JMAP methods are supported:
Standard "/get" method. The ids argument may be null to fetch all at once.
Standard "/changes" method.
Standard "/set" method. The following extra SetError types are defined:
For create:
Request:
[ "Identity/get", {
"accountId": "acme",
}, "0" ]
with response:
[ "Identity/get", {
"accountId": "acme",
"state": "99401312ae-11-333",
"list": [
{
"id": "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": "9911312-11_22AAz",
"name": "Joe B",
"email": "joebloggs@example.com",
"replyTo": null,
"bcc": null,
"textSignature": "",
"htmlSignature": "",
"mayDelete": true
}
],
"notFound": []
}, "0" ]
An EmailSubmission object represents the submission of an email for delivery to one or more recipients. It has the following properties:
550-5.7.1 Our system has detected that this message is 550 5.7.1 likely spam, sorry.
550 5.7.1 Our system has detected that this message is likely spam, sorry.
An
Address object has the following properties:If the
envelope property is null or omitted on creation, the server MUST generate this from the referenced email as follows: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 email, but MAY just remain pending. If in pending state, a client can attempt to cancel the submission by setting this property to canceled; if the update succeeds, the submission was successfully canceled and the email has not been delivered to any of the original recipients.For example:
Note, successful relaying to an external SMTP server SHOULD NOT be taken as an indication that the email has successfully reached the final mailbox. In this case though, the server MAY receive a DSN response, if requested. If a DSN is received for the recipient with Action equal to "delivered", as per
[RFC3464] section 2.3.3, then the delivered property SHOULD be set to yes; if the Action equals "failed", the property SHOULD be set to no. Receipt of any other DSN SHOULD NOT affect this property. The server MAY also set this property based on other feedback channels.If an MDN is received for this recipient with Disposition-Type (as per
[RFC3798] section 3.2.6.2) equal to "displayed", this property SHOULD be set to yes. The server MAY also set this property based on other feedback channels.
JMAP servers MAY choose not to expose DSN and MDN responses as Email objects if they correlate to a EmailSubmission object. It SHOULD only do this if it exposes them in the dsnBlobIds and mdnblobIds fields instead, and expects the user to be using clients capable of fetching and displaying delivery status via the EmailSubmission object.
For efficiency, a server MAY destroy EmailSubmission objects a certain amount of time after the email is successfully sent or it has finished retrying sending the email. For very basic SMTP proxies, this MAY be immediately after creation, as it has no way to assign a real id and return the information again if fetched later.
The following JMAP methods are supported:
Standard "/get" method.
Standard "/changes" method.
Standard "/query" method.
A FilterCondition object has the following properties, any of which may be omitted:
A EmailSubmission object matches the filter if and only if all of the given conditions given match. If zero properties are specified, it is automatically true for all objects.
The following properties MUST be supported for sorting:
Standard "/queryChanges" method.
Standard "/set" method, with the following two extra arguments:
A single implicit Email/set call MUST be made after all EmailSubmission create/update/destroy requests have been processed to perform any changes requested in these two arguments. The response to this MUST be returned after the EmailSubmission/set response.
An email is sent by creating a EmailSubmission object. When processing each create, the server must check that the email is valid, and the user has sufficient authorization to send it. If the creation succeeds, the email will be sent to the recipients given in the envelope rcptTo parameter. The server MUST remove any Bcc header present on the email during delivery. The server MAY add or remove other headers from the submitted email, or make further alterations in accordance with the server's policy during delivery.
If the referenced email is destroyed at any point after the EmailSubmission object is created, this MUST NOT change the behaviour of the email submission (i.e. it does not cancel a future send).
Similarly, destroying a EmailSubmission object MUST NOT affect the deliveries it represents. It purely removes the record of the email submission. The server MAY automatically destroy EmailSubmission objects after a certain time or in response to other triggers, and MAY forbid the client from manually destroying EmailSubmission objects.
If the email to be sent is larger than the server supports sending, a standard tooLarge SetError MUST be returned. A maxSize PositiveInt property MUST be present on the SetError specifying the maximum size of an email that may be sent, in octets.
If the email or identity id given cannot be found, the submission creation is rejected with a standard invalidProperties SetError.
The following extra SetError types are defined:
For create:
For update:
The following example presumes a draft of the message to be sent has already been saved, and its Email id is "M7f6ed5bcfd7e2604d1753f6c". This call then sends the email immediately, and if successful removes the draft flag and moves it from the Drafts folder (which has Mailbox id "7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e") to the Sent folder (which we presume has Mailbox id "73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6").
[[ "EmailSubmission/set", {
"accountId": "ue411d190",
"create": {
"k1490": {
"identityId": "64588216",
"emailId": "M7f6ed5bcfd7e2604d1753f6c",
"envelope": {
"mailFrom": {
"email": "john@example.com",
"parameters": null
},
"rcptTo": [{
"email": "jane@example.com",
"parameters": null
},
...
]
}
}
},
"onSuccessUpdateEmail": {
"#k1490": {
"mailboxIds/7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e": null,
"mailboxIds/73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6": true,
"keywords/$draft": null
}
}
}, "0" ]]
A successful response might look like this. Note there are two responses due to the implicit Email/set call, but both have the same tag as they are due to the same call in the request:
[[ "EmailSubmission/set", {
"accountId": "ue411d190",
"oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"newState": "355421f6-8aed-4cf4-a0c4-7377e951af36",
"created": {
"k1490": {
"id": "3bab7f9a-623e-4acf-99a5-2e67facb02a0"
}
},
"notCreated": null,
"updated": null,
"notUpdated": null,
"destroyed": null,
"notDestroyed": null
}, "0" ],
[ "Email/set", {
"accountId": "ue411d190",
"oldState": "778193",
"newState": "778197",
"created": null,
"notCreated": null,
"updated": {
"M7f6ed5bcfd7e2604d1753f6c": null
},
"notUpdated": null,
"destroyed": null,
"notDestroyed": null
}, "0" ]]
If the email submission was not accepted on the other hand, the response may look like this:
[[ "EmailSubmission/set", {
"accountId": "ue411d190",
"oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"newState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
"created": null,
"notCreated": {
"k1490": {
"type": "tooManyRecipients",
"maxRecipients": 10
}
},
"updated": null,
"notUpdated": null,
"destroyed": null,
"notDestroyed": null
}, "0" ]]
A vacation response automatically sends a reply to messages sent to a particular account, to inform the original sender that their message may not be processed for some time. Automated message sending can produce undesireable behaviour. To avoid this, implementors MUST follow the recommendations set forth in [RFC3834].
The VacationResponse object represents the state of vacation-response related settings for an account. It has the following properties:
The following JMAP methods are supported:
Standard "/get" method.
There MUST only be exactly one VacationResponse object in an account. It MUST have the id "singleton".
Standard "/set" method.
All security considerations of JMAP (RFC XXXX) apply to this specification.
Service providers typically perform security filtering on incoming email and it's important the detection of content-type and charset for the security filter aligns with the heuristics performed by JMAP servers. Servers that apply heuristics to determine the content-type or charset for EmailBodyValue SHOULD document the heuristics and provide a mechanism to turn them off in the event they are misaligned with the security filter used at a particular mailbox host.
Automatic conversion of charsets that allow hidden channels for ASCII text, such as UTF-7, have been problematic for security filters in the past so server implementations can mitigate this risk by having such conversions off-by-default and/or separately configurable.
To allow the client to restrict the volume of data it can receive in response to a request, a maximum length may be requested for the data returned for a textual body part. However, truncating the data may change the semantic meaning, for example truncating a URL changes its location. Servers that scan for links to malicious sites should take care to either ensure truncation is not at a semantically significant point, or to rescan the truncated value for malicious content before returning it.
HTML message bodies provide richer formatting for emails but present a number of security challenges, especially when embedded in a webmail context in combination with interface HTML. Clients that render HTML email should make careful consideration of the potential risks, including:
There are a number of ways clients can mitigate these issues, and a defence-in-depth approach that uses a combination of techniques will provide the strongest security.
Subtle differences in parsing of HTML can introduce security flaws: to filter with 100% accurately you need to use the same parser when sanitizing that the HTML rendering engine will use.
As highly complex software components, HTML rendering engines increase the attack surface of a client considerably, especially when being used to process untrusted, potentially malicious content. Serious bugs have been found in image decoders, JavaScript engines and HTML parsers in the past, which could lead to full system compromise. Clients using an engine should ensure they get the latest version and continue to incorporate any security patches released by the vendor.
SMTP submission servers [RFC6409] use a number of mechanisms to mitigate damage caused by compromised user accounts and end-user systems including rate limiting, anti-virus/anti-spam milters and other technologies. The technologies work better when they have more information about the client connection. If JMAP email submission is implemented as a proxy to an SMTP Submission server, it is useful to communicate this information from the JMAP proxy to the submission server. The de-facto XCLIENT extension to SMTP (<http://www.postfix.org/XCLIENT_README.html>) can be used to do this, but use of an authenticated channel is recommended to limit use of that extension to explicitly authorized proxies.
JMAP servers that proxy to an SMTP Submission server SHOULD allow use of the submissions port [RFC8314] and SHOULD implement SASL PLAIN over TLS [RFC4616] and/or TLS client certificate authentication with SASL EXTERNAL [RFC4422] appendix A. Implementation of a mechanism similar to SMTP XCLIENT is strongly encouraged.
In the event the JMAP server directly relays mail to SMTP servers in other administrative domains, then implementation of the de-facto milter protocol is strongly encouraged to integrate with third-party products that address security issues including 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 provide such security services.
IANA will register the "mail" JMAP Capability as follows:
Capability Name: urn:ietf:params:jmap:mail
Specification document: this document
Intended use: common
Change Controller: IETF
Security and privacy considerations: this document, section 9
IANA will register the "submission" JMAP Capability as follows:
Capability Name: urn:ietf:params:jmap:submission
Specification document: this document
Intended use: common
Change Controller: IETF
Security and privacy considerations: this document, section 9
IANA will register the "vacationresponse" JMAP Capability as follows:
Capability Name: urn:ietf:params:jmap:vacationresponse
Specification document: this document
Intended use: common
Change Controller: IETF
Security and privacy considerations: this document, section 9
This document makes two changes to the IMAP keywords registry as defined in [RFC5788].
First, the name of the registry is changed to the "IMAP and JMAP keywords Registry".
Second, a scope column is added to the template and registry indicating whether a keyword applies to IMAP-only, JMAP-only, both, or reserved. All keywords presently in the IMAP keyword registry will be marked with a scope of both. The "reserved" status can be used to prevent future registration of a name that would be confusing if registered. Registration of keywords with scope 'reserved' omit most fields in the registration template (see example for $recent subsection of this section); such registrations are intended to be infrequent.
IMAP clients MAY silently ignore any keywords marked JMAP-only or reserved in the event they appear in protocol. JMAP clients MAY silently ignore any keywords marked IMAP-only or reserved in the event they appear in protocol.
New JMAP-only keywords are registered in the following sub-sections. These keywords correspond to IMAP system keywords and are thus not appropriate for use in IMAP. These keywords can not be subsequently registered for use in IMAP except via standards action.
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 a mailbox marked with the \Drafts special use [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 typically will 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 attribute. In a mailstore 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 (recommended): this document
Person & email address to contact for further information: (editor-contact-goes-here)
Intended usage: COMMON
Owner/Change controller: IESG
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 mailstore 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 (recommended): this document
Person & email address to contact for further information: (editor-contact-goes-here)
Intended usage: COMMON
Owner/Change controller: IESG
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 a mailbox marked with the \Flagged special use [RFC6154], setting this flag MAY cause the message to appear in that mailbox automatically.
When/by whom the keyword is set/cleared: JMAP clients typically allow a user to set/clear this flag as desired. In a mailstore 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 (recommended): this document
Person & email address to contact for further information: (editor-contact-goes-here)
Intended usage: COMMON
Owner/Change controller: IESG
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 attribute. In a mailstore 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 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 (recommended): this document
Person & email address to contact for further information: (editor-contact-goes-here)
Intended usage: COMMON
Owner/Change controller: IESG
This registers the keyword '$recent' in the "IMAP and JMAP keywords Registry".
Keyword name: $recent
Scope: reserved
Purpose (description): This keyword is not used to avoid confusion with the IMAP \Recent system flag.
Published specification (recommended): this document
Person & email address to contact for further information: (editor-contact-goes-here)
Owner/Change controller: IESG
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.
Usage Notes: JMAP only
The following sub-sections register several new error codes in the JMAP Error Codes registry, as defined in RFC XXXX.
JMAP Error Code: mailboxHasChild
Intended use: common
Change controller: IETF
Reference: This document, section 2.5
JMAP Error Code: mailboxHasEmail
Intended use: common
Change controller: IETF
Reference: This document, section 2.5
JMAP Error Code: blobNotFound
Intended use: common
Change controller: IETF
Reference: This document, section 4.6
JMAP Error Code: tooManyKeywords
Intended use: common
Change controller: IETF
Reference: This document, section 4.6
JMAP Error Code: tooManyMailboxes
Intended use: common
Change controller: IETF
Reference: This document, section 4.6
JMAP Error Code: emailNotFound
Intended use: common
Change controller: IETF
Reference: This document, section 7.5
JMAP Error Code: emailTooLarge
Intended use: common
Change controller: IETF
Reference: This document, section 7.5
JMAP Error Code: invalidEmail
Intended use: common
Change controller: IETF
Reference: This document, section 7.5
JMAP Error Code: tooManyRecipients
Intended use: common
Change controller: IETF
Reference: This document, section 7.5
JMAP Error Code: noRecipients
Intended use: common
Change controller: IETF
Reference: This document, section 7.5
JMAP Error Code: invalidRecipients
Intended use: common
Change controller: IETF
Reference: This document, section 7.5
JMAP Error Code: forbiddenMailFrom
Intended use: common
Change controller: IETF
Reference: This document, section 7.5
JMAP Error Code: forbiddenFrom
Intended use: common
Change controller: IETF
Reference: This document, sections 6.3 and 7.5
JMAP Error Code: forbiddenToSend
Intended use: common
Change controller: IETF
Reference: This document, section 7.5