| JMAP | N. Jenkins |
| Internet-Draft | FastMail |
| Updates: 5788 (if approved) | October 30, 2017 |
| Intended status: Standards Track | |
| Expires: May 3, 2018 |
JMAP for Mail
draft-ietf-jmap-mail-02
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 May 3, 2018.
Copyright (c) 2017 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 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].
The underlying format used for this specification is I-JSON ([RFC7493]). Consequently, the terms "object" and "array" as well as the four primitive types (strings, numbers, booleans, and null) are to be interpreted as described in Section 1 of [RFC7159]. Unless otherwise noted, all the property names and values are case sensitive.
Some examples in this document contain "partial" JSON documents used for illustrative purposes. In these examples, three periods "..." are used to indicate a portion of the document that has been removed for compactness.
Types signatures are given for all JSON objects in this document. The following conventions are used:
Object properties may also have a set of attributes defined along with the type signature. These have the following meanings:
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 spec. Servers supporting this specification MUST add a property called {TODO: URI for this spec} to the capabilities object. The value of this property is an object which SHOULD 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>
A mailbox represents a named set of emails. This is the primary mechanism for organising messages within an account. It is analogous to a folder or a label in other systems. A mailbox may perform a certain role in the system; see below for more details.
For compatibility with IMAP, a message MUST belong to one or more mailboxes. The message id does not change if the message changes mailboxes.
A Mailbox object has the following properties:
No two mailboxes may have the same role. Mailboxes without a known purpose MUST have a role of
null. An account is not required to have mailboxes with any of the above roles. A client MAY create new mailboxes with a role property to help them keep track of a use-case not covered by the above list. To avoid potential conflict with any special behaviour a server might apply to mailboxes with certain roles in the future, any roles not in the above list created by the client must begin with "x-". The client MAY attempt to create mailboxes with the standard roles if not already present, but the server MAY reject these.
The Trash mailbox (that is a mailbox with role == "trash") MUST be treated specially for the purpose of unread counts:
The result of this is that messages in the Trash are treated as though they are in a separate thread for the purposes of unread counts. It is expected that clients will hide messages in the Trash when viewing a thread in another mailbox and vice versa. This allows you to delete a single message to the Trash out of a thread.
So for example, suppose you have an account where the entire contents is a single conversation with 2 messages: an unread message in the Trash and a read message in the Inbox. The unreadThreads count would be 1 for the Trash and 0 for the Inbox.
For IMAP compatibility, a message 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 getFoos method. The ids argument may be null to fetch all at once.
Standard getFooUpdates method, but with one extra argument to the mailboxUpdates 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 message counts separately to other state changes. The changedProperties array may be used directly via a result reference in a subsequent getMailboxes call in a single request.
Standard getFooList method.
The FilterCondition object (optionally passed as the filter argument) 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 getFooListUpdates method.
Standard setFoos method. The following extra SetError types are defined:
For create:
For update:
For destroy:
Replies are grouped together with the original message to form a thread. In JMAP, a thread is simply a flat list of messages, ordered by date. Every message MUST belong to a thread, even if it is the only message in the thread.
The JMAP spec does not require the server to use any particular algorithm for determining whether two messages belong to the same thread, however there is a recommended algorithm in the implementation guide.
If messages are delivered out of order for some reason, a user may receive two messages in the same thread but without headers that associate them with each other. The arrival of a third message in the thread may provide the missing references to join them all together into a single thread. Since the threadId of a message is immutable, if the server wishes to merge the threads, it MUST handle this by deleting and reinserting (with a new message id) the messages that change threadId.
A Thread object has the following properties:
The following JMAP methods are supported:
Standard getFoos method.
Request:
[ "getThreads", {
"ids": ["f123u4", "f41u44"],
}, "#1" ]
with response:
[ "threads", {
"accountId": "acme",
"state": "f6a7e214",
"list": [
{
"id": "f123u4",
"messageIds": [ "eaa623", "f782cbb"]
},
{
"id": "f41u44",
"messageIds": [ "82cf7bb" ]
}
],
"notFound": null
}, "#1" ]
Standard getFooUpdates method.
A Message object is a JSON representation of an [RFC5322] message that hides the complexities of MIME. All special encodings of either headers or textual body parts, such as Base64 ([RFC4648]), or [RFC2047] encoding of non-ASCII characters, MUST be fully decoded into UTF-8. It has the following properties:
The IMAP
\Recent keyword is not exposed via JMAP. The IMAP \Deleted keyword is also not present: IMAP uses a delete+expunge model, which JMAP does not. Any message with the \Deleted keyword MUST NOT be visible via JMAP. Users may add arbitrary keywords to a message. For compatibility with IMAP, a keyword is a (case-sensitive) string of 1–255 characters in the ASCII subset %x21–%x7e (excludes control chars and space), and MUST NOT include any of these characters: ( ) { ] % * " \ 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:This property is set by the server based on the
attachments property.
An Emailer object has the following properties:
Group information and comments from the RFC 5322 header MUST be discarded when converting into an Emailer object.
Example array of Emailer objects:
[
{name:"Joe Bloggs", email:"joeb@example.com"},
{name:"", email:"john@example.com"},
{name:"John Smith", email: "john@"}
]
An Attachment object has the following properties:
To add an attachment, the file must first be uploaded using the standard upload mechanism; this will give the client a blobId that may be used to identify the file. The cid property may be assigned by the client, and is solely used for matching up with cid:<id> links inside the htmlBody.
The following JMAP methods are supported:
Standard getFoos method, except the client may use the following pseudo values in the properties argument:
Request:
["getMessages", {
"ids": [ "f123u456", "f123u457" ],
"properties": [ "threadId", "mailboxIds", "from", "subject", "date" ]
}, "#1"]
and response:
["messages", {
"accountId": "abc",
"state": "41234123231",
"list": [
{
id: "f123u457",
threadId: "ef1314a",
mailboxIds: { "f123": true },
from: [{name: "Joe Bloggs", email: "joe@bloggs.com"}],
subject: "Dinner on Thursday?",
date: "2013-10-13T14:12:00Z"
}
],
notFound: [ "f123u456" ]
}, "#1"]
Standard getFooUpdates method.
Standard getFooList method, but with the following additional arguments:
A FilterOperator object has the following properties:
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:
`[ "someThreadKeyword:$Flagged desc", "date desc" ]
This would sort messages in flagged threads first (the thread is considered flagged if any message within it is flagged), and then in date order, newest first. If two messages have both identical flagged status and date, the order is server-dependent but must be stable.
When collapseThreads == true, then after filtering and sorting the message list, the list is further winnowed by removing any messages for a thread id that has already been seen (when passing through the list sequentially). A thread will therefore only appear once in the threadIds list of the result, at the position of the first message in the list that belongs to the thread.
The messageList response has the following additional argument:
Standard getFooListUpdates method, with the following additional arguments:
The messageListUpdates response has the following additional arguments:
Standard setFoos method. The setMessages method encompasses:
When creating a message, the headers property specifies extra headers to add in addition to any based off the parsed properties (like from/to/subject). The keys MUST only contain the characters a-z (lower-case only), 0-9 and hyphens. If a header is included that conflicts with one of the other properties on the Message object (e.g. from, date), the value in the headers object MUST be ignored.
The server MAY also choose to set additional headers. If not included, the server MUST generate and set a Message-Id header in conformance with [RFC5322] section 3.6.4.
Other than making sure it conforms to the correct type, the server MUST NOT attempt to validate from/to/cc/bcc (e.g. checking if an email address is valid) when creating a message. This is to ensure draft messages can be saved at any point.
Destroying a message removes it from all mailboxes to which it belonged. To just delete a message to trash, simply change the mailboxIds property so it is now in the mailbox with role == "trash", and remove all other mailbox ids.
When emptying the trash, clients SHOULD NOT destroy messages which are also in a mailbox other than trash. For those messages, they SHOULD just remove the Trash mailbox from the message.
The following extra SetError types are defined:
For create:
For update:
The importMessages method adds [RFC5322] messages to a user's set of messages. The messages must first be uploaded as a file using the standard upload mechanism. It takes the following arguments:
A MessageImport object has the following properties:
Each message to import is considered an atomic unit which may succeed or fail individually. Importing successfully creates a new message object from the data reference by the blobId and applies the given mailboxes and keywords.
The server MAY forbid two messages with the same exact [RFC5322] content, or even just with the same [RFC5322] Message-Id, to coexist within an account. In this case, it should reject attempts to import a message considered a duplicate with an alreadyExists SetError. A messageId property of type String MUST be included on the error object with the id of the existing message.
If the blobId, mailboxIds, or keywords properties are invalid (e.g. missing, wrong type, id not found), the server MUST reject the import with an invalidProperties SetError.
If the message cannot be imported because it would take the account over quota, the import should be rejected with a maxQuotaReached SetError.
If the blob referenced cannot be parsed as an [RFC5322] message, the server MUST reject the import with an invalidMessage SetError.
The response to importMessages is called messagesImported. It has the following arguments:
The following errors may be returned instead of the messageImported response:
accountNotFound: Returned if an accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: Returned if the accountId given corresponds to a valid account, but the account does not support this data type.
accountReadOnly: Returned if the account has isReadOnly == true.
invalidArguments: Returned if one of the arguments is of the wrong type, or otherwise invalid. A description property MAY be present on the response object to help debug with an explanation of what the problem was.
The only way to move messages between two different accounts is to copy them using the copyMessages method, then once the copy has succeeded, delete the original. It takes the following arguments:
A MessageCopy object has the following properties:
The server MAY forbid two messages with the same exact [RFC5322] content, or even just with the same [RFC5322] Message-Id, to coexist within an account. If duplicates are allowed though, the "from" account may be the same as the "to" account to copy messages within an account.
Each message copy is considered an atomic unit which may succeed or fail individually. Copying successfully MUST create a new message object, with separate ids and mutable properties (e.g. mailboxes and keywords) to the original message.
The response to copyMessages is called messagesCopied. It has the following arguments:
The SetError may be one of the following types:
alreadyExists: Returned if the server forbids duplicates and the message already exists in the target account. A messageId property of type String MUST be included on the error object with the id of the existing message.
notFound: Returned if the messageId given can't be found.
invalidProperties: Returned if the mailboxIds or keywords properties are invalid (e.g. missing, wrong type, id not found).
maxQuotaReached: Returned if the user has reached their mail quota so the message cannot be copied.
The following errors may be returned instead of the messagesCopied response:
fromAccountNotFound: Returned if a fromAccountId was explicitly included with the request, but it does not correspond to a valid account.
toAccountNotFound: Returned if a toAccountId was explicitly included with the request, but it does not correspond to a valid account.
fromAccountNoMail: Returned if the fromAccountId given corresponds to a valid account, but does not contain any mail data.
toAccountNoMail: Returned if the toAccountId given corresponds to a valid account, but does not contain any mail data.
accountReadOnly: Returned if the "to" account has isReadOnly == true.
invalidArguments: Returned if one of the arguments is of the wrong type, or otherwise invalid. A description property MAY be present on the response object to help debug with an explanation of what the problem was.
The MessageSubmission object represents the submission of a message for delivery to one or more recipients. A MessageSubmission object 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 message 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 message, but MAY just remain pending. If in pending state, a client can attempt to cancel the submission by setting this property to canceled; if the update succeeds, the submission was successfully canceled and the message 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 message 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 Message objects if they correlate to a MessageSubmission object. It SHOULD only do this if it exposes them in the dsnBlobIds and mdnblobIds fields instead, and expects the user to be using clients capable of fetching and displaying delivery status via the MessageSubmission object.
For efficiency, a server MAY destroy MessageSubmission objects a certain amount of time after the message is successfully sent or it has finished retrying sending 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.
The following JMAP methods are supported:
Standard getFoos method.
Standard getFooUpdates method.
Standard getFooList method.
The FilterCondition object (optionally passed as the filter argument) has the following properties, any of which may be omitted:
A MessageSubmission 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 getFooListUpdates method.
Standard setFoos method, with the following two extra arguments:
A single implicit setMessages call MUST be made after all MessageSubmission create/update/destroy requests have been processed to perform any changes requested in these two arguments. The messagesSet response MUST be returned after the messageSubmissionsSet response.
A message is sent by creating a MessageSubmission object. When processing each create, the server must check that the message is valid, and the user has sufficient authorization to send it. If the creation succeeds, the message will be sent to the recipients given in the envelope rcptTo parameter. The server MUST remove any Bcc header present on the message during delivery. The server MAY add or remove other headers from the submitted message, or make further alterations in accordance with the server's policy during delivery.
If the referenced message is destroyed at any point after the MessageSubmission object is created, this MUST NOT change the behaviour of the message submission (i.e. it does not cancel a future send).
Similarly, destroying a MessageSubmission object MUST NOT affect the deliveries it represents. It purely removes the record of the message submission. The server MAY automatically destroy MessageSubmission objects after a certain time or in response to other triggers, and MAY forbid the client from manually destroying MessageSubmission objects.
The following extra SetError types are defined:
For create:
For update:
For destroy:
An Identity object stores information about an email address (or domain) the user may send from. It has the following properties:
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 getFoos method. The ids argument may be null to fetch all at once.
Standard getFooUpdates method.
Standard setFoos method. The following extra SetError types are defined:
For create:
For destroy:
When doing a search on a String property, the client may wish to show the relevant section of the body that matches the search as a preview instead of the beginning of the message, and to highlight any matching terms in both this and the subject of the message. 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, preview and attachments properties.
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 getSearchSnippets. It takes the following arguments:
The response to getSearchSnippets is called searchSnippets. It has the following arguments:
Since snippets are only based on immutable properties, there is no state string or update mechanism needed.
The following errors may be returned instead of the searchSnippets response:
accountNotFound: Returned if an accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: Returned if the accountId given corresponds to a valid account, but the account does not support this data type.
requestTooLarge: Returned if the number of messageIds requested by the client exceeds the maximum number the server is willing to process in a single method call.
cannotDoFilter: Returned if the server is unable to process the given filter for any reason.
invalidArguments: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A description property MAY be present on the response object to help debug with an explanation of what the problem was.
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 getFoos method.
There MUST only be exactly one VacationResponse object in an account. It MUST have the id "singleton".
Standard setFoos method. The following extra SetError types are defined:
For create or destroy:
All security considerations of JMAP {TODO: insert RFC ref} apply to this specification.
| [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. |
| [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. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC2852] | Newman, D., "Deliver By SMTP Service Extension", RFC 2852, DOI 10.17487/RFC2852, June 2000. |
| [RFC3461] | Moore, K., "Simple Mail Transfer Protocol (SMTP) Service Extension for Delivery Status Notifications (DSNs)", RFC 3461, DOI 10.17487/RFC3461, January 2003. |
| [RFC3463] | Vaudreuil, G., "Enhanced Mail System Status Codes", RFC 3463, DOI 10.17487/RFC3463, January 2003. |
| [RFC3464] | Moore, K. and G. Vaudreuil, "An Extensible Message Format for Delivery Status Notifications", RFC 3464, DOI 10.17487/RFC3464, January 2003. |
| [RFC3629] | Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003. |
| [RFC3798] | Hansen, T. and G. Vaudreuil, "Message Disposition Notification", RFC 3798, DOI 10.17487/RFC3798, May 2004. |
| [RFC4648] | Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006. |
| [RFC4865] | White, G. and G. Vaudreuil, "SMTP Submission Service Extension for Future Message Release", RFC 4865, DOI 10.17487/RFC4865, May 2007. |
| [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. |
| [RFC5321] | Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, DOI 10.17487/RFC5321, October 2008. |
| [RFC5322] | Resnick, P., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008. |
| [RFC5788] | Melnikov, A. and D. Cridland, "IMAP4 Keyword Registry", RFC 5788, DOI 10.17487/RFC5788, March 2010. |
| [RFC6409] | Gellens, R. and J. Klensin, "Message Submission for Mail", STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011. |
| [RFC6533] | Hansen, T., Newman, C. and A. Melnikov, "Internationalized Delivery Status and Disposition Notifications", RFC 6533, DOI 10.17487/RFC6533, February 2012. |
| [RFC6710] | Melnikov, A. and K. Carlberg, "Simple Mail Transfer Protocol Extension for Message Transfer Priorities", RFC 6710, DOI 10.17487/RFC6710, August 2012. |
| [RFC7159] | Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014. |
| [RFC7493] | Bray, T., "The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015. |