Internet-Draft SML Action Requests November 2026
Baecker Expires 22 May 2027 [Page]
Workgroup:
Structured Email
Internet-Draft:
draft-backer-sml-action-requests-00
Published:
Intended Status:
Standards Track
Expires:
Author:
A. Bäcker
ab Inventio

Structured Action Requests and Shared Status in Email

Abstract

Much email asks the recipient to do something: approve, send, sign, pay, decide. Email has no interoperable way to say who owns such a request, when it is due, or whether it is done, so senders track requests by hand and requests are dropped. This document defines a Structured Email (SML) profile for action requests: a machine-readable action object, carried as JSON-LD using the schema.org Action vocabulary and optionally mirrored as an iCalendar VTODO, plus status-update messages that supersede earlier ones, so that every participant's mail client in every administrative domain can show one current status. It works with no shared server between organizations, and it degrades to readable text in clients that do not implement it.

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 22 May 2027.

▲

Table of Contents

1. Introduction

Closed platforms (project trackers, CRMs, workplace suites) track tasks with owners, due dates and status, but only among users of the same platform. Email crosses organizational boundaries but carries no task semantics. iCalendar VTODO over iMIP [RFC5546][RFC6047] can exchange tasks by email but is rarely used for this, has no follow-up semantics, and is not visible in mail views. The SML core specification [I-D.ietf-sml-structured-email] defines how to embed JSON-LD in email and how one message supersedes another, and leaves structured replies to future work (its Section 5.2). This document is such a profile for the most common structured reply: a status change on a requested action.

Goals:

  1. A sender designates the owner(s), outcome and due time of a request in a way any compliant client can display and track.
  2. Status (acknowledged, in progress, blocked, delegated, completed, declined, cancelled) travels back by email, structured or as plain text, and every participant converges on the latest status.
  3. Clients and automated agents can follow up politely and stop when the action is done, within limits the recipient can see.
  4. Non-compliant clients show the same information as text.

Non-goals: defining how an agent decides when to follow up, or how free-text replies are interpreted. Those are implementation choices; this document defines only the data and the message flow they act on.

2. Conventions and Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119][RFC8174] when, and only when, they appear in all capitals.

3. The Action Object

The action object is a JSON-LD node of type schema:Action (or a subtype) with the following properties.

Table 1
Property Req. Meaning
identifier MUST Globally unique action id, a "urn:uuid:" URN or a URI in the requester's domain. Never reused.
sml:version MUST Integer starting at 1, incremented on every change.
participant MUST The requester (schema:Person with email). Other participants MAY be listed.
agent MUST One or more owners (schema:Person with email), each with a role: responsible, contributor or approver, and a per-owner status.
description MUST The requested outcome in plain language.
endTime SHOULD Due time, RFC 3339 with offset.
sml:priority MAY Integer 0-9 with the meaning of the iCalendar PRIORITY property [RFC5545]: 1 is highest, 9 lowest, 0 undefined. See Section 3.1.
actionStatus MUST schema.org status (see Section 4) for generic consumers.
sml:status MUST Fine-grained status from Section 4.
sml:statusReason MAY Text, for blocked, declined or delegated.
sml:blockingParty MAY Person or text, for blocked.
sml:evidence MAY URL or cid: reference to the completion evidence (e.g., an attachment).
sml:followUpPolicy MAY Section 6.
sml:history MAY Ordered list of prior transitions: {status, time, actor, basis}. basis is one of "structured", "inferred" or "observed".

The "sml:" prefix is a placeholder for the SML Email Vocabulary namespace, still TBD in the core specification.

3.1. Priority and Due Time

Priority and due time say different things. endTime says how urgent an action is. sml:priority says how important the requester considers it, relative to the requester's other open requests. A requester can therefore mark a request with a distant due time as more important than one due tomorrow. Clients MAY use priority to order or highlight requests. Because each requester sets priorities on their own scale, clients SHOULD NOT present priorities from different requesters as directly comparable. This document does not define how agents use priority.

Example (abbreviated):

{
  "@context": "https://schema.org",
  "@type": "Action",
  "identifier": "urn:uuid:7c1e4f0a-2b8d-4c47-9f2e-1a2b3c4d5e6f",
  "sml:version": 1,
  "participant": {"@type": "Person",
                  "email": "requester@example.com"},
  "agent": [{"@type": "Person", "email": "owner@example.org",
             "sml:role": "responsible", "sml:status": "requested"}],
  "description": "Send the signed NDA",
  "endTime": "2026-12-03T17:00:00-08:00",
  "sml:priority": 2,
  "actionStatus": "PotentialActionStatus",
  "sml:status": "requested",
  "sml:followUpPolicy": {"initialDelay": "P2D", "cadence": "P2D",
    "maxFollowUps": 3, "quietPeriod": "P1D",
    "businessHoursOnly": true}
}

4. Status Values and Transitions

Table 2
sml:status schema:actionStatus Terminal Who may set it
requested PotentialActionStatus no requester
acknowledged ActiveActionStatus no owner
in-progress ActiveActionStatus no owner
blocked ActiveActionStatus no owner
delegated ActiveActionStatus no owner (names the new owner)
completed CompletedActionStatus yes owner; requester may confirm
declined FailedActionStatus yes owner
cancelled FailedActionStatus yes requester

Permitted transitions: from requested to any status; among the non-terminal statuses freely; from any non-terminal status to a terminal status. A terminal status MAY be reopened only by the requester (back to requested, with a new version). Receivers MUST ignore transitions set by a party not allowed to set them (Section 8).

With several owners, each owner has a per-owner status and the aggregate status is: completed when all responsible owners are completed; declined or cancelled per the requester's update; otherwise the least advanced non-terminal status.

5. Message Structure

5.1. Action request

An action request is a Structured Email message [I-D.ietf-sml-structured-email] containing:

  1. A text/plain part and, OPTIONALLY, a text/html part. Both MUST include a human-readable status block, for example: "Action requested of Maria Lopez · Due 3 Dec 17:00 PT · Status: Requested". A non-compliant client then still shows the request.
  2. An application/ld+json part carrying the action object, with Content-Purpose: Machine-readable as in the core specification.
  3. OPTIONALLY, a text/calendar part with METHOD:REQUEST carrying an equivalent VTODO (Section 7).

New header field (Section 10):

Action-Id: <urn:uuid:7c1e4f0a-2b8d-4c47-9f2e-1a2b3c4d5e6f>

Action-Id lets clients and agents correlate messages without parsing bodies. It MUST equal the action object's identifier.

5.2. Status update

A status update is a reply (In-Reply-To and References set as usual) that carries the full current action object with an incremented version, the same Action-Id, and a Supersedes header [RFC4021] naming the message whose action object it replaces. A compliant client MUST display only the highest-version action object per Action-Id and SHOULD render it as a single live item, not a new one. The text parts MUST restate the current status block.

Either an owner's client (or agent) or the requester's client (or agent) may send a status update. When the owner replies in free text only, the requester's agent MAY derive a status from the text and send a status update to all participants. Such an update MUST record basis "inferred" in sml:history, so that the owner can see and correct it. A future version may define simple reply words (for example DONE, BLOCKED, NEW DATE) that clients can recognize without natural-language processing, so that status can be updated without an automated agent.

5.3. State without a shared server

The current state of an action is the highest-version action object received for its Action-Id. Any participant can rebuild it from their own mailbox, so no server shared between organizations is needed.

5.4. Revision before acknowledgement

Until an owner's status is anything other than requested, the requester MAY revise the action (description, due time, owners) by sending a superseding action request with a higher version. Compliant clients replace the displayed request. After acknowledgement, changes to description or due time MUST be sent as an amendment: an action object with sml:amendment set to the proposed changes and sml:amendmentStatus "pending" until the owner accepts or rejects it. This protects owners from unilateral changes after they commit.

6. Follow-up Policy

sml:followUpPolicy states how the requester's client or agent will remind owners. It is visible to the owner, so recipients know what to expect.

Table 3
Field Meaning
initialDelay ISO 8601 duration before the first reminder.
cadence Duration between reminders, or "relative" with an offsets list relative to endTime (e.g., ["-P3D","-P1D","PT0S"]).
maxFollowUps Upper bound on reminders. Agents MUST NOT exceed it.
quietPeriod No reminder within this duration after any status change by an owner.
businessHoursOnly If true, reminders only in the owner's business hours when known.
escalation {after: n, contact: email}. The contact is copied after n unanswered reminders. MUST be disclosed in the request.
channels Permitted reminder channels. Default ["email"].

Agents MUST stop reminding when the action reaches a terminal status, and SHOULD defer reminders while an owner's structured vacation notice [I-D.ietf-sml-structured-vacation-notices] is in effect. How an agent chooses timing and wording within these limits is out of scope.

7. iCalendar and JSCalendar Mapping

For calendar and task servers that implement iTIP/iMIP [RFC5546][RFC6047], the action MAY also be sent as a VTODO [RFC5545] with METHOD:REQUEST, using the task extensions of [RFC10051] where noted. Field mapping:

Table 4
Action object VTODO
identifier UID
sml:version SEQUENCE
participant (requester) ORGANIZER
agent (owners) ATTENDEE; ROLE=REQ-PARTICIPANT for responsible owners
description SUMMARY
endTime DUE
sml:priority PRIORITY
sml:statusReason COMMENT; REASON [RFC10051] where a registered reason URI applies

Status mapping:

Table 5
sml:status VTODO STATUS Owner's PARTSTAT Notes
requested NEEDS-ACTION NEEDS-ACTION
acknowledged NEEDS-ACTION ACCEPTED
in-progress IN-PROCESS IN-PROCESS PERCENT-COMPLETE MAY be set
blocked IN-PROCESS IN-PROCESS SUBSTATE:SUSPENDED [RFC10051]
delegated unchanged DELEGATED DELEGATED-TO names the new owner
completed COMPLETED COMPLETED
declined CANCELLED DECLINED
cancelled CANCELLED unchanged set by the requester

Status changes in this profile come from participants' messages, so senders SHOULD omit TASK-MODE [RFC10051] (its default, CLIENT, applies). The follow-up policy (Section 6) and amendments (Section 5.4) have no VTODO equivalent; they are omitted from the VTODO or carried in X- properties to be registered later. An iTIP REPLY from the owner's server MUST be treated as a structured status update.

For JMAP servers the same mapping applies to the JSCalendar Task object [RFC8984][I-D.ietf-jmap-tasks], whose priority property uses the same 0-9 scale. A JMAP server can therefore store a received action request as an ordinary task in the owner's task list.

8. Security Considerations

9. Privacy Considerations

The action object reveals who owes what to whom and when. Forwarding a status update forwards this. Clients SHOULD warn before forwarding an action object outside the participant list.

10. IANA Considerations

11. Implementation Status

A private prototype exists (ab Inventio, 2026). It implements the iCalendar VTODO / JSCalendar Task mapping of Section 7 and the status transitions of Section 4. It does not yet implement the JSON-LD action object of Section 3 or the superseding status updates of Section 5.2. The author is seeking server and client implementers for the full profile.

12. References

12.1. Normative References

[RFC2119]
"Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174]
"Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", RFC 8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC4021]
"Registration of Mail and MIME Header Fields", RFC 4021, , <https://www.rfc-editor.org/info/rfc4021>.
[RFC3864]
"Registration Procedures for Message Header Fields", RFC 3864, , <https://www.rfc-editor.org/info/rfc3864>.
[RFC5545]
"Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, , <https://www.rfc-editor.org/info/rfc5545>.
[RFC5546]
"iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, , <https://www.rfc-editor.org/info/rfc5546>.
[RFC6047]
"iCalendar Message-Based Interoperability Protocol (iMIP)", RFC 6047, , <https://www.rfc-editor.org/info/rfc6047>.
[RFC8984]
"JSCalendar: A JSON Representation of Calendar Data", RFC 8984, , <https://www.rfc-editor.org/info/rfc8984>.
[I-D.ietf-sml-structured-email]
"Structured Email", Work in Progress, Internet-Draft, draft-ietf-sml-structured-email, <https://datatracker.ietf.org/doc/draft-ietf-sml-structured-email/>.

12.2. Informative References

[RFC10051]
"Task Extensions to iCalendar", RFC 10051, , <https://www.rfc-editor.org/info/rfc10051>.
[I-D.ietf-sml-structured-vacation-notices]
"Structured vacation notices", Work in Progress, Internet-Draft, draft-ietf-sml-structured-vacation-notices, <https://datatracker.ietf.org/doc/draft-ietf-sml-structured-vacation-notices/>.
[I-D.ietf-sml-trust]
"Structured Email: Trust and Security Considerations", Work in Progress, Internet-Draft, draft-ietf-sml-trust, <https://datatracker.ietf.org/doc/draft-ietf-sml-trust/>.
[I-D.ietf-jmap-tasks]
"JMAP for Tasks", Work in Progress, Internet-Draft, draft-ietf-jmap-tasks, <https://datatracker.ietf.org/doc/draft-ietf-jmap-tasks/>.

Author's Address

Alex Bäcker
ab Inventio