This is an automated email from the ASF dual-hosted git repository. btellier pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 08c46e3384e759d29be16da8646206684495b31e Author: duc91 <[email protected]> AuthorDate: Wed Sep 23 17:30:01 2020 +0700 James-3385: update Email/Query documentation --- CHANGELOG.md | 1 + .../doc/specs/spec/mail/message.mdown | 89 +++++++++++++++++++++- 2 files changed, 89 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f32b9d5..4d3e97c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) ## [Unreleased] ### Added +- Partial Support for JMAP RFC-8621: The current implementation status allow reading mailboxes, emails, vacation responses - JAMES-3117 Add PeriodicalHealthChecks for periodical calling all health checks - JAMES-3143 WebAdmin endpoint to solve Cassandra message inconsistencies - JAMES-3138 Webadmin endpoint to recompute users current quotas on top of Guice products 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 f50c8b0..6bc3137 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,7 +1,7 @@ # Emails <aside class="warning"> - Not implemented yet + Partially implemented </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. @@ -38,6 +38,11 @@ These properties represent metadata about the message in the mail store and are The id representing the raw octets of the message [@!RFC5322] for this Email. This may be used to download the raw original message or to attach it directly to another Email, etc. - **threadId**: `Id` (immutable; server-set) The id of the Thread to which this Email belongs. + +<aside class="warning"> + threadId support is not implemented yet. Default to the id of the email. +</aside> + - **mailboxIds**: `Id[Boolean]` The set of Mailbox ids this Email belongs to. An Email in the mail store MUST belong to one or more Mailboxes at all times (until it is destroyed). The set is represented as an object, with each key being a *Mailbox id*. The value for each key in the object MUST be `true`. - **keywords**: `String[Boolean]` (default: \{\}) @@ -52,6 +57,11 @@ These properties represent metadata about the message in the mail store and are The IMAP `\Recent` keyword is not exposed via JMAP. The IMAP `\Deleted` keyword is also not present: IMAP uses a delete+expunge model, which JMAP does not. Any message with the `\Deleted` keyword MUST NOT be visible via JMAP (and so are not counted in the "totalEmails", "unreadEmails", "totalThreads", and "unreadThreads" Mailbox properties). +<aside class="warning"> + The current implementation do not expose `\Deleted`, `\Recent` keywords. + However emails marked as `\Deleted` can still be retrieved via Email/query Email/set (and so are counted in the "totalEmails", "unreadEmails", "totalThreads", and "unreadThreads" Mailbox properties). +</aside> + Users may add arbitrary keywords to an Email. For compatibility with IMAP, a keyword is a case-insensitive string of 1–255 characters in the ASCII subset %x21–%x7e (excludes control chars and space), and it MUST NOT include any of these characters: ( ) { ] % * " \ @@ -278,6 +288,10 @@ Where `{header-field-name}` means any series of one or more printable ASCII char - **:all** This means the value is an array, with the items corresponding to each instance of the header field, in the order they appear in the message. If this suffix is not used, the result is the value of the **last** instance of the header field (i.e., identical to the **last** item in the array if :all is used), or `null` if none. +<aside class="warning"> + :all prefix support is not implemented yet +</aside> + If both suffixes are used, they MUST be specified in the order above. Header field names are matched case insensitively. The value is typed according to the requested form or to an array of that type if :all is used. If no header fields exist in the message with the requested name, the value is `null` if fetching a single instance or an empty array if requesting :all. As a simple example, if the client requests a property called `header:subject`, this means find the *last* header field in the message named "subject" (matched case insensitively) and return the value in *Raw* form, or `null` if no header field of this name is found. @@ -348,6 +362,10 @@ An **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`. +<aside class="warning"> + We support fetching specific headers for the Email entity, but this is not yet implemented for the EmailBodyPart entity +</aside> + The following **Email** properties are specified for access to the body data of the message: - **bodyStructure**: `EmailBodyPart` (immutable) @@ -543,6 +561,11 @@ This is a standard "/get" method as described in [@!RFC8620], Section 5.1, with The server MUST ensure the truncation results in valid UTF-8 and does not occur mid-codepoint. If the part is of type `text/html`, the server SHOULD NOT truncate inside an HTML tag, e.g., in the middle of `<a href="https://example.com";>`. There is no requirement for the truncated form to be a balanced tree or valid HTML (indeed, the original source may well be neither of these things). +<aside class="warning"> + Body truncation implementation does not take html structure into account. + Truncation can happen in the middle of an html tag. +</aside> + 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", @@ -639,15 +662,29 @@ and response: ## Email/changes +<aside class="warning"> + Not implemented yet +</aside> + This is a standard "/changes" method as described in [@!RFC8620], Section 5.2. If generating intermediate states for a large set of changes, it is recommended that newer changes be returned first, as these are generally of more interest to users. ## Email/query +<aside class="warning"> + Partially implemented + + The calcultateTotal field is not supported and so nor are the negative position. +</aside> + This is a standard "/query" method as described in [@!RFC8620], Section 5.5, but with the following additional request arguments: - **collapseThreads**: `Boolean` (default: false) If `true`, Emails in the same Thread as a previous Email in the list (given the filter and sort order) will be removed from the list. This means only one Email at most will be included in the list for any given Thread. +<aside class="warning"> + Each message belonging to a single thread according to our current implementation, collapseThread is a noop operation. +</aside> + 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. ### Filtering @@ -697,6 +734,21 @@ A **FilterCondition** object has the following properties, any of which may be o 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). +<aside class="warning"> +These properties are not supported yet for filtering: +- allInThreadHaveKeyword +- someInThreadHaveKeyword +- noneInThreadHaveKeyword +- text +- from +- to +- cc +- bcc +- subject +- body +- header +</aside> + The exact semantics for matching `String` fields is **deliberately not defined** to allow for flexibility in indexing implementation, subject to the following: - Any syntactically correct encoded sections [@!RFC2047] of header fields with a known encoding SHOULD be decoded before attempting to match text. @@ -728,6 +780,17 @@ The following values for the *property* field on the Comparator object SHOULD be - **allInThreadHaveKeyword** - This value MUST be considered `true` for the Email if **all** of the Emails in the same Thread have the keyword given as an additional *keyword* property on the *Comparator* object. - **someInThreadHaveKeyword** - This value MUST be considered `true` for the Email if **any** of the Emails in the same Thread have the keyword given as an additional *keyword* property on the *Comparator* object. +<aside class="warning"> + These properties are not supported yet for sorting: + - size + - from + - to + - subject + - hasKeyword + - allInThreadHaveKeyword + - someInThreadHaveKeyword +</aside> + The server MAY support sorting based on other properties as well. A client can discover which properties are supported by inspecting the account's *capabilities* object (see Section 1.3). Example sort: @@ -750,8 +813,16 @@ This would sort Emails in flagged Threads first (the Thread is considered flagge 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). +<aside class="warning"> + Each message belonging to a single thread according to our current implementation, collapseThread is a noop operation. +</aside> + ## Email/queryChanges +<aside class="warning"> +Not implemented yet +</aside> + This is a standard "/queryChanges" method as described in [@!RFC8620], Section 5.6, with the following additional request argument: - **collapseThreads**: `Boolean` (default: false) @@ -759,6 +830,10 @@ This is a standard "/queryChanges" method as described in [@!RFC8620], Section 5 ## Email/set +<aside class="warning"> +Not implemented yet +</aside> + This is a standard "/set" method as described in [@!RFC8620], Section 5.3. The *Email/set* method encompasses: - Creating a draft @@ -828,6 +903,10 @@ For **create** and **update**: ## Email/copy +<aside class="warning"> +Not implemented yet +</aside> + This is a standard "/copy" method as described in [@!RFC8620], Section 5.4, except only the *mailboxIds*, *keywords*, and *receivedAt* properties may be set during the copy. This method cannot modify the message represented by the Email. The server MAY forbid two Email objects with identical message content [@!RFC5322], or even just with the same Message-ID [@!RFC5322], to coexist within an account; if the target account already has the Email, the copy will be rejected with a standard `alreadyExists` error. @@ -837,6 +916,10 @@ For successfully copied Email objects, the *created* response contains the *id*, ## Email/import +<aside class="warning"> +Not implemented yet +</aside> + The *Email/import* method adds messages [@!RFC5322] to the set of Emails in an account. The server MUST support messages with Email Address Internationalization (EAI) headers [@!RFC6532]. The messages must first be uploaded as blobs using the standard upload mechanism. The method takes the following arguments: - **accountId**: `Id` @@ -886,6 +969,10 @@ The following additional errors may be returned instead of the *Email/import* re ## Email/parse +<aside class="warning"> +Not implemented yet +</aside> + This method allows you to parse blobs as messages [@!RFC5322] to get Email objects. The server MUST support messages with EAI headers [@!RFC6532]. This can be used to parse and display attached messages 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: --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
