src-advisory/SRCmail
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add RFC specifications (txt + pdf) organized by category (core, mail, contacts, calendar, sieve, quotas, auth)

Browse Source
This commit is contained in:
Linus Rath
2026-03-13 02:51:07 +01:00
parent 5a679275ca
commit 1267efa307
31 changed files with 57249 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
specifications/mail/rfc2369.pdf
BIN
View File
Binary file not shown.
specifications/mail/rfc2369.txt
+843
View File
@@ -0,0 +1,843 @@
Network Working Group G. Neufeld
Request for Comments: 2369 Nisto
Category: Standards Track J. Baer
SkyWeyr Technologies
July 1998
The Use of URLs as Meta-Syntax for Core Mail List Commands
and their Transport through Message Header Fields
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1998). All Rights Reserved.
Abstract
The mailing list command specification header fields are a set of
structured fields to be added to email messages sent by email
distribution lists. Each field typically contains a URL (usually
mailto [RFC2368]) locating the relevant information or performing the
command directly. The three core header fields described in this
document are List-Help, List-Subscribe, and List-Unsubscribe.
There are three other header fields described here which, although
not as widely applicable, will have utility for a sufficient number
of mailing lists to justify their formalization here. These are
List-Post, List-Owner and List-Archive.
By including these header fields, list servers can make it possible
for mail clients to provide automated tools for users to perform list
functions. This could take the form of a menu item, push button, or
other user interface element. The intent is to simplify the user
experience, providing a common interface to the often cryptic and
varied mailing list manager commands.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.
Neufeld & Baer Standards Track [Page 1]
RFC 2369 URLs as Meta-Syntax July 1998
1. Introduction
This is a proposal for additional header fields to be added to email
messages sent by email distribution lists. The content of each new
field is typically a URL - usually mailto [RFC2368] - which locates
the relevant information or performs the command directly. MTAs
generating the header fields SHOULD usually include a mailto based
command, in addition to any other protocols used, in order to support
users who do not have access to non-mail-based protocols.
Implementing these fields will be optional. Significant functionality
and convenience can be gained by including them, however. Many list
managers, especially as the proposal first gains acceptance, MAY
choose to implement only one or two of the fields. The List-Help
field is the most useful individual field since it provides an access
point to detailed user support information, and accommodates almost
all existing list managers command sets. The List-Subscribe and
List-Unsubscribe fields are also very useful, but cannot describe
some list manager syntaxes at this time (those which require variable
substitution). See appendix A.5 for an explanation.
The description of command syntax provided by the fields can be used
by mail client applications to provide simplified and consistent user
access to email distribution list functions. This could take the form
of menu items, push buttons, or other user interface elements. The
intent is to simplify the user experience, providing a common
interface to the often cryptic and varied mailing list manager
commands.
Consideration has been given to avoiding the creation of too many
fields, while at the same time avoiding the overloading of individual
fields and keeping the syntax clear and simple.
The use of these fields does not remove the requirement to support
the -Request command address for mailing lists [RFC2142].
2. The Command Syntax
The list header fields are subject to the encoding and character
restrictions for mail headers as described in [RFC822]. Additionally,
the URL content is further restricted to the set of URL safe
characters [RFC1738].
The contents of the list header fields mostly consist of angle-
bracket ('<', '>') enclosed URLs, with internal whitespace being
ignored. MTAs MUST NOT insert whitespace within the brackets, but
client applications should treat any whitespace, that might be
inserted by poorly behaved MTAs, as characters to ignore.
Neufeld & Baer Standards Track [Page 2]
RFC 2369 URLs as Meta-Syntax July 1998
A list of multiple, alternate, URLs MAY be specified by a comma-
separated list of angle-bracket enclosed URLs. The URLs have order of
preference from left to right. The client application should use the
left most protocol that it supports, or knows how to access by a
separate application. By this mechanism, protocols like http may be
specified while still providing the basic mailto support for those
clients who do not have access to non-mail protocols. The client
should only use one of the available URLs for a command, using
another only if the first one used failed.
The use of URLs allows for the use of the syntax with existing URL
supporting applications. As the standard for URLs is extended, the
list header fields will gain the benefit of those extensions.
Additionally, the use of URLs provides access to multiple transport
protocols (such as ftp and http) although it is expected that the
"mailto" protocol [RFC2368] will be the focus of most use of the list
header fields. Use of non-mailto protocols should be considered in
light of those users who do not have access to the specified
mechanism (those who only have email - with no web access).
Command syntaxes requiring variable fields to be set by the client
(such as including the user's email address within a command) are not
supported by this implementation. However, systems using such
syntaxes SHOULD still take advantage of the List-Help field to
provide the user with detailed instructions as needed or - perhaps
more usefully - provide access to some form of structured command
interface such as an HTML-based form.
The additional complications of supporting variable fields within the
command syntax was determined to be too difficult to support by this
protocol and would compromise the likelihood of implementation by
software authors.
To allow for future extension, client applications MUST follow the
following guidelines for handling the contents of the header fields
described in this document:
1) Except where noted for specific fields, if the content of the
field (following any leading whitespace, including comments)
begins with any character other than the opening angle bracket
'<', the field SHOULD be ignored.
2) Any characters following an angle bracket enclosed URL SHOULD be
ignored, unless a comma is the first non-whitespace/comment
character after the closing angle bracket.
Neufeld & Baer Standards Track [Page 3]
RFC 2369 URLs as Meta-Syntax July 1998
3) If a sub-item (comma-separated item) within the field is not an
angle-bracket enclosed URL, the remainder of the field (the
current, and all subsequent, sub-items) SHOULD be ignored.
3. The List Header Fields
This document presents header fields which will provide the
command syntax description for the 'core' and key secondary
functions of most email distribution lists. The fields implemented
on a given list SHOULD be included on all messages distributed by
the list (including command responses to individual users), and on
other messages where the message clearly applies to one distinct
list. There MUST be no more than one of each field present in any
given message.
These fields MUST only be generated by mailing lists, not end
users.
3.1. List-Help
The List-Help field is the most important of the header fields
described in this document. It would be acceptable for a list
manager to include only this field, since by definition it SHOULD
direct the user to complete instructions for all other commands.
Typically, the URL specified would request the help file, perhaps
incorporating an HTML form for list commands, for the list, and
alternatively provide access to an instructive website.
Examples:
List-Help: <mailto:list@host.com?subject=help> (List Instructions)
List-Help: <mailto:list-manager@host.com?body=info>
List-Help: <mailto:list-info@host.com> (Info about the list)
List-Help: <http://www.host.com/list/>, <mailto:list-info@host.com>
List-Help: <ftp://ftp.host.com/list.txt> (FTP),
<mailto:list@host.com?subject=help>
3.2. List-Unsubscribe
The List-Unsubscribe field describes the command (preferably using
mail) to directly unsubscribe the user (removing them from the list).
Examples:
List-Unsubscribe: <mailto:list@host.com?subject=unsubscribe>
List-Unsubscribe: (Use this command to get off the list)
<mailto:list-manager@host.com?body=unsubscribe%20list>
List-Unsubscribe: <mailto:list-off@host.com>
Neufeld & Baer Standards Track [Page 4]
RFC 2369 URLs as Meta-Syntax July 1998
List-Unsubscribe: <http://www.host.com/list.cgi?cmd=unsub&lst=list>,
<mailto:list-request@host.com?subject=unsubscribe>
3.3. List-Subscribe
The List-Subscribe field describes the command (preferably using
mail) to directly subscribe the user (request addition to the list).
Examples:
List-Subscribe: <mailto:list@host.com?subject=subscribe>
List-Subscribe: <mailto:list-request@host.com?subject=subscribe>
List-Subscribe: (Use this command to join the list)
<mailto:list-manager@host.com?body=subscribe%20list>
List-Subscribe: <mailto:list-on@host.com>
List-Subscribe: <http://www.host.com/list.cgi?cmd=sub&lst=list>,
<mailto:list-manager@host.com?body=subscribe%20list>
3.4. List-Post
The List-Post field describes the method for posting to the list.
This is typically the address of the list, but MAY be a moderator, or
potentially some other form of submission. For the special case of a
list that does not allow posting (e.g., an announcements list), the
List-Post field may contain the special value "NO".
Examples:
List-Post: <mailto:list@host.com>
List-Post: <mailto:moderator@host.com> (Postings are Moderated)
List-Post: <mailto:moderator@host.com?subject=list%20posting>
List-Post: NO (posting not allowed on this list)
3.5. List-Owner
The List-Owner field identifies the path to contact a human
administrator for the list. The URL MAY contain the address of a
administrator for the list, the mail system administrator, or any
other person who can handle user contact for the list. There is no
need to specify List-Owner if it is the same person as the mail
system administrator (postmaster).
Examples:
List-Owner: <mailto:listmom@host.com> (Contact Person for Help)
List-Owner: <mailto:grant@foo.bar> (Grant Neufeld)
List-Owner: <mailto:josh@foo.bar?Subject=list>
Neufeld & Baer Standards Track [Page 5]
RFC 2369 URLs as Meta-Syntax July 1998
3.6. List-Archive
The List-Archive field describes how to access archives for the list.
Examples:
List-Archive: <mailto:archive@host.com?subject=index%20list>
List-Archive: <ftp://ftp.host.com/pub/list/archive/>
List-Archive: <http://www.host.com/list/archive/> (Web Archive)
4. Supporting Nested Lists
A list that is a sublist for another list in a nested mailing list
hierarchy will need to modify some of the List- header fields, while
leaving others as the parent list set them.
Sublists SHOULD remove the parent list's List-Help, List-Subscribe,
List-Unsubscribe and List-Owner fields, and SHOULD insert their own
versions of those fields.
If the sublist provides its own archive, it SHOULD replace the List-
Archive with its own. Otherwise, it MUST leave the List-Archive field
untouched.
Dependant on how postings to the list are handled, the sublist MAY
replace the List-Post field. The appropriateness of whether to
replace List-Post is left to the determination of the individual list
managers. If the intention is that postings should be distributed to
all members of the primary list, List-Post should not be changed by a
sublist in such a way that postings will be distributed only to
members of the sublist.
5. Security Considerations
There are very few new security concerns generated with this
proposal. Message headers are an existing standard, designed to
easily accommodate new types. There may be concern with multiple
fields being inserted or headers being forged, but these are problems
inherent in Internet email, not specific to the protocol described in
this document. Further, the implications are relatively harmless.
Mail list processors should not allow any user-originated list header
fields to pass through to their lists, lest they confuse the user and
have the potential to create security problems.
On the client side, there may be some concern with posts or commands
being sent in error. It is required that the user have a chance to
confirm any action before it is executed. In the case of mailto, it
Neufeld & Baer Standards Track [Page 6]
RFC 2369 URLs as Meta-Syntax July 1998
may be appropriate to create the correctly formatted message without
sending it, allowing the user to see exactly what is happening and
giving the user the opportunity to approve or discard the message
before it is sent.
All security considerations for the use of URLs [RFC1738] apply
equally to this protocol. Mail client applications should not support
list header field URLs which could compromise the security of the
user's system. This includes the "file://" URL type which could
potentially be used to trigger the execution of a local application
on some user systems.
6. Acknowledgements
The numerous participants of the List-Header [5], ListMom-Talk [6],
List-Managers and MIDA-Mail mailing lists contributed much to the
formation and structure of this document.
Keith Moore <moore@cs.utk.edu> and Christopher Allen
<ChristopherA@consensus.com> provided guidance on the standards
process.
Neufeld & Baer Standards Track [Page 7]
RFC 2369 URLs as Meta-Syntax July 1998
A. Background Discussion
This proposal arose from discussions started on the ListMom-Talk
Discussion List [6]. When the discussion reached a sufficient level,
a separate list was formed for discussing this proposal, the List
Headers Mail List [5] for deeper discussion. We have included
summaries of key issues raised, in order to show some of the
alternatives examined and reasons for our decisions.
A.1. Multiple header fields vs. a single header field
Use of a single header field for transporting command meta-syntax was
rejected for a number of reasons.
Such a field would require the creation of a new meta-syntax in order
to describe the list commands (as opposed to the use of the widely
deployed URL syntax which was chosen for this implementation). Every
additional layer of complexity and newness reduces the likelihood of
actual implementation because it will require additional work to
support. Also, by using the existing URL syntax, we can profit from
the end users' knowledge of that syntax and ability to use it even if
their client applications do not support the list header fields.
Restricting the transport of meta-syntax to the use of a single
header field also introduces complications with header field size
limitations. Most individual commands can easily be described in a
single line, but describing a multitude of commands can take up many
lines in the field and runs a greater risk of being modified by an
existing server on route.
The client implementation is also easier with multiple fields, since
each command can be supported and implemented individually,
completely independent of the others. Thus, some list managers or
mail clients can choose to implement a subset of the fields based on
the specific needs of their individual lists.
Finally, the format described in this document is simple and well
recognized, which reduces the chances of errors in implementation and
parsing.
A.2. URLs vs. parameter lists
URLs are already an established syntax which is flexible, well-
defined, and in wide spread use. As its definition matures and
expands, the abilities of the list fields will grow as well, without
requiring modification of this proposal. URLs are well prepared to
handle future protocols and developments, and can easily describe the
different existing access protocols such as mailto, http and ftp.
Neufeld & Baer Standards Track [Page 8]
RFC 2369 URLs as Meta-Syntax July 1998
Many clients already have functionality for recognizing, parsing, and
evaluating URLs, either internally or by passing the request to a
helper application. This makes implementation easier and more
realistic. As an example, this existing support for URL parsing
allowed us to add prototype list header functionality to existing
mail clients (Eudora and Emailer for the Macintosh) without modifying
their source code.
A.3. Why not just create a standard command language?
A standard command language, supported by all email list services,
would go a long way to reducing the problems of list access that
currently plague existing services. It would reduce the amount of
learning required by end users and allow for a number of common
support tools to be developed.
However, such standardization does pose problems in the areas of
multi-lingual support and the custom needs of individual mailing
lists. The development of such a standard is also expected to be met
with a slow adoption rate by software developers and list service
providers.
These points do not preclude the development of such a standard (in
fact, it would suggest that we should start sooner rather than
later), but we do need a solution that can be widely supported by the
current list services.
We can support most existing list manager command syntaxes without a
standard command language. By using URLs, we allow alternate access
methods a standard command language probably wouldn't enable, such as
web based control.
Finally, client support for a standard command language is not at all
clear or necessarily simple to implement. The variety and large
number of commands existing today would require complicated user
interfaces which could be confusing and difficult to implement. By
restricting this proposal to the core functions, the client
implementation is much simpler, which significantly increases the
likelihood of implementation (as evidenced by the support already
announced by a number of client and server application authors).
A.4. Internationalization
Multilingual support is up to the URL standard. If URLs support it,
then the List- header fields support it. This is another advantage of
using URLs as the building blocks for the list header fields.
Neufeld & Baer Standards Track [Page 9]
RFC 2369 URLs as Meta-Syntax July 1998
A.5. Variable Substitution
Variables would allow the List- header fields to accommodate nearly
every existing list manager. However, it would immeasurably increase
the complexity of the entire proposal, and possibly involve
redefining the URL standard, or force us to use something more
complicated (and hence more difficult to implement) than URLs to
describe the command syntax.
Parameters would either have to be mandatory (i.e. the user agent
doesn't submit the message if it doesn't know what text to
substitute) or you need a way to say "if you know this parameter, add
its text here; otherwise, do this" where "this" is either: (a)
substitute a constant string, or (b) fail.
The reason you would want a facility like this is because some list
server applications insist on having certain parameters like users'
names, which the user agent might or might not know. e.g. listserv
insists on having a first name and a last name if you supply either
one.
Which could lead to something like the UNIX shell syntax, where
${foo-bar} means substitute the value of parameter "foo" if "foo" is
defined, else substitute the string "bar". Perhaps $foo would mean
"substitute the value of parameter foo if it is defined, else
substitute the empty string"
This all seems far too complicated for the gains involved, especially
since the use of variables can often be avoided.
The use of variables in the command syntaxes of list services appears
to be lessening and does not, in any case, apply to all commands.
While the unsubscribe and subscribe command header fields may not be
usable by those systems which require the use of variables, the help
field will still provide end users with a consistent point of access
through which they can get support for their use of the list.
A.6. Why not use a specialized MIME part instead of header fields?
MIME parts were considered, but because most mail clients currently
either don't support MIME or are not equipped to handle such
specialized parts - such an implementation would result in problems
for end users. It is also not as easy for many list servers to
implement MIME as it is to implement new header fields.
However, we are looking at the design of a MIME part to more fully
describe list command syntax, as well as trying to find ways to get
it supported by the applicable software.
Neufeld & Baer Standards Track [Page 10]
RFC 2369 URLs as Meta-Syntax July 1998
A.7. Why include a Subscribe command?
Subscribe and Unsubscribe are the key commands needed by almost every
list. Other commands, such as digest mode, are not as widely
supported.
Additionally, users who have unsubscribed (before going on vacation,
or for whatever other reason) may want to resubscribe to a list. Or,
a message may be forwarded/bounced from a subscriber to a non-
subscriber. Or, the user may change addresses and want to subscribe
from their new address. Having the List-Subscribe field available
could certainly help in all these cases.
A.8. The Dangers of Header Bloat
At what point are there just too many header fields? It really
varies on a list by list basis. On some lists, the majority of users
will never be aware of a field unless the client software provides
some alternative user interface to it (akin to the Reply-To field).
On others, the users will often see the header fields of messages and
would be able to recognize the function of the URLs contained within.
The flexibility afforded by the protocol described in this document
(in that the header fields may be individually implemented as deemed
appropriate) provides list administrators with sufficient 'room to
maneuver' to meet their individual needs.
Neufeld & Baer Standards Track [Page 11]
RFC 2369 URLs as Meta-Syntax July 1998
B. Client Implementation
B.1. Guidelines
For 'mailto' URL based commands, mail client applications may choose
to provide specialized feedback (such as presenting a dialog or
alert), instead of the actual command email message, asking for
command confirmation from the user. The feedback should identify the
message destination and command within a more descriptive
explanation. For example:
"Do you want to send the unsubscription command 'unsubscribe
somelist' to 'somelist-request@some.host.com'? Sending the command
will result in your removal from the associated list."
If the user has multiple email addresses supported by the mail
client, the client application should prompt the user for which
address to use when subscribing or performing some other action where
the address to use cannot be specifically determined. When
unsubscribing or such, the address that is subscribed should be used,
unless that is not known by the application and cannot be determined
from the message headers.
B.2. Implementation Options
The following implementation possibilities are suggested here to give
some idea as to why these new header fields will be useful, and how
they could be supported.
In most cases, it may be helpful to disable the interface for the
commands when not applicable to the currently selected message.
B.2.1. Key combinations and command lines
On text based systems which utilize command lines or key
combinations, each field could be implemented as a separate command.
Thus one combination would subscribe the user, another would
unsubscribe, a third request help, etc. The commands would only be
available on messages containing the list header fields.
B.2.2. Menu items
On graphical systems which have menus, these commands could take the
form of a menu or sub-menu of items. For example, a "Lists" menu
might appear when viewing messages containing the header fields, with
items named "Subscribe", "Unsubscribe", "Get Help", "Post Message to
Neufeld & Baer Standards Track [Page 12]
RFC 2369 URLs as Meta-Syntax July 1998
List", "Contact List Owner" and "Access List Archive". This menu
could be disabled when not applicable to the current message or
disappear entirely.
B.2.3. Push Buttons and Pallettes
On graphical window systems, buttons could be placed in the window of
the message, a toolbar, or in a floating pallette of their own. Each
button could correspond to a command, with names "Subscribe",
"Unsubscribe", "Get Help", "Post to List", "List Owner" and
"Archive". These buttons or pallettes could be disabled when not
applicable to the current message or disappear entirely.
B.2.4 Feedback to the User
If using a dialog interface (or other feedback element) the client
application MUST include an option for the user to review (and
possibly modify) the message before it is sent. The application may
also find it useful to provide a link to more detailed context-
sensitive assistance about mail list access in general.
References
[RFC822] Crocker, D., "Standard for the Format of ARPA
Internet Text Messages", STD 11, RFC 822, August 1982.
[RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill,
"Uniform Resource Locators (URL)" RFC 1738, December 1994.
[RFC2142] Crocker, D., "Mailbox Names for Common Services, Roles and
Functions", RFC 2142, May 1997.
[RFC2368] Hoffman, P., Masinter, L., and J. Zawinski, "The mailto URL
scheme", RFC 2368, July 1998.
[5] "List-Header" Mail list. list-header@list.nisto.com
<URL:http://www.nisto.com/listspec/mail/>
<URL:http://www.nisto.com/listspec/>
[6] "ListMom-Talk" Mail list. listmom-talk@skyweyr.com
<URL:http://cgi.skyweyr.com/ListMom.Home>
Neufeld & Baer Standards Track [Page 13]
RFC 2369 URLs as Meta-Syntax July 1998
Editors' Addresses
Joshua D. Baer
Box 273
4902 Forbes Avenue
Pittsburgh, PA 15213-3799
USA
EMail: josh@skyweyr.com
Grant Neufeld
Calgary, Alberta
Canada
EMail: grant@acm.org
Web: http://www.nisto.com/
Neufeld & Baer Standards Track [Page 14]
RFC 2369 URLs as Meta-Syntax July 1998
Full Copyright Statement
Copyright (C) The Internet Society (1998). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Neufeld & Baer Standards Track [Page 15]
specifications/mail/rfc5322.pdf
BIN
View File
Binary file not shown.
specifications/mail/rfc5322.txt
+3195
View File
File diff suppressed because it is too large Load Diff
specifications/mail/rfc8621.pdf
BIN
View File
Binary file not shown.
specifications/mail/rfc8621.txt
+6051
View File
File diff suppressed because it is too large Load Diff
specifications/mail/rfc9007.pdf
BIN
View File
Binary file not shown.
specifications/mail/rfc9007.txt
+614
View File
@@ -0,0 +1,614 @@
Internet Engineering Task Force (IETF) R. Ouazana, Ed.
Request for Comments: 9007 Linagora
Category: Standards Track March 2021
ISSN: 2070-1721
Handling Message Disposition Notification with the JSON Meta Application
Protocol (JMAP)
Abstract
This document specifies a data model for handling Message Disposition
Notifications (MDNs) (see RFC 8098) in the JSON Meta Application
Protocol (JMAP) (see RFCs 8620 and 8621).
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9007.
Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction
1.1. Notational Conventions
1.2. Terminology
1.3. Addition to the Capabilities Object
2. MDN
2.1. MDN/send
2.2. MDN/parse
3. Samples
3.1. Sending an MDN for a Received Email Message
3.2. Asking for an MDN When Sending an Email Message
3.3. Parsing a Received MDN
4. IANA Considerations
4.1. JMAP Capability Registration for "mdn"
4.2. JMAP Error Codes Registration for "mdnAlreadySent"
5. Security Considerations
6. Normative References
Author's Address
1. Introduction
JMAP ("The JSON Meta Application Protocol (JMAP)" [RFC8620]) 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 it provides a consistent interface to
different data types.
JMAP for Mail ("The JSON Meta Application Protocol (JMAP) for Mail"
[RFC8621]) specifies a data model for synchronising email data with a
server using JMAP. Clients can use this to efficiently search,
access, organise, and send messages.
Message Disposition Notifications (MDNs) are defined in [RFC8098] and
are used as "read receipts", "acknowledgements", or "receipt
notifications".
A client can come across MDNs in different ways:
1. When receiving an email message, an MDN can be sent to the
sender. This specification defines an "MDN/send" method to cover
this case.
2. When sending an email message, an MDN can be requested. This
must be done with the help of a header field, as already
specified by [RFC8098]; the header field can already be handled
by guidance in [RFC8621].
3. When receiving an MDN, the MDN could be related to an existing
sent message. This is already covered by [RFC8621] in the
EmailSubmission object. A client might want to display detailed
information about a received MDN. This specification defines an
"MDN/parse" method to cover this case.
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Type signatures, examples, and property descriptions in this document
follow the conventions established in Section 1.1 of [RFC8620]. Data
types defined in the core specification are also used in this
document.
Servers MUST support all properties specified for the new data types
defined in this document.
1.2. Terminology
The same terminology is used in this document as in the core JMAP
specification.
Because keywords are case insensitive in IMAP but case sensitive in
JMAP, the "$mdnsent" keyword MUST always be used in lowercase.
1.3. Addition to the Capabilities Object
Capabilities are announced as part of the standard JMAP Session
resource; see [RFC8620], Section 2. This defines a new capability,
"urn:ietf:params:jmap:mdn".
The capability "urn:ietf:params:jmap:mdn" being present in the
"accountCapabilities" property of an account represents support for
the "MDN" data type, parsing MDNs via the "MDN/parse" method, and
creating and sending MDN messages via the "MDN/send" method. Servers
that include the capability in one or more "accountCapabilities"
properties MUST also include the property in the "capabilities"
property.
The value of this "urn:ietf:params:jmap:mdn" property is an empty
object both in the account's "accountCapabilities" property and in
the "capabilities" property.
2. MDN
An *MDN* object has the following properties:
* forEmailId: "Id|null"
The Email id of the received message to which this MDN is related.
This property MUST NOT be null for "MDN/send" but MAY be null in
the response from the "MDN/parse" method.
* subject: "String|null"
The subject used as "Subject" header field for this MDN.
* textBody: "String|null"
The human-readable part of the MDN, as plain text.
* includeOriginalMessage: "Boolean" (default: false)
If "true", the content of the original message will appear in the
third component of the multipart/report generated for the MDN.
See [RFC8098] for details and security considerations.
* reportingUA: "String|null"
The name of the Mail User Agent (MUA) creating this MDN. It is
used to build the MDN report part of the MDN. Note that a "null"
value may have better privacy properties.
* disposition: "Disposition"
The object containing the diverse MDN disposition options.
* mdnGateway: "String|null" (server-set)
The name of the gateway or Message Transfer Agent (MTA) that
translated a foreign (non-Internet) message disposition
notification into this MDN.
* originalRecipient: "String|null" (server-set)
The original recipient address as specified by the sender of the
message for which the MDN is being issued.
* finalRecipient: "String|null"
The recipient for which the MDN is being issued. If set, it
overrides the value that would be calculated by the server from
the Identity defined in the "MDN/send" method, unless explicitly
set by the client.
* originalMessageId: "String|null" (server-set)
The "Message-ID" header field [RFC5322] (not the JMAP id) of the
message for which the MDN is being issued.
* error: "String[]|null" (server-set)
Additional information in the form of text messages when the
"error" disposition modifier appears.
* extensionFields: "String[String]|null"
The object where keys are extension-field names, and values are
extension-field values (see [RFC8098], Section 3.3).
A *Disposition* object has the following properties:
* actionMode: "String"
This MUST be one of the following strings: "manual-action" /
"automatic-action"
* sendingMode: "String"
This MUST be one of the following strings: "mdn-sent-manually" /
"mdn-sent-automatically"
* type: "String"
This MUST be one of the following strings: "deleted" /
"dispatched" / "displayed" / "processed"
See [RFC8098] for the exact meaning of these different fields. These
fields are defined as case insensitive in [RFC8098] but are case
sensitive in this RFC and MUST be converted to lowercase by "MDN/
parse".
2.1. MDN/send
The "MDN/send" method sends a message in the style of [RFC5322] from
an MDN object. When calling this method, the "using" property of the
Request object MUST contain the capabilities
"urn:ietf:params:jmap:mdn" and "urn:ietf:params:jmap:mail"; the
latter because of the implicit call to "Email/set" and the use of
Identity objects, which is described below. The method takes the
following arguments:
* accountId: "Id"
The id of the account to use.
* identityId: "Id"
The id of the Identity to associate with these MDNs. The server
will use this identity to define the sender of the MDNs and to set
the "finalRecipient" field.
* send: "Id[MDN]"
A map of the creation id (client specified) to MDN objects.
* onSuccessUpdateEmail: "Id[PatchObject]|null"
A map of the id to an object containing properties to update on
the Email object referenced by the "MDN/send" if the sending
succeeds. This will always be a backward reference to the
creation id (see the example below in Section 3.1).
The response has the following arguments:
* accountId: "Id"
The id of the account used for the call.
* sent: "Id[MDN]|null"
A map of the creation id to an MDN containing any properties that
were not set by the client. This includes any properties that
were omitted by the client and thus set to a default by the
server. This argument is null if no MDN objects were successfully
sent.
* notSent: "Id[SetError]|null"
A map of the creation id to a SetError object for each record that
failed to be sent or null if all successful.
In this context, the existing SetError types defined in [RFC8620] and
[RFC8621] are interpreted as follows:
notFound: The reference "forEmailId" cannot be found or has no valid
"Disposition-Notification-To" header field.
forbidden: "MDN/send" would violate an Access Control List (ACL) or
other permissions policy.
forbiddenFrom: The user is not allowed to use the given
"finalRecipient" property.
overQuota: "MDN/send" would exceed a server-defined limit on the
number or total size of sent MDNs. It could include limitations
on sent messages.
tooLarge: "MDN/send" would result in an MDN that exceeds a server-
defined limit for the maximum size of an MDN or more generally, on
email message.
rateLimit: Too many MDNs or email messages have been created
recently, and a server-defined rate limit has been reached. It
may work if tried again later.
invalidProperties: The record given is invalid in some way.
The following is a new SetError:
mdnAlreadySent: The message has the "$mdnsent" keyword already set.
If the "accountId" or "identityId" given cannot be found, the method
call is rejected with an "invalidArguments" error.
The client MUST NOT issue an "MDN/send" request if the message has
the "$mdnsent" keyword set.
When sending the MDN, the server is in charge of generating the
"originalRecipient" and "originalMessageId" fields according to
[RFC8098]. "finalRecipient" will also generally be generated by the
server based on the provided identity, but if specified by the client
and allowed (see Section 5), the server will use the client-provided
value.
The client is expected to explicitly update each "Email" for which an
"MDN/send" has been invoked in order to set the "$mdnsent" keyword on
these messages. To ensure that, the server MUST reject an "MDN/send"
that does not result in setting the keyword "$mdnsent". Thus, the
server MUST check that the "onSuccessUpdateEmail" property of the
method is correctly set to update this keyword.
2.2. MDN/parse
This method allows a client to parse blobs as messages in the style
of [RFC5322] to get MDN objects. This can be used to parse and get
detailed information about blobs referenced in the "mdnBlobIds" of
the EmailSubmission object or any email message the client could
expect to be an MDN.
The "forEmailId" property can be null or missing if the
"originalMessageId" property is missing or does not refer to an
existing message or if the server cannot efficiently calculate the
related message (for example, if several messages get the same
"Message-ID" header field).
The "MDN/parse" method takes the following arguments:
* accountId: "Id"
The id of the account to use.
* blobIds: "Id[]"
The ids of the blobs to parse.
The response has the following arguments:
* accountId: "Id"
The id of the account used for the call.
* parsed: "Id[MDN]|null"
A map of the blob id to a parsed MDN representation for each
successfully parsed blob or null if none.
* notParsable: "Id[]|null"
A list of ids given that corresponds to blobs that could not be
parsed as MDNs or null if none.
* notFound: "Id[]|null"
A list of blob ids given that could not be found or null if none.
The following additional errors may be returned instead of the "MDN/
parse" response:
requestTooLarge: The number of ids requested by the client exceeds
the maximum number the server is willing to process in a single
method call.
invalidArguments: If the given "accountId" cannot be found, the MDN
parsing is rejected with an "invalidArguments" error.
3. Samples
3.1. Sending an MDN for a Received Email Message
A client can use the following request to send an MDN back to the
sender:
[[ "MDN/send", {
"accountId": "ue150411c",
"identityId": "I64588216",
"send": {
"k1546": {
"forEmailId": "Md45b47b4877521042cec0938",
"subject": "Read receipt for: World domination",
"textBody": "This receipt shows that the email has been
displayed on your recipient's computer. There is no
guarantee it has been read or understood.",
"reportingUA": "joes-pc.cs.example.com; Foomail 97.1",
"disposition": {
"actionMode": "manual-action",
"sendingMode": "mdn-sent-manually",
"type": "displayed"
},
"extension": {
"EXTENSION-EXAMPLE": "example.com"
}
}
},
"onSuccessUpdateEmail": {
"#k1546": {
"keywords/$mdnsent": true
}
}
}, "0" ]]
If the email id matches an existing email message without the
"$mdnsent" keyword, the server can answer:
[[ "MDN/send", {
"accountId": "ue150411c",
"sent": {
"k1546": {
"finalRecipient": "rfc822; john@example.com",
"originalMessageId": "<199509192301.23456@example.org>"
}
}
}, "0" ],
[ "Email/set", {
"accountId": "ue150411c",
"oldState": "23",
"newState": "42",
"updated": {
"Md45b47b4877521042cec0938": {}
}
}, "0" ]]
If the "$mdnsent" keyword has already been set, the server can answer
an error:
[[ "MDN/send", {
"accountId": "ue150411c",
"notSent": {
"k1546": {
"type": "mdnAlreadySent",
"description" : "$mdnsent keyword is already present"
}
}
}, "0" ]]
3.2. Asking for an MDN When Sending an Email Message
This is done with the "Email/set" "create" method of [RFC8621].
[[ "Email/set", {
"accountId": "ue150411c",
"create": {
"k2657": {
"mailboxIds": {
"2ea1ca41b38e": true
},
"keywords": {
"$seen": true,
"$draft": true
},
"from": [{
"name": "Joe Bloggs",
"email": "joe@example.com"
}],
"to": [{
"name": "John",
"email": "john@example.com"
}],
"header:Disposition-Notification-To:asText": "joe@example.com",
"subject": "World domination",
...
}
}
}, "0" ]]
Note the specified "Disposition-Notification-To" header field
indicating where to send the MDN (usually the sender of the message).
3.3. Parsing a Received MDN
The client issues a parse request:
[[ "MDN/parse", {
"accountId": "ue150411c",
"blobIds": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
}, "0" ]]
The server responds:
[[ "MDN/parse", {
"accountId": "ue150411c",
"parsed": {
"0f9f65ab-dc7b-4146-850f-6e4881093965": {
"forEmailId": "Md45b47b4877521042cec0938",
"subject": "Read receipt for: World domination",
"textBody": "This receipt shows that the email has been
displayed on your recipient's computer. There is no
guarantee it has been read or understood.",
"reportingUA": "joes-pc.cs.example.com; Foomail 97.1",
"disposition": {
"actionMode": "manual-action",
"sendingMode": "mdn-sent-manually",
"type": "displayed"
},
"finalRecipient": "rfc822; john@example.com",
"originalMessageId": "<199509192301.23456@example.org>"
}
}
}, "0" ]]
In the case that a blob id is not found, the server would respond:
[[ "MDN/parse", {
"accountId": "ue150411c",
"notFound": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
}, "0" ]]
If the blob id has been found but is not parsable, the server would
respond:
[[ "MDN/parse", {
"accountId": "ue150411c",
"notParsable": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
}, "0" ]]
4. IANA Considerations
4.1. JMAP Capability Registration for "mdn"
This section registers the "mdn" JMAP Capability in the "JMAP
Capabilities" registry as follows:
Capability Name: "urn:ietf:params:jmap:mdn"
Intended Use: common
Change Controller: IETF
Security and Privacy Considerations: This document, Section 5.
Reference: This document
4.2. JMAP Error Codes Registration for "mdnAlreadySent"
IANA has registered one new error code in the "JMAP Error Codes"
registry, as defined in [RFC8620].
JMAP Error Code: mdnAlreadySent
Intended Use: common
Change Controller: IETF
Description: The message has the "$mdnsent" keyword already set.
The client MUST NOT try again to send an MDN for this message.
Reference: This document, Section 2.1
5. Security Considerations
The same considerations regarding MDN (see [RFC8098] and [RFC3503])
apply to this document.
In order to reinforce trust regarding the relation between the user
sending an email message and the identity of this user, the server
SHOULD validate in conformance to the provided Identity that the user
is permitted to use the "finalRecipient" value and return a
"forbiddenFrom" error if not.
6. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3503] Melnikov, A., "Message Disposition Notification (MDN)
profile for Internet Message Access Protocol (IMAP)",
RFC 3503, DOI 10.17487/RFC3503, March 2003,
<https://www.rfc-editor.org/info/rfc3503>.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008,
<https://www.rfc-editor.org/info/rfc5322>.
[RFC8098] Hansen, T., Ed. and A. Melnikov, Ed., "Message Disposition
Notification", STD 85, RFC 8098, DOI 10.17487/RFC8098,
February 2017, <https://www.rfc-editor.org/info/rfc8098>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
2019, <https://www.rfc-editor.org/info/rfc8620>.
[RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621,
August 2019, <https://www.rfc-editor.org/info/rfc8621>.
Author's Address
Raphaël Ouazana (editor)
Linagora
100 Terrasse Boieldieu - Tour Franklin
92042 Paris - La Défense CEDEX
France
Email: rouazana@linagora.com
URI: https://www.linagora.com