In Section 2:

o name: "String" User-visible name for the mailbox, e.g. "Inbox".
This may be any UTF-8 string of at least 1 character in length and
maximum 256 bytes in size. Servers SHOULD forbid sibling
Mailboxes with the same name.

The last SHOULD - why? There is no such requirement in IMAP.

In Section 2:
o mayReadItems: "Boolean" If true, may use this mailbox as part of
a filter in a getMessageList call. If a submailbox is shared
but not the parent mailbox, this may be "false".

o mayAddItems: "Boolean" The user may add messages to this mailbox
(by either creating a new message or moving an existing one).

o mayRemoveItems: "Boolean" The user may remove messages from this
mailbox (by either changing the mailboxes of a message or deleting
it).

o mayCreateChild: "Boolean" The user may create a mailbox with
this mailbox as its parent.

o mayRename: "Boolean" The user may rename the mailbox or make it
a child of another mailbox.

o mayDelete: "Boolean" The user may delete the mailbox itself.

Should this reference IMAP ACL RFC (RFC 4314)?

This might be an issue to be mentioned in the JMAP/IMAP co-existence document.

Only recurring events can have recurrenceOverrides
To restrict this the recurrenceOverrides could be in the Recurrence object.

eg CalendarEvent->recurrenceRule->recurrenceOverrides
instead of CalendarEvent->recurrenceOverrides

any reason why it shouldn't?

The Message object has a number of address (list) properties: from, to, cc, bcc, replyTo.

The from and replyTo properties are Emailer objects in the spec, and not arrays thereof, even though the RFC's allow multiple addresses in these fields. (I have used this and seen this elsewhere in the wild.)

A sender property (which should be a single Emailer property) seems to be missing.

N.B.: The example of the Emailer property seems to show an array of Emailer objects, no?

None of these fields say how ‘group syntax’ should be dealt with. (See RFC6854 for a recent RFC extending the use of this construct.)

Since the JMAP spec is still evolving you probably want to add 'rscale' and 'skip' properties to the 'recurrence' object.

Question: Why not just use the existing jCal format (RFC 7265) rather than something similar but different?

The behaviour of getMessageListUpdates in regards to threads seems a bit under specified and I have a couple of questions.

Can getMessageListUpdates only be used to update the list of threads or does it simultaneously update the list of message ids within a thread? In case of the later how do I know the position of the message within a thread since index refers to the position of the thread within the list of threads?
If however getMessageListUpdates can only be used to update the list of threads am I right in assuming that RemovedItem[] will remove single messages from threads? Meaning I will have to keep track of all messages ids within a thread and when a thread has an empty message list (and only then) I can discard that thread from the thread list? Or to put it in other words. If a thread contains two messages and I remove one of them will that message appear as a RemovedItem[]? Or what happens if that entire thread is removed? Will the update have two RemovedItems? Even when collapse threads is true?

As per draft-ietf-jmap-core, but it is not clear in draft-ietf-jmap-mail.

Raised by Dave during IETF99. The name 'messageId' is very confusingly similar to the RFC5322 'Message-Id' header. This will be an ongoing cause of confusion, and should be nipped in the bud.

From the discussion, calling it something else is bad because it breaks the correspondence between object name and {object}Id which is consistent through all the rest of JMAP. Better to rename Message. We need to choose a name.

See RFC 5788 and https://www.iana.org/assignments/imap-keywords/imap-keywords.xhtml#imap-keywords-1.

"MAY NOT" is not defined in RFC 2119. It is probably "MUST NOT".

A message can have megabytes of text in the plaintext part. We need a way to specify that you only want the start of the body, and a way to tell the client that this is an incomplete fetch.

One suggestion (from Chris Newman) at IETF99 was to provide the MIME part number for each attachment, which isn't really necessary because blobId already gives that, but the more interesting bit is the MIME part numbers for the bodyparts used to generate the body, htmlBody and textBody responses - and potentially define those as having a maximum size along with a blobId to generate a URL to do range fetches on the underlying content. This needs some more thought.

2.2.1. 200: Success, but more authorization required.

The response body will be a single JSON object with the following
properties.

o loginId: "String" An id from the server to allow it to connect
the next request with previous requests in the login process.
This SHOULD be of limited time validity (e.g. 15 minutes from
previous call).

o methods: "AuthMethod[]" A list of the supported authentication
methods to continue with authentication. See below for definition
of the AuthMethod object.

o prompt: "String|null" A message to display in the client to the
user. The client MUST treat this as plain text, but SHOULD
automatically hyperlink any URLs it finds if a system browser is
available.

This is the standard response to an initial request. Note, a server
may return this even if the username is not actually active, to
prevent enumeration. The client should then pick one of the
methods from the list in the response to continue with
authentication (if no methods supported by the client are in the
list, it will not be able to get an access token).

An AuthMethod object MUST have a type property. This is a
"String" representing the method of authentication. For some types,
there may be other values required on the AuthMethod object in
addition; see the description of types below. The following types
are currently defined, but more may be added in the future. A client
SHOULD offer the user the option to choose any of the method types
returned that the client supports. The client MUST ignore any types
it does not understand:

It would be good to either reuse SASL authentication framework here or at least hook into existing authentication mechanisms (e.g. Digest, as well as https://datatracker.ietf.org/wg/httpauth/documents/).

Hi,

I recently discovered JMAP and I'm reading through the spec and other available information and there doesn't seem to be a way to discover the JMAP host when given an email address.

Other protocols like IMAP offer host discovery only via some extensions that usually aren't widely adopted. JMAP being a new protocol has the chance to add a standard way of discovering the host right into the specification.

Desired result: A client should be able to ask the user only for an email address and a password and figure out the JMAP host URI on it's own.

XMPP for example does this by using SRV records on the domain. For IMAP there are similar approaches.

When doing this it is also important that certificates are properly verifiable. Meaning since the email address is the only thing entered by a user the certificate on the HTTP host must match the domain name of the email address even though the JMAP URI might differ.

In Section 5:

o textBody: "String" The plain text body part for the message. If
there is only an HTML version of the body, a plain text version
MUST be generated from this; the exact method of conversion in
this case is not defined and is server-specific.

This should mention that this is the empty string if the message has neither text/plain nor text/html body part. (We should also consider using other text/* body parts, if sensible.)

2.3.4. Destroying mailboxes

There MUST always be at least one mailbox. It is expected that the
server will enforce this by setting "mayDeleteMailbox == false" on at
least the Inbox, if not all system mailboxes. However, if this is
not the case, an attempt to destroy the last mailbox MUST still be
rejected with a "mailboxRequired" error.

It is not clear why this is needed and what is this requirement trying to achieve.
Also need to consider a case of an account with only Shared Folders (in IMAP speak).

3.4. Vendor-specific extensions

Individual services will have custom features they wish to expose
over JMAP. This may take the form of extra datatypes and/or methods
not in the spec, or extra arguments to JMAP methods, or extra
properties on existing data types (which may also appear in arguments
to methods that take property names). To ensure compatibility with
clients that don't know about a specific custom extension, and for
compatibility with future versions of JMAP, the server MUST ONLY
expose these extensions if the client explicitly opts in.

I think this section needs a bit more explanation on way(s) to opt-in. Possibly it is enough to have some pointers to text elsewhere in the document.

Without
opt-in, the server MUST follow the spec and reject anything that does
not conform to it as specified.

The spec says

A MessageList is a sorted query on the set of messages in a user's mailbox

but mailboxes can be part of the query, so perhaps the intent was to have

A MessageList is a sorted query on the set of messages in a user's account

The document is recommending use of "x-" prefix. See RFC 6648 about why this is not a good idea.

We might want to reserve a different prefix like "vnd." which might have different requirements on registrations, e.g. First Come First Served as opposed to Expert Review or Specification Required.

2.1. Service autodiscovery

To support clients that are unable to do SRV lookups, the server
SHOULD make the hostname the same domain as the username if
possible.

I think it might be worth moving deployment considerations to a separate section.

The spec is clear on what getMessageList should do when neither position nor anchor are provided:

To paginate the results the client MUST either specify a position argument OR an anchor argument. If both, or neither are supplied, the call MUST be rejected with an invalidArguments error.

position however is defined as:

Number|null The 0-based index of the first result in the list to return. If a negative value is given, the call MUST be rejected with an invalidArguments error. If null, 0 is used.

The rules for null make this ambiguous. A missing parameter is treated as null, which means that a missing position is the same as "position":0. But then anchor can never be provided, because we would then have both.

The easy fix is to remove the default on position, but that still requires one of position or anchor to be specified. I think a better solution would be to keep the default on position, and then make it be ignored if both position and anchor are provided (even implicitly). In that way, its possible to issue a valid getMessageList with empty ({}) args and still get a useful result back.

3.3. Errors

Possible errors for each method are specified in the method
descriptions. If a method encounters an error, the appropriate
"error" response MUST be inserted at the current point in the output

Do we need an IANA registry of error codes? (I.e. is the list of errors fixed or is it extensible).

If the list is extensible: does each method have its own list of error types or are they all in the same namespace?

array and, unless otherwise specified, further processing MUST NOT
happen within that method call.

It is required for all RFCs.

3.7. The Number datatype

The JSON datatypes are limited to those found in JavaScript. A
"Number" in JavaScript is represented as a signed double (64-bit
floating point). However, except where explicitly specified, all
numbers used in this API are unsigned integers <= 2^53 (the maximum
integer that may be reliably stored in a double). This implicitly
limits the maximum length of message lists in queries and the like.

3.8. The Date datatypes

Where a JMAP API specifies "Date" as a type, it means a string in
[RFC3339] date-time format, with the time-offset component always
"Z" (i.e. the date-time MUST be in UTC time) and time-secfrac
always omitted. The "T" and "Z" MUST always be upper-case. For
example, ""2014-10-30T14:12:00Z"".

3.9. Use of null

Unless otherwise specified, a missing property in the arguments
object of a request (from the client), or a response (from the
server) MUST be intepreted exactly the same as that property having
the value "null".

Unless otherwise specified, a missing property in a data object MUST
be interpreted in the following ways: - In the response to a
getFoos style call, or when creating an object in a setFoos
style call, a missing property MUST be interpreted as though it had
the default value for that type, or "null" if no default is
specified. - When updating an object in a setFoos style call, a
missing property MUST be interpreted as the existing value for that
property (i.e. don't update it).

For network efficiency, when fetching the server and client may make
use of the above and omit properties which have the default value for
the data type.

Should these 3 sections be moved as subsections of "Terminology" or "Notational Conventions"?

2.3.5. 503: Service unavailable

The server is currently down. Try again later with exponential
backoff. There is no content in the response.

This should probably provide some recommendations on how many times to try and for how long.

From the spec:

The URL endpoint to use when downloading files, in RFC6570 URI Template (level 1) format. The URL MUST contain a variable called blobId. The URL SHOULD contain a variable called name. The client may use this template in combination with a blobId to download any binary data (files) referenced by other objects. Since a blob is not associated with a particular name, the template SHOULD allow a name to be substituted in as well; the server will return this as the filename if it sets a Content-Disposition header.

But, RFC6570 Level 1 has no provision for optional parameters. The proxy URL structure is /raw/{userId}/{blobId}/{name}. If I don't have a name, I can't usefully expand that template.

I think Level 3 and '{?var}' is what's needed for this case:

/raw/{userId}/{blobId}{?name}

I don't think the spec itself needs to change other than to remove the "Level 1" requirement. Which does raise the bar a bit for clients, but there seems to be plenty of libraries available; one quick search finds this list.

Lets say I wanted to fetch a list of contacts from multiple accounts (Like the Android contact app does) maybe filtered on "isFlagged" can I only select the a list if Ids from a single account?

I think it would be great to have a list of contactIds in all the accounts the user has access too.
Maybe this depends on the servers implementation. The spec says it would use the primary accountId if none is provided in the getContactList request.

In Section 2.2:
o clientVersion: "String" Information to identify the version of
the client. This MUST change for any changed client code (e.g. a
version control tag or counter for development software) and
SHOULD sort lexically later for newer versions.

o deviceName: "String" A human-friendly string to identify the
device making the request, e.g. "Joe Blogg's iPhone".

Are any of these optional?

Also, these have privacy considerations, that should be discussed in the document.

2.3.4. Destroying mailboxes

A mailbox MUST NOT be destroyed if it has any messages assigned to
it. Attempts to do so MUST be rejected with a "mailboxHasMessage"
error.

Previous version of the document required for messages to be moved to INBOX if they were in another mailbox and that was the only mailbox for them. Arguably the above is better, but it is still a departure from IMAP model, which causes all messages to be destroyed (unless they are also referenced by another JMAP mailbox). I think this needs to be further discussed in the WG.

5.2. getMessageUpdates

o changed: "String[]" An array of message ids for messages that
have either been created or had their state change, and are not
currently deleted.

Why not two separate lists for creations and updates? I think you report them separately for other types of objects.

o removed: "String[]" An array of message ids for messages that
have been deleted since the oldState.

In Section 5:

o width: "Number|null" The width (in px) of the image, if the
attachment is an image.

o height: "Number|null" The height (in px) of the image, if the
attachment is an image.

Does these have to be mandatory to support? This raises implementation complexity.

Hi,
We'd like to know which Open Source license jmap specifications are released under ?
Thanks

In Section 2.2.2:

• maxCallsInRequest: "Number" The maximum number of method
  calls the server will accept in a single request to the API
  endpoint.

For interoperability the document should define the minimum value that has to be supported, which is likely to be >1.

All getFooUpdates method seem to have maxChanges request parameter (and related parameters for paged results), except for getMailboxUpdates. Is there a reason for this?

In 2.3.3:

o These properties are immutable or may only be set by the server:

  *  id

  *  role

  *  mustBeOnlyMailbox

  *  mayReadItems

  *  mayAddItems

  *  mayRemoveItems

  *  mayCreateChild

  *  mayRename

  *  mayDelete

  *  totalMessages

  *  unreadMessages

  *  totalThreads

  *  unreadThreads

Before the document is finished we should review this list. If a future specification adds support for ACL editing, some of these would become mutable.

3.4. Address Specification

Addresses occur in several message header fields to indicate senders
and recipients of messages. An address may either be an individual
mailbox, or a group of mailboxes.

address = mailbox / group

[...]

When it is desirable to treat several mailboxes as a single unit
(i.e., in a distribution list), the group construct can be used. The
group construct allows the sender to indicate a named group of
recipients. This is done by giving a display name for the group,
followed by a colon, followed by a comma-separated list of any number
of mailboxes (including zero and one), and ending with a semicolon.
Because the list of mailboxes can be empty, using the group construct
is also a simple way to communicate to recipients that the message
was sent to one or more named sets of recipients, without actually
providing the individual mailbox address for any of those recipients.

Section 2 of draft-ietf-jmap-mail-00 says:

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 in IMAP or a label in other systems.

Nit: RFC 3501 that defines IMAP only uses the term "folder" in the Abstract, IMAP term is also "mailbox".

The Introduction currently says:

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.

I think this needs to be clear that JMAP above refers to draft-ietf-jmap-core. We might also need to have a new term for draft-ietf-jmap-core, as opposed to JMAP-email.

2.4.2. 401: Unauthorized

Failed due to missing "Authorization" header, or the "Authorization"
header did not contain a valid access token. As per the HTTP spec,
the response MUST have a "WWW-Authenticate: Bearer" header. There is

This should also have a reference to the OAuth spec where "Bearer" is defined.

no content in the response.

From the mailing list:

From: Stan Kalisch [email protected]
Message-Id: [email protected]

Minor point: should not the terms "header field" and "header section" be used as in RFC 5322?

Stan

Mailboxes form acyclic graphs (trees); there MUST NOT be a loop.

A first correction: This should be

Mailboxes form acyclic graphs (forests); there MUST NOT be a loop.

because the graph does not need to be connected.

A second correction is related to the orientation: the child-to-parent relationship directs the graph, so one should be more precise and say

Mailboxes form an acyclic graph directed by the child-to-parent relationship and with out-degree one (in-forest); there MUST NOT be a loop.

Note that the term in-forest is not common.

5.1. 201: File uploaded successfully
o type: "String" The content type of the file.

This should reference Section 4.2 of RFC 6838, which defines syntax for MIME types.

A single FilterCondition object can have multiple properties set. In order for the condition to match a message, all properties within the condition must match (ie an AND). The spec is not clear on this.

o role: "String|null" Identifies system mailboxes. This property
can only be set on create. After the record has been created,
this property is immutable. The following values MUST be used for
the relevant mailboxes:

  *  "inbox" - the mailbox to which new mail is delivered by
     default, unless diverted by a rule or spam filter etc.

  *  "archive" - messages the user does not need right now, but does
     not wish to delete.

  *  "drafts" - messages the user is currently writing and are not
     yet sent.

  *  "outbox" - messages the user has finished writing and wishes to
     send (see the "setMessages" method description for more
     information).  A mailbox with this role MUST be present if the
     user is allowed to send mail through an account.  If not
     present, the user MAY NOT send mail with that account.

  *  "sent" - messages the user has sent.

  *  "trash" - messages the user has deleted.

  *  "spam" - messages considered spam by the server.

  *  "templates" - drafts which should be used as templates (i.e.
     used as the basis for creating new drafts).

This needs to make it clear that roles are the same as in RFC 6154 (and if there are any differences, RFC 6154 should be updated to match).

The JMAP spec has an example Emailer object:

[
    {name:"Joe Bloggs", email:"[email protected]"},
    {name:"", email:"[email protected]"}
]

Over IMAP, the JMAP email field can be constructed by joining the IMAP addr-mailbox and addr-host. However, in certain common cases (e.g. Mandrill, GCal invites) the addr-host isn't present. What should the behavior be in this case?

See Switchboard #51.

Thanks!

5. Messages

JMAP completely hides the complexities of MIME. All special
encodings of either headers or the body, such as base64 [2], or RFC
2047 [3] encoding of non-ASCII characters, MUST be fully decoded into
standard UTF-8.

Body parts can contain binary data (e.g. images), so saying that they decode to UTF-8 is incorrect. Maybe you mean textual body parts here?

5. Uploading binary data

There is a single endpoint which handles all file uploads, regardless
of what they are to be used for. To upload a file, the client
submits a POST request to the file upload endpoint (see the
authentication section for information on how to obtain this URL).
The Content-Type MUST be correctly set for the type of the file being
uploaded. The request MUST be authenticated as per any HTTP request.
The request MAY include an "X-JMAP-AccountId" header, with the value

Change the header field name not to use "X-" and register it in the IANA registry.

being the account to use for the request. Otherwise, the default
account will be used.