Skip to content

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)

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 deployed tracker, clicks recorded after the redirect through the tracking queue, 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.
  • 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 gain t: "c".
  • Each route accepts only its own type: /o only t: "o", /c only t: "c" (or a token without t, 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 /o with the GIF, Cache-Control: no-store, private, whether or not the token verifies, so the answer reveals nothing; it never redirects. HEAD requests on either route are answered and not recorded.
  • Text-only messages have no pixel and record no opens.
  • One pure function in core, classifyEngagement(signals, lists) → { class, reason }, used by each target’s tracker (the Worker on Cloudflare, the tracker service 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 (from request.cf on Workers, from its own lookup in containers), then passes classifyEngagement the 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), and classifyEngagement never 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); prefetch and burst (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_version and updated by pull request; Private Relay ranges are regenerated from Apple’s published list by a script. Every engagement record keeps the classifier_version that 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 carries decoy: 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 are machine:decoy, and clicks on the same message recorded after the decoy click and within ENGAGEMENT_BURST_WINDOW are machine: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 than ENGAGEMENT_PREFETCH_WINDOW (configuration, seconds) after the message’s accepted_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 yet accepted.
    • burst: a click on a different link of the message within ENGAGEMENT_BURST_WINDOW after 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 is machine.
    • 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.
  • 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) within TRACKER_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.
  • Reports give opens (unique messages with any open), humanOpens (unique messages with at least one open that is not machine), and machineOpenShare, always together, with the caveat opens_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_opens only when it declares it, with the caveat (ADR 0048).
  • Clicks are classified the same way; click metrics use humanClicks.
  • Each project has tracking.opens and tracking.clicks, both on by default (maintainer’s decision), changed by projects.setTracking (principal: "any", scope admin, role admin).
  • 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 trackingOptOut is true gets 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; trackingOptOut is 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.
  • 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).
  • 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).