Skip to content

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

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-Click to 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 that claimSend rechecks (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
  • Each claim of a marketing message mints a token: cl_unsub_ and 256 random bits from IdGenerator.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 unknown outcome 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 adds List-Unsubscribe: <link> and List-Unsubscribe-Post: List-Unsubscribe=One-Click to the email.
  • Headers travel through the EmailProvider port as OutgoingEmail.headers, which an adapter passes to the provider unchanged: SES puts them in Content.Simple.Headers; the fake records them. ListManagementOptions is not used.
  • POST /u/:projectId/:messageId/:token is the endpoint action customers.unsubscribeByLink (auth unsubscribe_link). It ignores the body. The project must exist in the control plane (scopeForUnsubscribeLink), so an unknown one never reaches a project store. The unsubscribeByLink command compares the token’s hash in constant time with the message’s stored hash before it reads the customer, then sets the customer’s unsubscribedAt if it is not set. It runs only from an endpoint action, like decideSendApproval.
  • 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.
  • GET of the link returns a static page with a form that posts to the link. It reads and writes nothing. It is sent with Cache-Control: no-store, Referrer-Policy: no-referrer, X-Content-Type-Options: nosniff, and a CSP with default-src 'none', form-action 'self', and frame-ancestors 'none'.
  • cl_unsub_ is added to CREDENTIAL_PREFIXES, so redactForLog masks tokens (ADR 0026, ADR 0032).
  • The unsubscribe is recorded on the customer, so the existing pre-send recheck in claimSend skips the customer’s later mail as skipped:unsubscribed.
  • A link stays valid through every later state of its attempt, including unknown and failed: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 an unknown outcome.
  • 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_ORIGIN accepts http: for local development, so a real provider must not be wired with an http: 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).