Internet DRAFT - draft-happel-structured-email
draft-happel-structured-email
Network Working Group H.-J. Happel
Internet-Draft audriga GmbH
Intended status: Informational 23 October 2023
Expires: 25 April 2024
Structured Email
draft-happel-structured-email-00
Abstract
This document specifies how a machine-readable version of the content
of email messages can be added to those messages.
Status of This Memo
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 Notice
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.
Happel Expires 25 April 2024 [Page 1]
Internet-Draft Structured Email October 2023
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Representing structured data . . . . . . . . . . . . . . . . 3
3.1. Vocabularies . . . . . . . . . . . . . . . . . . . . . . 3
4. Structured data in email messages . . . . . . . . . . . . . . 4
4.1. Placement . . . . . . . . . . . . . . . . . . . . . . . . 4
4.1.1. Full representation . . . . . . . . . . . . . . . . . 4
4.1.2. Partial representation . . . . . . . . . . . . . . . 5
4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 5
4.2.1. Using identifiers in structured data . . . . . . . . 5
4.2.2. Using structured data identifiers in text/html . . . 5
5. Structured data across email messages . . . . . . . . . . . . 6
5.1. Forwarding . . . . . . . . . . . . . . . . . . . . . . . 6
5.2. Replies . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.3. Error replies . . . . . . . . . . . . . . . . . . . . . . 6
5.4. Updates . . . . . . . . . . . . . . . . . . . . . . . . . 6
6. Header fields and message flags . . . . . . . . . . . . . . . 7
6.1. Presence of structured data . . . . . . . . . . . . . . . 7
6.2. Action processing . . . . . . . . . . . . . . . . . . . . 8
7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.1. Partial representation . . . . . . . . . . . . . . . . . 8
8. Security and trust . . . . . . . . . . . . . . . . . . . . . 8
9. Implementation status . . . . . . . . . . . . . . . . . . . . 8
9.1. Structured Email plugin for Roundcube Webmail . . . . . . 9
10. Security considerations . . . . . . . . . . . . . . . . . . . 9
11. Privacy considerations . . . . . . . . . . . . . . . . . . . 9
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
13. Informative References . . . . . . . . . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction
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.
Happel Expires 25 April 2024 [Page 2]
Internet-Draft Structured Email October 2023
The goal of this specification is to provide a clear and
comprehensive specification for this practice and to provide ground
for potential future extensions.
2. Conventions Used in This Document
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.
3. Representing structured data
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
3.1. Vocabularies
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.
Happel Expires 25 April 2024 [Page 3]
Internet-Draft Structured Email October 2023
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
4. Structured data in email messages
This section discusses the placement of structured data within email
messages and identifiers for referencing between structured data and
other parts of a message.
4.1. Placement
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
4.1.1. Full representation
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.
Happel Expires 25 April 2024 [Page 4]
Internet-Draft Structured Email October 2023
4.1.2. Partial representation
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).
4.2. Identifiers
[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.
4.2.1. Using identifiers in structured data
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
4.2.2. Using structured data identifiers in text/html
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.
Happel Expires 25 April 2024 [Page 5]
Internet-Draft Structured Email October 2023
For discussion, see also:
https://github.com/hhappel/draft-happel-structured-email/issues/5
5. Structured data across email messages
5.1. Forwarding
For discussion, see also:
https://github.com/hhappel/draft-happel-structured-email/issues/6
5.2. Replies
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
5.3. Error replies
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
5.4. Updates
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.
Happel Expires 25 April 2024 [Page 6]
Internet-Draft Structured Email October 2023
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
6. Header fields and message flags
This sections presents header fields and IMAP flags which are
supposed to support MUAs in dealing with structured email.
6.1. Presence of structured data
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.
Happel Expires 25 April 2024 [Page 7]
Internet-Draft Structured Email October 2023
6.2. Action processing
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.
7. Examples
7.1. Partial representation
Pleacement of JSON-LD markup in a "text/html" body part:
<html>
<body>
<script language="ld+json">
...
</script>
</body>
</html>
8. Security and trust
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.
9. Implementation status
< 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
Happel Expires 25 April 2024 [Page 8]
Internet-Draft Structured Email October 2023
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".
9.1. Structured Email plugin for Roundcube Webmail
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]).
10. Security considerations
See section "security and trust".
11. Privacy considerations
See section "security and trust".
12. IANA Considerations
This document has no IANA actions at this time.
(TBD IMAP flags)
13. Informative References
[HTMLData] WHATWG, "HTML Living Standard: Embedding custom non-
visible data with the data-* attributes",
<https://html.spec.whatwg.org/multipage/dom.html#attr-
data-*>.
[HasAttachment]
IETF imapext WG mailing list, "Registering $hasAttachment
& $hasNoAttachment",
<https://mailarchive.ietf.org/arch/msg/imapext/
MVE5eNHOaNIVGUvN1RKtBL8b278/>.
[JSONLD] W3C JSON-LD Working Group, "JSON-LD 1.1",
<https://www.w3.org/TR/json-ld/>.
Happel Expires 25 April 2024 [Page 9]
Internet-Draft Structured Email October 2023
[MachineReadable]
NIST, "NIST IR 7511 Rev. 4",
<https://csrc.nist.gov/glossary/term/Machine_Readable>.
[PotentialAction]
W3C Schema.org Community Group, "Schema.org:
potentialAction", <https://schema.org/potentialAction>.
[RDF] W3C RDF Working Group), "RDF 1.1 Concepts and Abstract
Syntax", <https://www.w3.org/TR/rdf11-concepts/>.
[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>.
[RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource
Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998,
<https://www.rfc-editor.org/info/rfc2392>.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987,
January 2005, <https://www.rfc-editor.org/info/rfc3987>.
[RFC4021] Klyne, G. and J. Palme, "Registration of Mail and MIME
Header Fields", RFC 4021, DOI 10.17487/RFC4021, March
2005, <https://www.rfc-editor.org/info/rfc4021>.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008,
<https://www.rfc-editor.org/info/rfc5322>.
[RFC5598] Crocker, D., "Internet Mail Architecture", RFC 5598,
DOI 10.17487/RFC5598, July 2009,
<https://www.rfc-editor.org/info/rfc5598>.
[RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", BCP 205,
RFC 7942, DOI 10.17487/RFC7942, July 2016,
<https://www.rfc-editor.org/info/rfc7942>.
[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>.
Happel Expires 25 April 2024 [Page 10]
Internet-Draft Structured Email October 2023
[RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
Access Protocol (IMAP) - Version 4rev2", RFC 9051,
DOI 10.17487/RFC9051, August 2021,
<https://www.rfc-editor.org/info/rfc9051>.
[SchemaOrg]
W3C Schema.org Community Group, "Schema.org",
<https://schema.org/>.
[SchemaOrgEmail]
Structured Email, "Schema.org for email",
<https://structured.email/content/related_work/frameworks/
schema_org_for_email.html>.
[WDCStats] Web Data Commons Project, "Web Data Commons - Microdata,
RDFa, JSON-LD, and Microformat Data Sets",
<http://webdatacommons.org/structureddata/#toc3>.
Author's Address
Hans-Joerg Happel
audriga GmbH
Email: happel@audriga.com
URI: https://www.audriga.com
Happel Expires 25 April 2024 [Page 11]
