| Internet-Draft | SML Action Requests | November 2026 |
| Baecker | Expires 22 May 2027 | [Page] |
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.¶
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.¶
Copyright (c) 2026 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.¶
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:¶
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.¶
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.¶
The action object is a JSON-LD node of type schema:Action (or a subtype) with the following properties.¶
| 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.¶
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}
}
¶
| 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.¶
An action request is a Structured Email message [I-D.ietf-sml-structured-email] containing:¶
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.¶
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.¶
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.¶
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.¶
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.¶
| 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.¶
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:¶
| 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:¶
| 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.¶
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.¶
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.¶