Subject: [Jmap] AD review of draft-ietf-jmap-mail-12

From: Alexey Melnikov <[email-masked]>
Date: Wed, 9 Jan 2019 17:33:39 +0000

Hi,

The document is nearly ready for IETF LC, but there are a few things 
that need to be fixed before it would be ready to be reviewed by wider 
IETF community.

The document is not clear that RFC XXXX is draft-ietf-jmap-core-XX (This 
is only clear for somebody already following JMAP WG). If you don't know 
how to insert a proper Normative reference to draft-ietf-jmap-core-XX, 
at least add a note explaining that this is what is intended.

In Section 1.3.2:

    o  *submissionExtensions*: "String[String[]]" A JMAP implementation
       that talks to a Submission [RFC6409] server SHOULD have a
       configuration setting that allows an administrator to expose a new
       submission EHLO capability in this field.  This allows a JMAP
       server to gain access to a new submission extension without code
       changes.  By default, the JMAP server should hide EHLO
       capabilities that are to do with the transport mechanism and thus
       are only relevant to the JMAP server (for example PIPELINING,
       CHUNKING, or STARTTLS).  Each key in the object is the _ehlo-
       name_, and the value is a list of _ehlo-args_.  Examples of
       Submission extensions to include:

       *  FUTURERELEASE ([RFC4865])

       *  SIZE ([RFC1870])

       *  DSN ([RFC3461])

       *  DELIVERYBY ([RFC2852])

       *  MT-PRIORITY ([RFC6710])

Is it worth having a registry for these a la Section 6.2 of RFC 8494?

In Section 1.5:

    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.

I think an example or pointer to an example would be useful here. I only 
found an example in JMAP CORE, but I am still not entirely sure what you 
are describing here.

In Section 2:

 > Servers MUST forbid sibling Mailboxes with the same name.

What exactly is this trying to say? Do you mean 2 siblings with the same 
name? (is it just a way to say that a mailbox name is unique among all 
of its siblings?)

Or does it mean that a mailbox A can't have sibling A? If yes, then why?

RFC 4314 (IMAP ACL) needs to be referenced at least Informatevely (due 
to Myrights command reference).

IMAP4rev1 (RFC 3501) should be an Informative reference (due to 
referencing the following terms: subscriptions, internal date).

In Section 4.1.2.1:

 >   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).

Do we really want to encourage the "MAY use heuristics" part? Such email 
messages are non compliant and thus not in scope for this document!

So RAW will typically have the leading space, as most generated messages 
have a space after ":" that terminates the header field name. Is it 
worth pointing this out to implementors?

In Section 4.1.2.2:

 >5. Any [RFC6532] UTF-8 values decoded.

Decoded from what? They are already in UTF-8!

    o  Comment

RFC 5322 defines "Comments" header field (note that it is plural).

Also, what about "Keywords" header field?

Is it worth explicitly mentioning Content-Description header field here 
as well?

In Section 4.1.2.3:

"Any [RFC6532] UTF-8 values MUST be decoded." -- again, decoded from what?

Is RFC 2231 encoding allowed in this and the following section?

In 4.1.3:

asText and asAddresses is not defined in the document. Did you mean:

4.1.2.2.  Text

4.1.2.3.  Addresses

?

If yes, you need to clarify this somewhere.

In Section 4.1.4:

You need to define handling for unrecognised Content-Transfer-Encoding 
values here.

"cid:" needs to Normatively reference RFC 2392. HTML needs a reference 
as well.

In Section 4.2 (and similar text in 4.9):

maxBodyValueBytes:

  "The server MUST ensure the truncation results in valid UTF-8 and does 
not occur mid-codepoint." --

The document needs to make sure that this is only true for body parts 
which are known to be textual (e.g. text/plain, text/html, XML, JSON). 
If a body part is a JPEG image, this requirement doesn't make sense.

In Sections 4.8/4.9:

The document needs to explicitly allow EAI messages, not just RFC 5322 
format.

In Section 5:

HTML is now definitely a Normative reference. More details of what is 
expected in HTML escaping, other than <mark> wrap?

In Section 7:

Are "MDN" and "DSN" blobIds referencing only the machine parseable part 
or the whole multipart/report coming back? I think the document should 
clarify this and (ideally) give some examples.

End of Section 7.5:

  "The server MAY choose to localise this string into the user's 
preferred language, if known."

How can this be done? Should the identity object contain some preferred 
language tag(s)? This needs a bit more thought.

In Section 9.3: SMTP XCLIENT should be an Informative reference.

In Section 10.4.4 (Registration of JMAP keyword '$answered')

    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 looks like a cut & paste error from the text specified for $flagged.

    This information would be
    exposed to other users with read permission for the mailbox keywords.

Best Regards,

Alexey

---

From: "Bron Gondwana" <[email-masked]>
Date: Wed, 09 Jan 2019 17:45:29 -0500

> Is it worth having a registry for these a la Section 6.2 of RFC 8494?

Do we want to do this afterwards and reference both JMAP and SMTP-SUBMISSION in an RFC which collects up the current status and bootstraps the registry, like we did for \Important? I ask because I'm not sure if we should do this work in JMAP or EXTRA.

> Or does it mean that a mailbox A can't have sibling A? If yes, then why?

It was the first of those, no two folders with the same (parentId, name) tuple.

> to Myrights command reference).

This got discussed during the core review. I believe it's already fixed.

> referencing the following terms: subscriptions, internal date).

Yep, good point:

https://github.com/jmapio/jmap/issues/277

> messages are non compliant and thus not in scope for this document!

Leaving this one for Neil to comment on before creating an issue

> worth pointing this out to implementors?

That's sounds like a definitely worthwhile thing to point out!

https://github.com/jmapio/jmap/issues/278

> "cid:" needs to Normatively reference RFC 2392. HTML needs a reference 

https://github.com/jmapio/jmap/issues/279
https://github.com/jmapio/jmap/issues/280

> If a body part is a JPEG image, this requirement doesn't make sense.

The "bodyValues" is only defined for text/ parts I believe:

 o  *bodyValues*: "String[EmailBodyValue]" (immutable) This is a map
      of _partId_ to an *EmailBodyValue* object for none, some or all
      "text/*" parts.  Which parts are included and whether the value is
      truncated is determined by various arguments to _Email/get_ and
      _Email/parse_.  An *EmailBodyValue* object has the following
      properties:

Hence it always contains UTF-8 data.

> The document needs to explicitly allow EAI messages, not just RFC 5322 

https://github.com/jmapio/jmap/issues/281

> clarify this and (ideally) give some examples.

https://github.com/jmapio/jmap/issues/282

> language tag(s)? This needs a bit more thought.

https://github.com/jmapio/jmap/issues/283

I also commented that it might be better to have the user's preferred language as part of core rather than part of mail.

> In Section 9.3: SMTP XCLIENT should be an Informative reference.

https://github.com/jmapio/jmap/issues/284

>  exposed to other users with read permission for the mailbox keywords.

https://github.com/jmapio/jmap/issues/285

Phew! Thanks for the detailed review Alexey.

Cheers,

Bron.

--
 Bron Gondwana, CEO, FastMail Pty Ltd
 [email-masked]

---

From: "Neil Jenkins" <[email-masked]>
Date: Wed, 09 Jan 2019 22:42:49 -0500

On Thu, 10 Jan 2019, at 4:34 AM, Alexey Melnikov wrote:
> The document is not clear that RFC XXXX is draft-ietf-jmap-core-XX

This is now referenced properly.
 
>  By default, the JMAP server should hide EHLO
>  are only relevant to the JMAP server
> 

I don't feel a need for one strongly, but we can add one if you think it's necessary?

>  "EmailDelivery" in the push mechanisms. 
> 
> I think an example or pointer to an example would be useful here.

I've added the following example to the document; does this clarify it for you?

*The client has registered for push notifications just for the `EmailDelivery` type (see [@!I-D.ietf-jmap-core] for details of the push system). The user marks an email as read on another device, causing the state string for the `Email` type to change, however as nothing new was added to the store the `EmailDelivery` state does not change and nothing is pushed to the client. A new message arrives in the user's inbox, again causing the `Email` state to change. This time the `EmailDelivery` state also changes, and a StateChange object is pushed to the client with the new state string. The client may then resync to fetch the new message immediately.*

> What exactly is this trying to say?

I have rewritten this to say:

*There MUST NOT be two mailboxes with both the same parent and the same name.*

Is that clear? (IMAP is path based so naturally you cannot have two sibling mailboxes with the same name; but JMAP is id based so in theory you could. For IMAP compatibility, and to avoid user confusion, this is forbidden by fiat.)

> to Myrights command reference).

As Bron mentioned, this has already done following the secdir core review.

> referencing the following terms: subscriptions, internal date).

Added.

> messages are non compliant and thus not in scope for this document!

Well, they appear in the real world so servers do need to deal with them. Using heuristics to determine what the sender intended often provides the best user experience (customers tend not to care that it was the sender that sent something broken…). However, I'm not strongly attached. Would you prefer me to replace this with the following?

*A server SHOULD replace any octet or octet run with the high bit set that violates UTF-8 syntax with the unicode replacement character (U+FFFD).**
*

> worth pointing this out to implementors?

Doesn't hurt. I have added:

*This form will typically have a leading space, as most generated messages**
*
*insert a space after the colon that terminates the header field name.*

> Decoded from what? They are already in UTF-8!

The idea was that your implementation has a unicode string implementation that may not be UTF-8; that's just one possible encoding. You are decoding everything into your internal string format, normalising the unicode (next step) and then it will be encoded as UTF-8 when output as JSON as this is the encoding used for that.

However, I have now just removed this step as I think it just confuses the matter and the step is obvious if required.

> RFC 5322 defines "Comments" header field (note that it is plural).

Thanks, fixed.

> Also, what about "Keywords" header field?

Sure, I've added that.

> Is it worth explicitly mentioning Content-Description header field here 

The spec currently only has restrictions on RFC5322 and RFC2369 headers. Other headers such as this one are not explicitly forbidden so may be used with the form already. So I don't think it's necessary to mention explicitly.

> "Any [RFC6532] UTF-8 values MUST be decoded." -- again, decoded from what?

Same as above; I have now removed.

> Is RFC 2231 encoding allowed in this and the following section?

I don't think so, as To, Cc etc. don't have parameter values. Or have I got that wrong?

> asText and asAddresses is not defined in the document. Did you mean:

This is defined at the top of page 26 in 4.1.3:

o  *:as{header-form}* This means the value is in a parsed form, where
      "{header-form}" is one of the parsed-form names specified above.
      If not given, the value is in _Raw_ form.

> You need to define handling for unrecognised Content-Transfer-Encoding 

I have added

*If the transfer encoding is unknown, it is treated as though it had no transfer-encoding.*

> "cid:" needs to Normatively reference RFC 2392. HTML needs a reference 

Added.

> If a body part is a JPEG image, this requirement doesn't make sense.

As Bron pointed out, bodyValue is only returned like this for text/* types.

> The document needs to explicitly allow EAI messages, not just RFC 5322 

I'm not entirely sure how to specify this. I have added this sentence to the introduction to each of these methods:

*The server SHOULD support messages with [@!RFC6532] EAI headers.*

Is that sufficient? (And should it be a MUST?)

> expected in HTML escaping, other than <mark> wrap?

Good, catch this was inadequately specified. I have rewritten it as:

*subject*: `String|null`
If text from the filter matches the subject, this is the subject of the email with the following transformations:
 1. Any instance of the following three characters MUST be replaced by an appropriate HTML entity: & (ampersand), < (less-than sign), and > (greater-than sign). Other characters MAY also be replaced with an HTML entity form.
 2. The matching words/phrases from the filter are wrapped in [@!HTML] `<mark></mark>` tags.
If the subject does not match text from the filter, this property is `null`.

*preview*: `String|null`
If text from the filter matches the plain-text or HTML body, this is the relevant section of the body (converted to plain text if originally HTML), with the same transformations as the *subject* property. It MUST NOT be bigger than 255 octets in size. If the body does not contain a match for the text from the filter, this property is `null`.

> clarify this and (ideally) give some examples.

This is intended to be the whole MIME message a with a top-level content-type of multipart/report; I have added the following line to the two properties to clarify:

*The blob is the whole MIME message (with a top-level content-type of multipart/report), as received.*

> How can this be done?

This is just acknowledging the server may have some kind of out-of-band knowledge about the authenticated user and if so should use it to increase the likelihood of presenting an understandable error to the user. I think anything more is out of scope of the current specification.
 
> In Section 9.3: SMTP XCLIENT should be an Informative reference.

Done.

> This looks like a cut & paste error from the text specified for $flagged.

Yes, fixed.

Thanks for the review Alexey. All fixes are pushed to the Git repo <https://github.com/jmapio/jmap/issues> for the spec and live on jmap.io <https://jmap.io/spec-mail.html>; I'll cut a new IETF draft once the remaining clarifications have been settled.

Neil.

---

From: Alexey Melnikov <[email-masked]>
Date: Thu, 10 Jan 2019 10:57:30 +0000

Hi Neil,

Below I removed comments from my reply where we are in agreement:

> I don't feel a need for one strongly, but we can add one if you think 
This is a possible interop issue and I would rather have a registry. I 
am Ok with Bron's proposal to define it in another document.

> /The client has registered for push notifications just for the 
> `EmailDelivery` type (see [@!I-D.ietf-jmap-core] for details of the 
> push system)./
This mostly works, but EmailDelivery is not defined in CORE, it is only 
shown there in examples. /
/
> /The user marks an email as read on another device, causing the state 
> string for the `Email` type to change, however as nothing new was 
> added to the store the `EmailDelivery` state does not change and 
> nothing is pushed to the client. A new message arrives in the user's 
> inbox, again causing the `Email` state to change. This time the 
> `EmailDelivery` state also changes, and a StateChange object is pushed 
> to the client with the new state string. The client may then resync to 
> fetch the new message immediately./
The rest looks fine.
> /There MUST NOT be two mailboxes with both the same parent and the 
> same name./
////
>
> Is that clear? (IMAP is path based so naturally you cannot have two 
> sibling mailboxes with the same name; but JMAP is id based so in 
> theory you could. For IMAP compatibility, and to avoid user confusion, 
> this is forbidden by fiat.)
If you change "two mailboxes" to "two sibling mailboxes", that would be 
clear.
> Well, they appear in the real world so servers do need to deal with 
> them. Using heuristics to determine what the sender intended often 
> provides the best user experience (customers tend not to care that it 
> was the sender that sent something broken…).
MAY is compliance language, but "MAY use heuristics" is impossible to 
test for interoperability.
> However, I'm not strongly attached. Would you prefer me to replace 
> this with the following?
>
> /A server SHOULD replace any octet or octet run with the high bit set 
> that violates UTF-8 syntax with the unicode replacement character 
> (U+FFFD).//
> /
Yes, please.
  [snip]
> The spec currently only has restrictions on RFC5322 and RFC2369 
> headers. Other headers such as this one are not explicitly forbidden 
> so may be used with the form already. So I don't think it's necessary 
> to mention explicitly.

It just took me some time to realize that it is allowed. I don't have a 
strong preference.

> I don't think so, as To, Cc etc. don't have parameter values. Or have 

You are right. I think I want a new type for parsing ;-separated 
attribute=value pairs with RFC 2231 parameters, as this is a pain to do 
in clients.

>        If not given, the value is in _Raw_ form.
Never mind than.
> /If the transfer encoding is unknown, it is treated as though it had 
> no transfer-encoding./

Ok. I think you should also mention that this would result in 
isEncodingProblem being true as well.

  [snip]

> As Bron pointed out, bodyValue is only returned like this for text/* 

Ok. Maybe explain this in a comment, if you feel like it.

> I'm not entirely sure how to specify this. I have added this sentence 
> to the introduction to each of these methods:
>
> /The server SHOULD support messages with [@!RFC6532] EAI headers./
In IMAP4rev2 we made it a MUST. I wouldn't mind if you add a capability 
for this.
> This is intended to be the whole MIME message a with a top-level 
> content-type of multipart/report; I have added the following line to 
> the two properties to clarify:
>
> /The blob is the whole MIME message (with a top-level content-type of 
> multipart/report), as received./
Ok. I suggest you add Normative references to RFCs that define MDN and 
DSN report types.
> This is just acknowledging the server may have some kind of 
> out-of-band knowledge about the authenticated user and if so should 
> use it to increase the likelihood of presenting an understandable 
> error to the user. I think anything more is out of scope of the 
> current specification.

Use of MAY is compliance language, but you don't provide a way to do 
this interoperably (or at all). At minimum clients should be able to 
deduce the language tag used, so you must have a field for conveying it 
(even if it is omitted in most cases.) I think I agree with Bron that 
the mechanism for specifying user's preferred language(s) should be 
specified in CORE.

Best Regards,

Alexey

---

From: Arnt Gulbrandsen <[email-masked]>
Date: Thu, 10 Jan 2019 12:32:05 +0100

> > The server SHOULD support messages with [@!RFC6532] EAI headers.
> In IMAP4rev2 we made it a MUST. I wouldn't mind if you add a 
> capability for this.

IMO IMAP4rev2 is right. SHOULD sounds like pointless diversity. (Unless 
there is a point of which I am unaware?)

Happy new year BTW.

Arnt

---

From: "Neil Jenkins" <[email-masked]>
Date: Fri, 11 Jan 2019 00:20:11 -0500

On Thu, 10 Jan 2019, at 9:57 PM, Alexey Melnikov wrote:
> This is a possible interop issue and I would rather have a registry. I am Ok with Bron's proposal to define it in another document.

OK, I will leave that to be established later.

>> *The client has registered for push notifications just for the `EmailDelivery` type (see [@!I-D.ietf-jmap-core] for details of the push system).*
> This mostly works, but EmailDelivery is not defined in CORE, it is only shown there in examples.

Well, no, it is being defined right here in the JMAP Mail spec. Clearly my description of this is still insufficient; here's another go:

*In addition, servers 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 SHOULD NOT change upon any other change to the Email objects, for example if one is marked as read or deleted.***
**
*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. To do this, they can register for pushes for the EmailDelivery type rather than the Email type **(defined in section 4)**.*

**Example**

*The client has registered for push notifications (see [@!I-D.ietf-jmap-core]) just for the `EmailDelivery` type. The user marks an email as read on another device, causing the state string for the `Email` type to change, however as nothing new was added to the store the `EmailDelivery` state does not change and nothing is pushed to the client. A new message arrives in the user's inbox, again causing the `Email` state to change. This time the `EmailDelivery` state also changes, and a StateChange object is pushed to the client with the new state string. The client may then resync to fetch the new message immediately.*

Is that any better?

> You are right. I think I want a new type for parsing ;-separated attribute=value pairs with RFC 2231 parameters, as this is a pain to do in clients.

Is that something you want in this spec, or leave to an extension?

> Ok. I think you should also mention that this would result in isEncodingProblem being true as well.

The isEncodingProblem definition has been updated to note this.

> In IMAP4rev2 we made it a MUST. I wouldn't mind if you add a capability for this.

I'm interested in *what implementors on the list think about this*; would you prefer this be a MUST, or optional with a capability to indicate support?

> I suggest you add Normative references to RFCs that define MDN and DSN report types.

Sure, done.

> Use of MAY is compliance language, but you don't provide a way to do this interoperably (or at all). At minimum clients should be able to deduce the language tag used, so you must have a field for conveying it (even if it is omitted in most cases.) I think I agree with Bron that the mechanism for specifying user's preferred language(s) should be specified in CORE.

Since we're using HTTP for transport we already have a mechanism for this. So I have changed this to:

*The server SHOULD use information from the Accept-Language header of the request, as defined in RFC7231 section 5.3.5 <https://tools.ietf.org/html/rfc7231#section-5.3.5>, to help determine the choice of localisation if multiple are available. The Content-Language header of the response (see section 3.1.3.2 <https://tools.ietf.org/html/rfc7231#section-3.1.3.2> of RFC7231) SHOULD indicate the language being used for user-visible strings.*

Does that sound reasonable?

Neil.

---

From: Alexey Melnikov <[email-masked]>
Date: Fri, 11 Jan 2019 11:45:38 +0000

Hi Neil,

On 11/01/2019 05:20, Neil Jenkins wrote:
>> This is a possible interop issue and I would rather have a registry. 
>> I am Ok with Bron's proposal to define it in another document.
>>
>
> Well, no, it is being defined right here in the JMAP Mail spec. 
> Clearly my description of this is still insufficient; here's another go:
>
> /In addition, servers 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 SHOULD NOT 
> change upon any other change to the Email objects, for example if one 
> is marked as read or deleted./
>
> /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. To do this, they can register 
> for pushes for the EmailDelivery type rather than the Email type 
> //(defined in section 4)//./
>
> /*Example*/
>
> /The client has registered for push notifications (see 
> [@!I-D.ietf-jmap-core]) just for the `EmailDelivery` type. The user 
> marks an email as read on another device, causing the state string for 
> the `Email` type to change, however as nothing new was added to the 
> store the `EmailDelivery` state does not change and nothing is pushed 
> to the client. A new message arrives in the user's inbox, again 
> causing the `Email` state to change. This time the `EmailDelivery` 
> state also changes, and a StateChange object is pushed to the client 
> with the new state string. The client may then resync to fetch the new 
> message immediately./
>
> Is that any better?

This is much better, thank you!

>> attribute=value pairs with RFC 2231 parameters, as this is a pain to 
>> do in clients.
>

As a client developer I would prefer to have this in the base spec, 
because I think this would make JMAP more useful for me.

As the responsible AD, I am ambivalent about base spec versa extension.

> I'm interested in *what implementors on the list think about this*; 
> would you prefer this be a MUST, or optional with a capability to 
> indicate support?

As a developer I appreciate that this might be a non trivial amount of 
work (more work than adding RFC 2231 decoding ;-)), so I don't mind this 
being an extra capability. As AD, I think this needs to be in the 
current MAIL document (whether as an extension or as a MUST).

I would also like to hear what other people think about this.

>> deduce the language tag used, so you must have a field for conveying 
>> it (even if it is omitted in most cases.) I think I agree with Bron 
>> that the mechanism for specifying user's preferred language(s) should 
>> be specified in CORE.
>
> /The server SHOULD use information from the Accept-Language header of 
> the request, as defined in RFC7231 section 5.3.5 
> <https://tools.ietf.org/html/rfc7231#section-5.3.5>, to help determine 
> the choice of localisation if multiple are available. The 
> Content-Language header of the response (see section 3.1.3.2 
> <https://tools.ietf.org/html/rfc7231#section-3.1.3.2> of RFC7231) 
> SHOULD indicate the language being used for user-visible strings./
>

Yes. But again, this probably belongs to CORE.

Either way, can you add an example (or extend an existing one) to 
demonstrate use of this feature?

Best Regards,

Alexey

---

From: "Neil Jenkins" <[email-masked]>
Date: Mon, 14 Jan 2019 22:40:26 -0500

On Fri, 11 Jan 2019, at 22:46, Alexey Melnikov wrote:
>>> I think I want a new type for parsing ;-separated attribute=value pairs with RFC 2231 parameters, as this is a pain to do in clients./
> As a client developer I would prefer to have this in the base spec, because I think this would make JMAP more useful for me. As the responsible AD, I am ambivalent about base spec versa extension.

This is a bit of a pain to define as a generic type because it's not a generic form in any of the RFCs. There's the Content-Type definition in 2045, and the Content-Disposition definition in 6266. I think I will leave this for someone else to do as an extension if there's demand.

> As a developer I appreciate that this might be a non trivial amount of work (more work than adding RFC 2231 decoding ;-)), so I don't mind this being an extra capability. As AD, I think this needs to be in the current MAIL document (whether as an extension or as a MUST).

> I would also like to hear what other people think about this.

I've made this a MUST. Makes sense given IMAPrev2 is doing it, let's forward to a brave new world…

> Either way, can you add an example (or extend an existing one) to demonstrate use of this feature?

OK. I've added this to the Core spec:

*3.7 Localisation of user-visible strings*

*If returning a custom string to be displayed to the user, for example an error message, the server SHOULD use information from the Accept-Language header of the request (as defined in [@!RFC7231] section 5.3.5) to help determine the choice of localisation if multiple are available. The Content-Language header of the response (see section 3.1.3.2 of [@!RFC7231]) SHOULD indicate the language being used for user-visible strings.***
**
*For example, suppose a request was made with the following header:***
**
` Accept-Language: fr-CH, fr;q=0.9, de;q=0.8, en;q=0.7, *;q=0.5`**
**
*and a method generated an error to display to the user. The server has translations of the error message in English and German. Looking at the Accept-Language header, the user's preferred language is French. Since we don't have a translation for this, we look at the next most preferred which is German. We have a German translation so the server returns this, and indicates the language chosen in a Content-Language header like so:***
**
` Content-Language: de`**

and then replaced the MessageSubmission rejection example in the Mail spec with this:

*Suppose instead an admin has removed sending rights for the user, and so the email submission is rejected with a "forbiddenToSend" error. The description argument of the error is intended for display to the user, so should be localised appropriately. Let's suppose the request was sent with an Accept-Language header like this:***
**
` Accept-Language: de;q=0.9,en;q=0.8`**
**
*The server should attempt to choose the best localisation from those it has available based on the Accept-Language header, as described in [@!I-D.ietf-jmap-core], section 3.7. If the server has English, French and German translations it would choose German as the preferred language and return a response like this:***
**
    [[ "EmailSubmission/set", {
      "accountId": "ue411d190",
      "oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
      "newState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",
      "notCreated": {
        "k1490": {
          "type": "forbiddenToSend",
          "description": "Verzeihung, wegen verdächtiger Aktivitäten Ihres Benutzerkontos haben wir den Versand von Nachrichten gesperrt. Bitte wenden Sie sich für Hilfe an unser Support Team."
        }
      }
    }, "0" ]]

I think that addresses all the concerns raised so far, so I have released new core <https://datatracker.ietf.org/doc/draft-ietf-jmap-core/> and mail <https://datatracker.ietf.org/doc/draft-ietf-jmap-mail/> drafts to progress to IESG last call.

Cheers,
Neil.