5Internet Engineering Task Force (IETF) R. Ouazana, Ed.
6Request for Comments: 9007 Linagora
7Category: Standards Track March 2021
11Handling Message Disposition Notification with the JSON Meta Application
16 This document specifies a data model for handling Message Disposition
17 Notifications (MDNs) (see RFC 8098) in the JSON Meta Application
18 Protocol (JMAP) (see RFCs 8620 and 8621).
22 This is an Internet Standards Track document.
24 This document is a product of the Internet Engineering Task Force
25 (IETF). It represents the consensus of the IETF community. It has
26 received public review and has been approved for publication by the
27 Internet Engineering Steering Group (IESG). Further information on
28 Internet Standards is available in Section 2 of RFC 7841.
30 Information about the current status of this document, any errata,
31 and how to provide feedback on it may be obtained at
32 https://www.rfc-editor.org/info/rfc9007.
36 Copyright (c) 2021 IETF Trust and the persons identified as the
37 document authors. All rights reserved.
39 This document is subject to BCP 78 and the IETF Trust's Legal
40 Provisions Relating to IETF Documents
41 (https://trustee.ietf.org/license-info) in effect on the date of
42 publication of this document. Please review these documents
43 carefully, as they describe your rights and restrictions with respect
44 to this document. Code Components extracted from this document must
45 include Simplified BSD License text as described in Section 4.e of
46 the Trust Legal Provisions and are provided without warranty as
47 described in the Simplified BSD License.
52 1.1. Notational Conventions
54 1.3. Addition to the Capabilities Object
59 3.1. Sending an MDN for a Received Email Message
60 3.2. Asking for an MDN When Sending an Email Message
61 3.3. Parsing a Received MDN
62 4. IANA Considerations
63 4.1. JMAP Capability Registration for "mdn"
64 4.2. JMAP Error Codes Registration for "mdnAlreadySent"
65 5. Security Considerations
66 6. Normative References
71 JMAP ("The JSON Meta Application Protocol (JMAP)" [RFC8620]) is a
72 generic protocol for synchronising data, such as mail, calendars, or
73 contacts, between a client and a server. It is optimised for mobile
74 and web environments, and it provides a consistent interface to
77 JMAP for Mail ("The JSON Meta Application Protocol (JMAP) for Mail"
78 [RFC8621]) specifies a data model for synchronising email data with a
79 server using JMAP. Clients can use this to efficiently search,
80 access, organise, and send messages.
82 Message Disposition Notifications (MDNs) are defined in [RFC8098] and
83 are used as "read receipts", "acknowledgements", or "receipt
86 A client can come across MDNs in different ways:
88 1. When receiving an email message, an MDN can be sent to the
89 sender. This specification defines an "MDN/send" method to cover
92 2. When sending an email message, an MDN can be requested. This
93 must be done with the help of a header field, as already
94 specified by [RFC8098]; the header field can already be handled
95 by guidance in [RFC8621].
97 3. When receiving an MDN, the MDN could be related to an existing
98 sent message. This is already covered by [RFC8621] in the
99 EmailSubmission object. A client might want to display detailed
100 information about a received MDN. This specification defines an
101 "MDN/parse" method to cover this case.
1031.1. Notational Conventions
105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
107 "OPTIONAL" in this document are to be interpreted as described in
108 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
109 capitals, as shown here.
111 Type signatures, examples, and property descriptions in this document
112 follow the conventions established in Section 1.1 of [RFC8620]. Data
113 types defined in the core specification are also used in this
116 Servers MUST support all properties specified for the new data types
117 defined in this document.
121 The same terminology is used in this document as in the core JMAP
124 Because keywords are case insensitive in IMAP but case sensitive in
125 JMAP, the "$mdnsent" keyword MUST always be used in lowercase.
1271.3. Addition to the Capabilities Object
129 Capabilities are announced as part of the standard JMAP Session
130 resource; see [RFC8620], Section 2. This defines a new capability,
131 "urn:ietf:params:jmap:mdn".
133 The capability "urn:ietf:params:jmap:mdn" being present in the
134 "accountCapabilities" property of an account represents support for
135 the "MDN" data type, parsing MDNs via the "MDN/parse" method, and
136 creating and sending MDN messages via the "MDN/send" method. Servers
137 that include the capability in one or more "accountCapabilities"
138 properties MUST also include the property in the "capabilities"
141 The value of this "urn:ietf:params:jmap:mdn" property is an empty
142 object both in the account's "accountCapabilities" property and in
143 the "capabilities" property.
147 An *MDN* object has the following properties:
149 * forEmailId: "Id|null"
151 The Email id of the received message to which this MDN is related.
152 This property MUST NOT be null for "MDN/send" but MAY be null in
153 the response from the "MDN/parse" method.
155 * subject: "String|null"
157 The subject used as "Subject" header field for this MDN.
159 * textBody: "String|null"
161 The human-readable part of the MDN, as plain text.
163 * includeOriginalMessage: "Boolean" (default: false)
165 If "true", the content of the original message will appear in the
166 third component of the multipart/report generated for the MDN.
167 See [RFC8098] for details and security considerations.
169 * reportingUA: "String|null"
171 The name of the Mail User Agent (MUA) creating this MDN. It is
172 used to build the MDN report part of the MDN. Note that a "null"
173 value may have better privacy properties.
175 * disposition: "Disposition"
177 The object containing the diverse MDN disposition options.
179 * mdnGateway: "String|null" (server-set)
181 The name of the gateway or Message Transfer Agent (MTA) that
182 translated a foreign (non-Internet) message disposition
183 notification into this MDN.
185 * originalRecipient: "String|null" (server-set)
187 The original recipient address as specified by the sender of the
188 message for which the MDN is being issued.
190 * finalRecipient: "String|null"
192 The recipient for which the MDN is being issued. If set, it
193 overrides the value that would be calculated by the server from
194 the Identity defined in the "MDN/send" method, unless explicitly
197 * originalMessageId: "String|null" (server-set)
199 The "Message-ID" header field [RFC5322] (not the JMAP id) of the
200 message for which the MDN is being issued.
202 * error: "String[]|null" (server-set)
204 Additional information in the form of text messages when the
205 "error" disposition modifier appears.
207 * extensionFields: "String[String]|null"
209 The object where keys are extension-field names, and values are
210 extension-field values (see [RFC8098], Section 3.3).
212 A *Disposition* object has the following properties:
214 * actionMode: "String"
216 This MUST be one of the following strings: "manual-action" /
219 * sendingMode: "String"
221 This MUST be one of the following strings: "mdn-sent-manually" /
222 "mdn-sent-automatically"
226 This MUST be one of the following strings: "deleted" /
227 "dispatched" / "displayed" / "processed"
229 See [RFC8098] for the exact meaning of these different fields. These
230 fields are defined as case insensitive in [RFC8098] but are case
231 sensitive in this RFC and MUST be converted to lowercase by "MDN/
236 The "MDN/send" method sends a message in the style of [RFC5322] from
237 an MDN object. When calling this method, the "using" property of the
238 Request object MUST contain the capabilities
239 "urn:ietf:params:jmap:mdn" and "urn:ietf:params:jmap:mail"; the
240 latter because of the implicit call to "Email/set" and the use of
241 Identity objects, which is described below. The method takes the
246 The id of the account to use.
250 The id of the Identity to associate with these MDNs. The server
251 will use this identity to define the sender of the MDNs and to set
252 the "finalRecipient" field.
256 A map of the creation id (client specified) to MDN objects.
258 * onSuccessUpdateEmail: "Id[PatchObject]|null"
260 A map of the id to an object containing properties to update on
261 the Email object referenced by the "MDN/send" if the sending
262 succeeds. This will always be a backward reference to the
263 creation id (see the example below in Section 3.1).
265 The response has the following arguments:
269 The id of the account used for the call.
271 * sent: "Id[MDN]|null"
273 A map of the creation id to an MDN containing any properties that
274 were not set by the client. This includes any properties that
275 were omitted by the client and thus set to a default by the
276 server. This argument is null if no MDN objects were successfully
279 * notSent: "Id[SetError]|null"
281 A map of the creation id to a SetError object for each record that
282 failed to be sent or null if all successful.
284 In this context, the existing SetError types defined in [RFC8620] and
285 [RFC8621] are interpreted as follows:
287 notFound: The reference "forEmailId" cannot be found or has no valid
288 "Disposition-Notification-To" header field.
290 forbidden: "MDN/send" would violate an Access Control List (ACL) or
291 other permissions policy.
293 forbiddenFrom: The user is not allowed to use the given
294 "finalRecipient" property.
296 overQuota: "MDN/send" would exceed a server-defined limit on the
297 number or total size of sent MDNs. It could include limitations
300 tooLarge: "MDN/send" would result in an MDN that exceeds a server-
301 defined limit for the maximum size of an MDN or more generally, on
304 rateLimit: Too many MDNs or email messages have been created
305 recently, and a server-defined rate limit has been reached. It
306 may work if tried again later.
308 invalidProperties: The record given is invalid in some way.
310 The following is a new SetError:
312 mdnAlreadySent: The message has the "$mdnsent" keyword already set.
314 If the "accountId" or "identityId" given cannot be found, the method
315 call is rejected with an "invalidArguments" error.
317 The client MUST NOT issue an "MDN/send" request if the message has
318 the "$mdnsent" keyword set.
320 When sending the MDN, the server is in charge of generating the
321 "originalRecipient" and "originalMessageId" fields according to
322 [RFC8098]. "finalRecipient" will also generally be generated by the
323 server based on the provided identity, but if specified by the client
324 and allowed (see Section 5), the server will use the client-provided
327 The client is expected to explicitly update each "Email" for which an
328 "MDN/send" has been invoked in order to set the "$mdnsent" keyword on
329 these messages. To ensure that, the server MUST reject an "MDN/send"
330 that does not result in setting the keyword "$mdnsent". Thus, the
331 server MUST check that the "onSuccessUpdateEmail" property of the
332 method is correctly set to update this keyword.
336 This method allows a client to parse blobs as messages in the style
337 of [RFC5322] to get MDN objects. This can be used to parse and get
338 detailed information about blobs referenced in the "mdnBlobIds" of
339 the EmailSubmission object or any email message the client could
342 The "forEmailId" property can be null or missing if the
343 "originalMessageId" property is missing or does not refer to an
344 existing message or if the server cannot efficiently calculate the
345 related message (for example, if several messages get the same
346 "Message-ID" header field).
348 The "MDN/parse" method takes the following arguments:
352 The id of the account to use.
356 The ids of the blobs to parse.
358 The response has the following arguments:
362 The id of the account used for the call.
364 * parsed: "Id[MDN]|null"
366 A map of the blob id to a parsed MDN representation for each
367 successfully parsed blob or null if none.
369 * notParsable: "Id[]|null"
371 A list of ids given that corresponds to blobs that could not be
372 parsed as MDNs or null if none.
374 * notFound: "Id[]|null"
376 A list of blob ids given that could not be found or null if none.
378 The following additional errors may be returned instead of the "MDN/
381 requestTooLarge: The number of ids requested by the client exceeds
382 the maximum number the server is willing to process in a single
385 invalidArguments: If the given "accountId" cannot be found, the MDN
386 parsing is rejected with an "invalidArguments" error.
3903.1. Sending an MDN for a Received Email Message
392 A client can use the following request to send an MDN back to the
396 "accountId": "ue150411c",
397 "identityId": "I64588216",
400 "forEmailId": "Md45b47b4877521042cec0938",
401 "subject": "Read receipt for: World domination",
402 "textBody": "This receipt shows that the email has been
403 displayed on your recipient's computer. There is no
404 guarantee it has been read or understood.",
405 "reportingUA": "joes-pc.cs.example.com; Foomail 97.1",
407 "actionMode": "manual-action",
408 "sendingMode": "mdn-sent-manually",
412 "EXTENSION-EXAMPLE": "example.com"
416 "onSuccessUpdateEmail": {
418 "keywords/$mdnsent": true
423 If the email id matches an existing email message without the
424 "$mdnsent" keyword, the server can answer:
427 "accountId": "ue150411c",
430 "finalRecipient": "rfc822; john@example.com",
431 "originalMessageId": "<199509192301.23456@example.org>"
436 "accountId": "ue150411c",
440 "Md45b47b4877521042cec0938": {}
444 If the "$mdnsent" keyword has already been set, the server can answer
448 "accountId": "ue150411c",
451 "type": "mdnAlreadySent",
452 "description" : "$mdnsent keyword is already present"
4573.2. Asking for an MDN When Sending an Email Message
459 This is done with the "Email/set" "create" method of [RFC8621].
462 "accountId": "ue150411c",
473 "name": "Joe Bloggs",
474 "email": "joe@example.com"
478 "email": "john@example.com"
480 "header:Disposition-Notification-To:asText": "joe@example.com",
481 "subject": "World domination",
487 Note the specified "Disposition-Notification-To" header field
488 indicating where to send the MDN (usually the sender of the message).
4903.3. Parsing a Received MDN
492 The client issues a parse request:
495 "accountId": "ue150411c",
496 "blobIds": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
502 "accountId": "ue150411c",
504 "0f9f65ab-dc7b-4146-850f-6e4881093965": {
505 "forEmailId": "Md45b47b4877521042cec0938",
506 "subject": "Read receipt for: World domination",
507 "textBody": "This receipt shows that the email has been
508 displayed on your recipient's computer. There is no
509 guarantee it has been read or understood.",
510 "reportingUA": "joes-pc.cs.example.com; Foomail 97.1",
512 "actionMode": "manual-action",
513 "sendingMode": "mdn-sent-manually",
516 "finalRecipient": "rfc822; john@example.com",
517 "originalMessageId": "<199509192301.23456@example.org>"
522 In the case that a blob id is not found, the server would respond:
525 "accountId": "ue150411c",
526 "notFound": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
529 If the blob id has been found but is not parsable, the server would
533 "accountId": "ue150411c",
534 "notParsable": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
5374. IANA Considerations
5394.1. JMAP Capability Registration for "mdn"
541 This section registers the "mdn" JMAP Capability in the "JMAP
542 Capabilities" registry as follows:
544 Capability Name: "urn:ietf:params:jmap:mdn"
546 Change Controller: IETF
547 Security and Privacy Considerations: This document, Section 5.
548 Reference: This document
5504.2. JMAP Error Codes Registration for "mdnAlreadySent"
552 IANA has registered one new error code in the "JMAP Error Codes"
553 registry, as defined in [RFC8620].
555 JMAP Error Code: mdnAlreadySent
557 Change Controller: IETF
558 Description: The message has the "$mdnsent" keyword already set.
559 The client MUST NOT try again to send an MDN for this message.
560 Reference: This document, Section 2.1
5625. Security Considerations
564 The same considerations regarding MDN (see [RFC8098] and [RFC3503])
565 apply to this document.
567 In order to reinforce trust regarding the relation between the user
568 sending an email message and the identity of this user, the server
569 SHOULD validate in conformance to the provided Identity that the user
570 is permitted to use the "finalRecipient" value and return a
571 "forbiddenFrom" error if not.
5736. Normative References
575 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
576 Requirement Levels", BCP 14, RFC 2119,
577 DOI 10.17487/RFC2119, March 1997,
578 <https://www.rfc-editor.org/info/rfc2119>.
580 [RFC3503] Melnikov, A., "Message Disposition Notification (MDN)
581 profile for Internet Message Access Protocol (IMAP)",
582 RFC 3503, DOI 10.17487/RFC3503, March 2003,
583 <https://www.rfc-editor.org/info/rfc3503>.
585 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
586 DOI 10.17487/RFC5322, October 2008,
587 <https://www.rfc-editor.org/info/rfc5322>.
589 [RFC8098] Hansen, T., Ed. and A. Melnikov, Ed., "Message Disposition
590 Notification", STD 85, RFC 8098, DOI 10.17487/RFC8098,
591 February 2017, <https://www.rfc-editor.org/info/rfc8098>.
593 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
594 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
595 May 2017, <https://www.rfc-editor.org/info/rfc8174>.
597 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
598 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
599 2019, <https://www.rfc-editor.org/info/rfc8620>.
601 [RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application
602 Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621,
603 August 2019, <https://www.rfc-editor.org/info/rfc8621>.
607 Raphaël Ouazana (editor)
609 100 Terrasse Boieldieu - Tour Franklin
610 92042 Paris - La Défense CEDEX
613 Email: rouazana@linagora.com
614 URI: https://www.linagora.com