0046. Open tracking with a pixel, and machine-open classification by one core function
- Status: Proposed. The default of open tracking (on for marketing mail, never for transactional mail) is the maintainer’s decision of 2026-11-19, Accepted and not reopened.
- Date: 2026-11-19
- Amends: ADR 0015 (open tracking moves from deferred into the first release), ADR 0020 (the tracker serves the pixel, classifies requests with a core function, and enqueues no IP address or user agent), ADR 0034 (SES Open and Click events stay unpublished), ADR 0023 (deletion also removes engagement records)
Context
Section titled “Context”The maintainer decided on 2026-11-19 to track opens, despite the reasons ADR 0015 and ADR 0020 deferred them, and decided that open tracking is on by default for marketing mail, per project, and never on for transactional mail.
Facts:
- Click tracking is decided (ADR 0020): signed self-contained
/c/<token>links on a separate tracking domain, a separately deployedtracker, clicks recorded after the redirect through thetrackingqueue, bot and scanner clicks flagged and excluded. - An open is detected by an invisible image in the HTML body. Its known failures (public documentation and common industry practice, checked 2026-11-19):
- Apple Mail Privacy Protection (MPP) preloads remote images through Apple’s proxy for most messages delivered to Apple Mail with MPP on, whether or not the person reads them; when it does depends on the device’s state. Apple publishes no list of these proxies; they are recognised heuristically, by Apple-owned networks and the proxy’s generic user agent.
- Apple does publish the egress ranges of iCloud Private Relay, which carries real people’s traffic from Safari; it must not be mistaken for MPP.
- Gmail and Yahoo fetch images through their proxies when the person opens the message and cache them: the first open is real, repeat opens are invisible.
- Security scanners fetch images and follow links on delivery, often from datacenter networks, often several links within a second. Many people also browse from datacenter networks (VPNs, corporate egress), so the network alone does not identify a scanner.
- Clients that block remote images never report an open.
- Queues carry IDs and versioned payloads only, never personal data (Data placement). An IP address and a user agent are personal data.
- Click tokens today carry no type field.
Decision
Section titled “Decision”The pixel
Section titled “The pixel”- A tracked HTML message ends with a 1×1 transparent GIF,
https://{tracking domain}/o/<token>. The token has the click token’s format and keys with payload{kid, t: "o", project_id, message_id}. Click tokens gaint: "c". - Each route accepts only its own type:
/oonlyt: "o",/conlyt: "c"(or a token withoutt, which only links sent before this change carry). A click token used as a pixel, or the reverse, is not recorded. - The tracker always answers
/owith the GIF,Cache-Control: no-store, private, whether or not the token verifies, so the answer reveals nothing; it never redirects.HEADrequests on either route are answered and not recorded. - Text-only messages have no pixel and record no opens.
Classification
Section titled “Classification”- One pure function in core,
classifyEngagement(signals, lists) → { class, reason }, used by each target’s tracker (the Worker on Cloudflare, thetrackerservice in containers). The network signals come from a second pure core function,deriveNetworkSignals(ip, asn, lists) → { datacenter, appleOwned, privateRelay }, so both targets share one implementation. Each tracker passes it the request’s IP address and ASN (fromrequest.cfon Workers, from its own lookup in containers), then passesclassifyEngagementthe method, user agent, those network signals, and whether the link is the decoy. Neither function logs, stores, or returns the IP address; it is used in memory for the request only (ADR 0032), andclassifyEngagementnever sees it. - Classes and reasons:
machine:apple_mpp(an Apple-owned network that is not a Private Relay egress, with the MPP proxy’s user agent);scanner(a user agent on the scanner list, or a datacenter network together with another scanner signal, never the network alone);decoy(a click on the hidden decoy link);prefetchandburst(set by the store, below).proxied: an image proxy that fetches on a real open (gmail_proxy,yahoo_proxy, and the others on the list). A likely human open.direct: anything else, Private Relay egress included.
- Lists (Apple-owned networks, Private Relay egress ranges, proxy and scanner user agents and networks) are data files in the repository, versioned together as
classifier_versionand updated by pull request; Private Relay ranges are regenerated from Apple’s published list by a script. Every engagement record keeps theclassifier_versionthat classified it. - The decoy link. A project setting,
tracking.decoyLink, off by default. When it is on and click tracking is on, the renderer appends one link hidden from people (display:none, no text) whose token carriesdecoy: true. Hidden links are a content pattern some spam filters penalise, so it can cost deliverability; that is why it is off unless a project chooses it. Clicks on it aremachine:decoy, and clicks on the same message recorded after the decoy click and withinENGAGEMENT_BURST_WINDOWaremachine:burst. Clicks recorded before it keep their class. - At the store, when it applies a record, with the facts it holds then (there is no later reclassification):
prefetch: the open or click is earlier thanENGAGEMENT_PREFETCH_WINDOW(configuration, seconds) after the message’saccepted_at(our provider response time, always known before mail can be read) or, if already recorded, the provider’s delivery timestamp from the Delivery event; or the message is not yetaccepted.burst: a click on a different link of the message withinENGAGEMENT_BURST_WINDOWafter an earlier recorded click, or after a decoy click as above. The earlier click keeps its class; nothing is reclassified retroactively.bounced: any open or click on a message whose delivery status is already bounced ismachine.- An open recorded before a later bounce keeps its class; that bounces arrive after a real open is rare, and reports count it as recorded.
- Bias. The classifier is imperfect and changes with
classifier_version. Every A/B arm (ADR 0048) shares the same bias, so a comparison between arms is fairer than any absolute open rate.
Recording
Section titled “Recording”- The tracker mints an engagement event ID (
IdGenerator) per recorded request and enqueues{event_id, project_id, message_id, kind, link_index?, at, class, reason, classifier_version}, with no IP address, user agent, or URL. - Edge deduplication. The tracker drops a request for the same
(message, kind, class)withinTRACKER_DEDUPE_WINDOW(seconds) through a per-location cache (the Cache API on Workers, an in-process LRU in containers). It is best effort; the store is the authority. - Store deduplication. The store applies a record once per
event_id, scoped by the message, which it confirms against the project as ADR 0020 does. The facts and counts it writes are those of ADR 0047.
What reports say about opens
Section titled “What reports say about opens”- Reports give
opens(unique messages with any open),humanOpens(unique messages with at least one open that is notmachine), andmachineOpenShare, always together, with the caveatopens_unreliable: “Opens are estimates. Apple Mail Privacy Protection opens most messages delivered to Apple Mail, and clients that block images never report an open.” - Conditions, and so goals and audiences (ADR 0045), cannot test opens or clicks. An experiment uses
human_opensonly when it declares it, with the caveat (ADR 0048). - Clicks are classified the same way; click metrics use
humanClicks.
Settings and consent
Section titled “Settings and consent”- Each project has
tracking.opensandtracking.clicks, both on by default (maintainer’s decision), changed byprojects.setTracking(principal: "any", scopeadmin, roleadmin). - Transactional-stream mail is never tracked: no pixel and no rewritten links. Until it is decided which messages are transactional, every workflow message is marketing.
- A send step may set
tracking: { opens: false, clicks: false }. - A customer whose reserved attribute
trackingOptOutistruegets no pixel and no rewritten links. - When a project is created, the dashboard and the creating action show the tracking choice explicitly, preselected on. The docs state that the user is the controller of their recipients’ data and Customer.lite their processor, and that consent for tracking in the EU (ePrivacy) is the user’s to obtain;
trackingOptOutis how they honour its absence. Consent handling remains a Before launch item. - The message records whether it was tracked (
tracked_opens,tracked_clicks), so rates are computed over tracked messages only.
Privacy
Section titled “Privacy”- Open and click records are personal data. They hold no IP address or user agent, and neither the tracker nor a consumer logs those (ADR 0032); what the platform records about tracker requests is the existing open item on platform logs.
- Customer deletion removes the customer’s engagement records with their messages (ADR 0023).
Consequences
Section titled “Consequences”- Opens are available, labelled as estimates, and kept out of decisions unless declared.
- Classification has one implementation for both targets and a version on every record; changing a list is a reviewed pull request.
- ADR 0020’s bot heuristics move to the core function (request signals) and the store (timing and bursts); queue payloads stay free of personal data.
- The tracker gets a per-location dedupe cache, and the store an index on engagement event IDs within the hot window.
- Open: whether to classify more proxies as their providers document them; a per-workspace tracking subdomain (ADR 0020’s later item).