0036. One-click unsubscribe links carry a per-attempt random token stored as a hash
- Status: Accepted (decided by the maintainer)
- Date: 2026-11-13
Context
Section titled “Context”ADR 0024 requires RFC 8058 one-click unsubscribe on marketing mail: a List-Unsubscribe header with an HTTPS URL holding a token, List-Unsubscribe-Post: List-Unsubscribe=One-Click, a POST that unsubscribes, and a GET that never does. It leaves the token open. ADR 0034 sends mail as SESv2 Content.Simple with the List-Unsubscribe headers in Headers. Every workflow message is on the marketing stream today (WORKFLOW_STREAM in core/src/commands/send.ts).
Facts and constraints:
- RFC 8058: the receiver POSTs
List-Unsubscribe=One-Clickto the URL, with no cookies or authorization. The URL alone must identify the recipient, so it must be unguessable. A fragment is never sent, so the secret cannot be kept out of the path the way approval links do (ADR 0033). - Customer external IDs are often email addresses, so the URL cannot hold them (ADR 0032). Message IDs are hashes of the project, run, and step.
- The link is unauthenticated, so it is an exception to the Tenant model like approval links: the project comes from the path and must be confirmed before any write.
- SESv2 also offers
ListManagementOptions, which uses SES contact lists to generate and handle the unsubscribe link. That would keep unsubscribe state at the provider, outside the project store thatclaimSendrechecks (ADR 0007), and would not exist for self-hosters without SES (ADR 0003).
Options for the token:
| Option | For | Against |
|---|---|---|
| Random token per send attempt, stored as a SHA-256 hash on the message row (chosen) | no new secret to configure or rotate; the same pattern as approval link secrets; deleted with the message; nothing to decrypt | a store write per claim (already a write); a link works only while its message row exists |
| HMAC of project and message under a server key | no storage | a new secret per installation and its rotation; core would need a keyed HMAC port; a leaked key forges every link |
| One stored token per customer | one link per customer | its plaintext must be kept to reuse it in later mail, or each mail invalidates the earlier ones |
Decision
Section titled “Decision”- Each claim of a marketing message mints a token:
cl_unsub_and 256 random bits fromIdGenerator.secret(), base64url. Only its SHA-256 hash is stored, on the message row (unsubscribe_token_hash, project-store migration 7). The claim returns the plaintext once, to the delivery consumer, and it is never stored, queued, or returned by an API or MCP action. Transactional mail gets no token and no headers. - A new attempt replaces the hash. The store makes another attempt only after the previous one was definitely not sent (a retryable rejection or an unavailable provider); an
unknownoutcome is never resent. So the replaced token belongs to mail that was never delivered. - The link is
{APP_ORIGIN}/u/{projectId}/{messageId}/{token}: generated IDs and the token, no address or external ID. The delivery consumer builds it and addsList-Unsubscribe: <link>andList-Unsubscribe-Post: List-Unsubscribe=One-Clickto the email. - Headers travel through the
EmailProviderport asOutgoingEmail.headers, which an adapter passes to the provider unchanged: SES puts them inContent.Simple.Headers; the fake records them.ListManagementOptionsis not used. POST /u/:projectId/:messageId/:tokenis theendpointactioncustomers.unsubscribeByLink(authunsubscribe_link). It ignores the body. The project must exist in the control plane (scopeForUnsubscribeLink), so an unknown one never reaches a project store. TheunsubscribeByLinkcommand compares the token’s hash in constant time with the message’s stored hash before it reads the customer, then sets the customer’sunsubscribedAtif it is not set. It runs only from an endpoint action, likedecideSendApproval.- An unknown project, an unknown message, a message without a token, a wrong token, and a deleted customer all get the same
404 not_found, so the answer reveals nothing. A repeated POST answers 200 and writes nothing. GETof the link returns a static page with a form that posts to the link. It reads and writes nothing. It is sent withCache-Control: no-store,Referrer-Policy: no-referrer,X-Content-Type-Options: nosniff, and a CSP withdefault-src 'none',form-action 'self', andframe-ancestors 'none'.cl_unsub_is added toCREDENTIAL_PREFIXES, soredactForLogmasks tokens (ADR 0026, ADR 0032).
Consequences
Section titled “Consequences”- The unsubscribe is recorded on the customer, so the existing pre-send recheck in
claimSendskips the customer’s later mail asskipped:unsubscribed. - A link stays valid through every later state of its attempt, including
unknownandfailed:outcome_unknown: a mail whose outcome is unknown may have been delivered, so its link must keep working. Only a new attempt replaces the hash, and none follows anunknownoutcome. - A link stops working when its message row is deleted (customer deletion, or retention once it exists). Mail older than message retention cannot be unsubscribed from through its header.
- The token is in the URL path, so the platform’s request logs (Workers Logs, Logpush) can record it. Our own log lines mask it. What the platform records is the open item on platform logs, settled in B4’s deploy gate.
- RFC 8058 requires an HTTPS link.
APP_ORIGINacceptshttp:for local development, so a real provider must not be wired with anhttp:origin; B4 checks this. - A person who opens the link in a browser and presses the button gets the endpoint’s JSON answer. A styled confirmation page, and the unsubscribe link in the body, come with templates.
- That DKIM covers both headers is still to be confirmed in the manual SES smoke test before B4 (ADR 0024).