Subject: [Jmap] Revised MessageSubmission object

From: Neil Jenkins <[email-masked]>
Date: Thu, 20 Jul 2017 01:29:40 +1000

OK, I've taken on all the feedback from the mailing list and as discussed at the IETF Prague meeting, and have updated the pull request[1]. The interesting bit is the MessageSubmission object definition, which I also include below for convenience. I think (hope) this is pretty close to finished, so please do a final review before I merge.
Cheers,
Neil.

--------
The MessageSubmission object represents the submission of a message for delivery to one or more recipients. A *MessageSubmission* object has the following properties:

 * *id*: String The id of the message submission. This is server-set and
   immutable.
 * *identityId*: String The id of the identity to associate with this
   submission. This is immutable.
 * *messageId*: String The id of the message to send. This is immutable.
   The message being sent does not have to be a draft, for example when
   “redirecting” an existing message to a different email address.
 * *threadId*: String The thread id of the message to send. This is
   immutable and set by the server to the *threadId* property of the
   message referenced by the *messageId*.
 * *envelope*: Envelope|null Information for use when sending via SMTP.
   This is immutable.

An *Envelope* object has the following properties:

   * *mailFrom*: String The email address to use as the return address
     in the SMTP submission. The JMAP server MAY allow this to be the
     empty string.
   * *mailFromParams*: String[String]|null SMTP parameters to pass
     with the MAIL FROM address. Each key is a parameter name, and the
     value the parameter value. In both cases, any xtext or unitext
     encodings are removed ([@!RFC3461], [@!RFC6533]) and JSON string
     encoding applied.

When a JMAP server performs a message submission, it MAY use the same id
string for the [@!RFC3461] ENVID parameter and the MessageSubmission
object id. Servers that do this MAY replace a client-provided value  for
ENVID with a server-provided value.

   * *rcptTo*: String[String[String]|null] The keys of this object are
     the email addresses to send the message to. The value is either
     null, or another object representing SMTP RCPT TO parameters to
     pass with this recipient. Each key is a parameter name, and the
     value the parameter value. In both cases, any xtext or unitext
     encodings are removed ([@!RFC3461], [@!RFC6533]) and JSON string
     encoding applied.

If the *envelope* property is null or omitted on creation, the server
MUST generate this from the referenced message as follows:

   * *mailFrom*: The email in the *Sender* header, if present, otherwise
     the *From* header, if present.

If multiple addresses are present in one of these headers, or there
is more than one *Sender*/*From* header, the server SHOULD reject
the message as invalid but otherwise MUST take the first email
address in the last *Sender*/*From* header in the [@!RFC5322]
version of the message.

If the address found from this is not allowed by the identity associated
with this submission, the *email* property from the identity MUST be
used instead.

   * *mailFromParams*: null

   * *rcptTo*: An object with the keys being the deduplicated set of
     email addresses from the *To*, *Cc* and *Bcc* headers, if present,
     and the value for each being null.
 * *sendAt*: Date The date the message was/will be released for
   delivery. This is server-set and immutable.

If the client successfully used [@!RFC4865] FUTURERELEASE with the
message, this MUST be the time when the server will release the message;
otherwise it MUST be the time the MessageSubmission was created.

 * *undoStatus*: String This represents whether the submission may be
   canceled. This is server set and MUST be one of the following values:

   * "pending": It MAY be possible to cancel this submission.
   * "final": The message has been relayed to at least one recipient in
     a manner that cannot be recalled. It is no longer possible to
     cancel this submission.
   * "canceled": The message submission was canceled and will not be
     delivered to any recipient. 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.

 * *deliveryStatus*: String[DeliveryStatus]|null This represents the
   delivery status for each of the message recipients, if known. This
   property is server-set and MAY not be supported by all servers, in
   which case it will remain null. Servers that support it SHOULD update
   the MessageSubmission object each time the status of any of the
   recipients changes.

This is a map from the email address of each recipient of the message,
to the most recent SMTP reply code/text known.

This property is server set and MAY not be supported by all servers, in
which case it will remain null. Servers that support it SHOULD update
the MessageSubmission object each time the status of one of the
recipients changes, even if some recipients are still being retried.
The *isFinal* property allows clients to know if the status may still
change further.

A *DeliveryStatus* object has the following properties:

   * *isQueued*: Boolean This is true if the server is still trying to
     send the message to this recipient (and so the *smtpReply* could
     still change), otherwise false.
   * *smtpReply*: String The SMTP reply string returned for this
     recipient when the server last tried to relay the message. This
     SHOULD be the response to the RCPT TO stage, unless this was
     accepted and the message as a whole rejected at the end of the DATA
     stage, in which case the DATA stage reply SHOULD be used instead.

For messages relayed via an alternative to SMTP, the server MAY generate
a synthetic string representing the status instead. If it does this, the
string MUST be of the following form:

     * A 3-digit SMTP reply code, as defined in [@!RFC5321],
       section 4.2.3.
     * Then a single space character.
     * Then an SMTP Enhanced Mail System Status Code as defined in
       [@!RFC3463], with a registry defined in [@!RFC5248].
     * Then a single space character.
     * Then an implementation-specific information string with a human
       readable explanation of the response.
   * *delivered*: String Represents whether the message has been
     succesfully delivered to the recipient. This MUST be one of the
     following values:

     * "unknown": The final delivery status is unknown, either because
       the delivery is still queued and being retried, or it was relayed
       to an external machine and no further information is available.
       This is the initial value.
     * "yes": The message was successfully delivered to the mailbox of
       the recipient.
     * "no": Message delivery to the recipient permanently failed. Note,
       succesful 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.

   * *displayed*: String Represents whether the message has been
     displayed to the recipient. This MUST be one of the following
     values:

     * "unknown": The display status is unknown. This is the
       initial value.
     * "yes": The message content has been displayed to the
       recipient. Note, there is no guarantee that the recipient has
       noticed, read, or understood the content. 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.

 * *dsnBlobIds*: String[] A list of blob ids for DSNs received for this
   submission, in order of receipt, oldest first. This is server-set.

 * *mdnBlobIds*: String[] A list of blob ids for MDNs received for this
   submission, in order of receipt, oldest first. This is server-set.JMAP servers SHOULD NOT expose DSN and MDN messages that correlate to a MessageSubmission object in responses to *getMessageList*. It SHOULD only expose them in the *dsnBlobIds* and *mdnblobIds* fields of this 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.

Links:

  1. https://github.com/jmapio/jmap/pull/99

---

From: "Chris Newman" <[email-masked]>
Date: Fri, 21 Jul 2017 10:25:04 +0200

Looks good to me.

		- Chris

On 19 Jul 2017, at 17:29, Neil Jenkins wrote:

> OK, I've taken on all the feedback from the mailing list and as 
> discussed at the IETF Prague meeting, and have updated the pull 
> request[1]. The interesting bit is the MessageSubmission object 
> definition, which I also include below for convenience. I think (hope) 
> this is pretty close to finished, so please do a final review before I 
> merge.
> Cheers,
> Neil.
>
> --------
> The MessageSubmission object represents the submission of a message 
> for delivery to one or more recipients. A *MessageSubmission* object 
> has the following properties:
>
>
>    submission, in order of receipt, oldest first. This is 
> server-set.JMAP servers SHOULD NOT expose DSN and MDN messages that 
> correlate to a MessageSubmission object in responses to 
> *getMessageList*. It SHOULD only expose them in the *dsnBlobIds* and 
> *mdnblobIds* fields of this 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.
>
> Links:
>
>   1. 
> https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_jmapio_jmap_pull_99&d=DwIFaQ&c=RoP1YumCXCgaWHvlZYR8PQcxBKCX5YTpkKY057SbK10&r=QBZgPENFbjFadxqU4HJ3ZDpRz3X1JlDY-keqMt52FFo&m=gZ8BsJE1nhSVdPcIJutq-IjfDKx6F21XQIJFaJm98vU&s=GRDYqGh3s-ov_V_EQqQeW-7or0XlCPWvxrhfjf405Go&e=

> _______________________________________________
> Jmap mailing list
> [email-masked]
> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_jmap&d=DwICAg&c=RoP1YumCXCgaWHvlZYR8PQcxBKCX5YTpkKY057SbK10&r=QBZgPENFbjFadxqU4HJ3ZDpRz3X1JlDY-keqMt52FFo&m=gZ8BsJE1nhSVdPcIJutq-IjfDKx6F21XQIJFaJm98vU&s=FeIDCfMS_WzhsVdtIezLLrRatQ64x7uFEwrM4VHEjCU&e=

---

From: Neil Jenkins <[email-masked]>
Date: Fri, 21 Jul 2017 19:25:28 +1000

One small syntax change based on feedback received off list: I've changed the structure of the Envelope object to be more consistent between rcptTo and mailFrom. New version below for reference.
Neil.

----
*envelope*: Envelope|null
 Information for use when sending via SMTP. This is immutable.

 * *mailFrom*: Address The email address to use as the return address in
   the SMTP submission, plus any parameters to pass with the MAIL FROM
   address. The JMAP server MAY allow the email to be the empty string.

 * *rcptTo*: Address[] The email addresses to send the message to, and
   any RCPT TO parameters to pass with the recipient.An *Address* object has the following properties:

 * *email*: String The email address being represented by the object.
 * *parameters*: Object|null Any parameters to send with the email.
   If supplied, each key in the object is a parameter name, and the
   value the parameter value. In both cases, any xtext or unitext
   encodings are removed ([@!RFC3461], [@!RFC6533]) and JSON string
   encoding applied.If the *envelope* property is null or omitted on creation, the server MUST generate this from the referenced message as follows:

 * *mailFrom*: The email in the *Sender* header, if present, otherwise
   the *From* header, if present, and no parameters.

 * *rcptTo*: The deduplicated set of email addresses from the *To*, *Cc*
   and *Bcc* headers, if present, with no parameters for any of them.