| Internet-Draft | Structured Email | October 2023 |
| Happel | Expires 25 April 2024 | [Page] |
This document specifies how a machine-readable version of the content of email messages can be added to those messages.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 25 April 2024.¶
Copyright (c) 2023 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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Information on websites and in email messages mostly addresses human readers. However, various attempts have been made to make such information - fully or in part - machine-readable, so that tools can assist users in dealing with that information more efficiently.¶
One widespread approach is the usage of [SchemaOrg] vocabulary embededd in websites, which is e.g., used by search engines to provide web search result snippets in a more advanced form (including displaying ratings, opening hours, or contact information).¶
Similarly, some email providers and open source tools extract and use Schema.org data which they find embedded in email messages. However their implementations differ in many details.¶
The goal of this specification is to provide a clear and comprehensive specification for this practice and to provide ground for potential future extensions.¶
The terms "message" and "email message" refer to "electronic mail messages" or "emails" as specified in [RFC5322]. The term "Message User Agent" (MUA) denotes an email client application as per [RFC5598].¶
The terms "machine-readable data" and "structured data" are used in contrast to "human-readable" messages and denote information expressed "in a structured format (..) which can be consumed by another program using consistent processing logic" [MachineReadable].¶
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.¶
In order to exchange structured data, one needs to chose a formal language and a serialization format.¶
One such language is the Resource Description Framework ([RDF]). It is already used for annotating websites and emails, as it is underlying [SchemaOrg]. Among the various serializations for RDF, JSON-LD ([JSONLD]) has become the most commonly used serialization used on websites [WDCStats].¶
Hence, structured data in email messages SHOULD be expressed in the JSON-LD serialization of RDF.¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/1¶
Using RDF/JSON-LD, users are free to express any kind of information in structured data. For reuse and reference however, it is common to agree upon certain core concepts/entities and properties for a certain domain. Those are typically collected and shared in so-called vocabularies.¶
One such vocabulary, that has been intially designed for usage on websites, is the [SchemaOrg] vocabulary. A small part of this vocabulary is used by email providers already.¶
Users that want to add structured data into email message SHOULD use concepts from [SchemaOrg], if they fit their use case. Users MAY however use any valid JSON-LD.¶
Similar to the case of arbitrary MIME body parts, which might not be supported by every MUA, interoperability can still be achieved, either by extending a MUA, or by handling data outside of the MUA.¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/2¶
This section discusses the placement of structured data within email messages and identifiers for referencing between structured data and other parts of a message.¶
This document targets structured data describing the content of an email message itself. Since users may add arbitrary structured data (e.g., MIME body parts of type "application/ld+json") to an email message, we need to define which kinds of structured data are supposed to be representative of the email message content.¶
For this, we distinguish the two cases of full represetation and partial representation.¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/3¶
If structured data is intended by the sender to fully describe the human readable content of an email message, it MUST be added as a multipart/alternative entity with the content type "application/ld+json".¶
The email message SHOULD in this case also contain a "text/plain" and a "text/html" version of the content.¶
If structured data is intended to describe only a subset of the human-readable content, it must be enclosed in a "script" HTML tag within the HTML "body" tag of the text/html body part of the email message (see example at the end).¶
[RFC2392] defines the "cid:" and "mid:" URI schemes to allow for cross-referecing between MIME parts and messages. This section discussed cross-referencing between structured data and MIME parts.¶
Most nodes and properties in JSON-LD are identified using IRIs [RFC3987]. Since any [RFC2392] reference forms a valid IRI, those references can be used in JSON-LD.¶
There are two main cases for which "cid:"-identifiers SHOULD be used in structured data.¶
First, if structured data references binary content such as images or other files which already exist as MIME body parts within the same message.¶
If a "cid:" value is used in a JSON-LD "@id" property, the corresponding JSON-LD node can be considered to describe the MIME body part identified by that "cid:". This MAY be used to denote that certain structured data is explictily describing that MIME body part. This MUST NOT be used for the main text/plain or text/html body parts, though.¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/4¶
For the case of "partial representation", it might be helpful if email user agents are able to understand which parts of human readable text refer to certian structured data.¶
For this purpose, the sender may add a HTML "data-id" property ([HTMLData]) to any HTML entity in the text/html body, which references the "@id" property of a JSON-LD node in the structured data.¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/5¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/6¶
In order to allow responses to structured email messages, the [SchemaOrg] vocabulary specifies a property called "potentialAction" ([PotentialAction]).¶
If the "target" property of an action points to a "mailto:" URI, the email user agent SHOULD reply with a structured email if the user triggers the action.¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/7¶
An original sender may not assume that a structured email has been processed by a recipient. However, if a recipient replies to a structured email, the original sender MAY want to signal an issue with the response, such as if a contradicting response has already been received.¶
In this case, a "full representation"-style error message MAY be returnend to the sender of the erroneous response. Example: TBD¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/8¶
In human-readable messages, human language can be used to update or recall information that was conveyed in prior messages. Accordingly, there needs to be a machine-readable mechanism that allows to express the update or recall of information of structured data.¶
Structured data SHOULD be updated, if a later email message with a SUPERSEDES header field ([RFC4021]; "superseding messing") referencing the message id of the original email message is processed. In this case, structured data of the original message should be fully revoked and replaced by the structured data of the superseding message (which might be empty).¶
Structured data in a superseding message MUST be ignored if: * Structured data from the original message is not or cannot be revoked * In particular, if the original message has already been replied to by the recipient¶
For discussion, see also: https://github.com/hhappel/draft-happel-structured-email/issues/9¶
This sections presents header fields and IMAP flags which are supposed to support MUAs in dealing with structured email.¶
In some use cases, MUAs might benefit from information about message details without having to evaluate the full message body.¶
For example, the "$hasAttachment" IMAP flag ([HasAttachment]) was proposed to signal the existence of MIME attachments in a message.¶
The following procedures should apply to structured email.¶
A sending MUA (aMUA) SHOULD add a header field "Structured data" if a message contains structured data. The value for this field MUST include one of the following values (case-insensitive): * "Full" for full representation * "Partial" for partial representation¶
The "Structured data" fields SHOULD additionally include (case-insensitive, comma-separated) the value "Action", if a message contains a "potentialAction" a MUA might want to investigate¶
Similarly, the IMAP flag "hasStructuredData" and "hasStructuredDataAction" MAY be used if an inbound message is found to contain structured data, but neither of the aforementioned header fields.¶
A structured email can contain "potentialActions". MUAs need to ensure that such actions are not triggered multiple times - either within the same MUA or across multiple concurrent MUAs.¶
For this purpose, the "\Answered" flag ([RFC9051]) is not appropriate, as it has an established meaning and implementations for regular, manually authored responses.¶
Therefore, a MUA MUST set a flag "$structuredDataActionSent" if a potentilAction has been responsed to - either by the user or some other mechanism on behalf of the user.¶
Pleacement of JSON-LD markup in a "text/html" body part:¶
<html> <body> <script language="ld+json"> ... </script> </body> </html>¶
Email user agents that want to support structured email should follow guidance to ensure trust and security standards. These will be elaborated in a separate specification.¶
< RFC Editor: before publication please remove this section and the reference to [RFC7942] >¶
This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in [RFC7942]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist.¶
According to [RFC7942], "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".¶
An open source plugin for the Roundcube Webmail software is developed to serve as a reference implementation for this specification.¶
Beyond that, some ISPs and open source tools provide implementation partly compliant with this specficiation ([SchemaOrgEmail]).¶
See section "security and trust".¶
See section "security and trust".¶
This document has no IANA actions at this time.¶
(TBD IMAP flags)¶