This is an automated email from the ASF dual-hosted git repository. rcordier pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit c9ccd9f0a8b29fdd2da45e52abe342a450e5c74c Author: Rene Cordier <[email protected]> AuthorDate: Tue Jul 28 16:34:08 2020 +0700 JAMES-3099 Annotate JMAP RFC-8621 mail specifications --- .../doc/specs/spec/mail/identity.mdown | 4 ++++ .../jmap-rfc-8621/doc/specs/spec/mail/intro.mdown | 28 ++++++++++++++++++++++ .../doc/specs/spec/mail/mailbox.mdown | 20 ++++++++++++++++ .../doc/specs/spec/mail/message.mdown | 4 ++++ .../doc/specs/spec/mail/messagesubmission.mdown | 4 ++++ .../doc/specs/spec/mail/searchsnippet.mdown | 4 ++++ .../jmap-rfc-8621/doc/specs/spec/mail/thread.mdown | 4 ++++ .../doc/specs/spec/mail/vacationresponse.mdown | 4 ++++ 8 files changed, 72 insertions(+) diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/identity.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/identity.mdown index be3f64b..c1b8431 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/identity.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/identity.mdown @@ -1,5 +1,9 @@ # Identities +<aside class="warning"> + Not implemented yet +</aside> + An **Identity** object stores information about an email address or domain the user may send from. It has the following properties: - **id**: `Id` (immutable; server-set) diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/intro.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/intro.mdown index 006ce4c..05691e3 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/intro.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/intro.mdown @@ -50,17 +50,33 @@ This document defines three additional capability URIs. ### urn:ietf:params:jmap:mail +<aside class="notice"> + Implemented +</aside> + This represents support for the Mailbox, Thread, Email, and SearchSnippet data types and associated API methods. The value of this property in the JMAP session *capabilities* property is an empty object. The value of this property in an account's *accountCapabilities* property is an object that MUST contain the following information on server capabilities and permissions for that account: - **maxMailboxesPerEmail**: `UnsignedInt|null` +<aside class="warning"> + Not enforced yet +</aside> The maximum number of Mailboxes (see Section 2) that can be can assigned to a single Email object (see Section 4). This MUST be an integer >= 1, or `null` for no limit (or rather, the limit is always the number of Mailboxes in the account). - **maxMailboxDepth**: `UnsignedInt|null` +<aside class="warning"> + Not enforced yet +</aside> The maximum depth of the Mailbox hierarchy (i.e., one more than the maximum number of ancestors a Mailbox may have), or `null` for no limit. - **maxSizeMailboxName**: `UnsignedInt` +<aside class="warning"> + Not enforced yet +</aside> The maximum length, in (UTF-8) octets, allowed for the name of a Mailbox. This MUST be at least 100, although it is recommended servers allow more. - **maxSizeAttachmentsPerEmail**: `UnsignedInt` +<aside class="warning"> + Not enforced yet +</aside> The maximum total size of attachments, in octets, allowed for a single Email object. A server MAY still reject the import or creation of an Email with a lower attachment size total (for example, if the body includes several megabytes of text, causing the size of the encoded MIME structure to be over some server-defined limit). Note that this limit is for the sum of unencoded attachment sizes. Users are generally not knowledgeable about encoding overhead, etc., nor should they need to be, so marketing and help materials normally tell them the "max size attachments". This is the unencoded size they see on their hard drive, so this capability matches that and allows the client to consistently enforce what the user understands as the limit. @@ -75,6 +91,10 @@ The value of this property in an account's *accountCapabilities* property is an ### urn:ietf:params:jmap:submission +<aside class="warning"> + Not implemented yet +</aside> + This represents support for the Identity and EmailSubmission data types and associated API methods. The value of this property in the JMAP session *capabilities* property is an empty object. The value of this property in an account's *accountCapabilities* property is an object that MUST contain the following information on server capabilities and permissions for that account: @@ -103,6 +123,10 @@ The value of this property in an account's *accountCapabilities* property is an ### urn:ietf:params:jmap:vacationresponse +<aside class="warning"> + Not implemented yet +</aside> + This represents support for the VacationResponse data type and associated API methods. The value of this property is an empty object in both the JMAP session *capabilities* property and an account's *accountCapabilities* property. ## Data Type Support in Different Accounts @@ -111,6 +135,10 @@ The server MUST include the appropriate capability strings as keys in the *accou ## Push +<aside class="warning"> + Not implemented yet +</aside> + Servers MUST support the JMAP push mechanisms, as specified in [@!RFC8620] Section 7, to receive notifications when the state changes for any of the types defined in this specification. In addition, servers that implement the "urn:ietf:params:jmap:mail" capability MUST support pushing state changes for a type called "EmailDelivery". There are no methods to act on this type; it only exists as part of the push mechanism. The state string for this MUST change whenever a new Email is added to the store, but it SHOULD NOT change upon any other change to the Email objects, for example, if one is marked as read or deleted. diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/mailbox.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/mailbox.mdown index d144ca6..b92eee3 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/mailbox.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/mailbox.mdown @@ -5,6 +5,9 @@ A Mailbox represents a named set of Emails. This is the primary mechanism for or 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: +<aside class="notice"> + Implemented +</aside> - **id**: `Id` (immutable; server-set) The id of the Mailbox. @@ -13,6 +16,10 @@ A **Mailbox** object has the following properties: - **parentId**: `Id|null` (default: null) The Mailbox id for the parent of this Mailbox, or `null` if this Mailbox is at the top level. Mailboxes form acyclic graphs (forests) directed by the child-to-parent relationship. There MUST NOT be a loop. - **role**: `String|null` (default: null) + <aside class="warning"> + Partially implemented. Role are based on the name of the mailbox. An evolution would be to use a mailbox annotation to hold its + value, removing the link with the name, and allow the user to define locale based system mailboxes. This value cannot be updated. + </aside> Identifies Mailboxes that have a particular common purpose (e.g., the "inbox"), regardless of the *name* property (which may be localised). This value is shared with IMAP (exposed in IMAP via the SPECIAL-USE extension [@!RFC6154]). However, unlike in IMAP, a Mailbox MUST only have a single role, and there MUST NOT be two Mailboxes in the same account with the same role. Servers providing IMAP access to the same data are encouraged to enforce these extra restrictions in IMAP as well. Otherwise, modifying the IMAP attributes to ensure compliance when exposing the data over JMAP is implementation dependent. @@ -22,6 +29,9 @@ A **Mailbox** object has the following properties: An account is not required to have Mailboxes with any particular roles. - **sortOrder**: `UnsignedInt` (default: 0) + <aside class="warning"> + Partially implemented. Based on the role. This value cannot be updated. + </aside> Defines the sort order of Mailboxes when presented in the client's UI, so it is consistent between devices. The number MUST be an integer in the range 0 <= sortOrder < 2^31. @@ -33,8 +43,14 @@ A **Mailbox** object has the following properties: - **unreadEmails**: `UnsignedInt` (server-set) The number of Emails in this Mailbox that have neither the `$seen` keyword nor the `$draft` keyword. - **totalThreads**: `UnsignedInt` (server-set) + <aside class="warning"> + Threads are not implemented. So far, each email is its own thread, so totalThreads will have the same value than totalEmails + </aside> The number of Threads where at least one Email in the Thread is in this Mailbox. - **unreadThreads**: `UnsignedInt` (server-set) + <aside class="warning"> + Threads are not implemented. So far, each email is its own thread, so unreadThreads will have the same value than unreadEmails + </aside> An indication of the number of "unread" Threads in the Mailbox. For compatibility with existing implementations, the way "unread Threads" is @@ -84,6 +100,10 @@ The following JMAP methods are supported. ## Mailbox/get +<aside class="notice"> + Implemented +</aside> + This is a standard "/get" method as described in [@!RFC8620], Section 5.1. The *ids* argument may be `null` to fetch all at once. ## Mailbox/changes diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/message.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/message.mdown index 285fc80..126f421 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/message.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/message.mdown @@ -1,5 +1,9 @@ # Emails +<aside class="warning"> + Not implemented yet +</aside> + An **Email** object is a representation of a message [@!RFC5322], which allows clients to avoid the complexities of MIME parsing, transfer encoding, and character encoding. ## Properties of the Email Object diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/messagesubmission.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/messagesubmission.mdown index 71f8718..2609aeb 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/messagesubmission.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/messagesubmission.mdown @@ -1,5 +1,9 @@ # Email Submission +<aside class="warning"> + Not implemented yet +</aside> + An **EmailSubmission** object represents the submission of an Email for delivery to one or more recipients. It has the following properties: - **id**: `Id` (immutable; server-set) diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/searchsnippet.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/searchsnippet.mdown index 7d83411..299a625 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/searchsnippet.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/searchsnippet.mdown @@ -1,5 +1,9 @@ # Search Snippets +<aside class="warning"> + Not implemented +</aside> + 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 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: diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/thread.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/thread.mdown index 13b9589..f32556f 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/thread.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/thread.mdown @@ -1,5 +1,9 @@ # Threads +<aside class="warning"> + Not implemented yet +</aside> + 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: diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/vacationresponse.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/vacationresponse.mdown index 8639ea2..bc425f2 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/vacationresponse.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/vacationresponse.mdown @@ -1,5 +1,9 @@ # Vacation Response +<aside class="warning"> + Not implemented yet +</aside> + A vacation response sends an automatic reply when a message is delivered to the mail store, informing the original sender that their message may not be read for some time. Automated message sending can produce undesirable behaviour. To avoid this, implementors MUST follow the recommendations set forth in [@!RFC3834]. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
