Skip to content

0020. Click tracking with self-contained signed tokens and a separate tracker

  • Status: Accepted
  • Date: 2026-11-08

Click tracking is in the MVP (ADR 0015). A sent link must keep working for years, through API deploys and storage outages, and must not become an open redirect.

  • The send step rewrites links into /c/<token> URLs. The token is base64url(payload).signature, with payload {kid, project_id, message_id, link_index, url}, signed with HMAC-SHA256 under a rotatable key.
  • The tracker Worker (or the tracker entrypoint in containers) verifies the signature, re-checks the URL rules, and replies 302 to the URL in the token. It never takes a destination from the request and needs no storage to redirect.
  • Recording happens after the redirect: the click goes to a tracking queue, and the project store applies scanner and bot heuristics and unique-human aggregates. Bot and scanner clicks are recorded but flagged and excluded from metrics.
  • The tracker is deployed separately from the API, so an API deploy cannot break sent links.
  • Tracked links never use the app domain (dashboard and API), so tracked links in reported mail cannot get the app domain blocklisted, and the tracker never shares the app’s cookies. The MVP uses one shared tracking domain, separate from the app domain. An optional per-workspace custom tracking subdomain (Cloudflare for SaaS custom hostnames) and send-time URL screening through the abuse-screening extension point come later.
  • Failure to record a click never breaks the redirect.
  • Key rotation keeps old keys for verification for as long as sent links should work.

Amendment (2026-11-19, pending ADR 0046, Proposed): the tracker also serves the open pixel at /o/<token>. Tokens carry a type (t: "c" or "o") and each route accepts only its own. Requests are classified by one core function (machine, proxied, direct, with a reason and a classifier version), and only the result is enqueued, with a tracker-minted event ID, never the IP address or user agent; the store adds timing and burst heuristics and deduplicates by event ID. Projects can turn click tracking off, and transactional mail and customers with trackingOptOut are never tracked.