email-tracking-worker.md

summary	Tracking Worker internals (routes, schema, keys)
read_when	Changing Worker endpoints or schema Debugging tracking id collisions / open queries

Email tracking worker

Location:

• Worker source: internal/tracking/worker/src/
• Schema: internal/tracking/worker/schema.sql

Bindings / config

Expected bindings:

• D1 database binding: DB
• Secrets: TRACKING_KEY, TRACKING_KEY_V<N>, TRACKING_CURRENT_KEY_VERSION, ADMIN_KEY

wrangler.toml is the local template; deployments set the real D1 database id.

TRACKING_KEY remains as the current-key fallback for legacy deployments and legacy unversioned tracking ids. New rotated deployments also set TRACKING_KEY_V1, TRACKING_KEY_V2, etc. The Worker reads the one-byte version prefix from new tracking ids, uses the matching TRACKING_KEY_V<N> when present, and falls back through active keys for older unversioned ids.

Routes (high-level)

• Pixel:

  • GET /p/<tracking_id>.gif
  • Validates/decrypts tracking_id, stores an open row, returns a transparent GIF.

• Query:

  • GET /q/<tracking_id>
  • Returns opens for that tracking id (no auth).

• Admin:

  • GET /opens?recipient=<email>&since=<...>
  • Auth: Authorization: Bearer <ADMIN_KEY>.

Schema notes

• tracking_id is stored for lookup by tracking id.
• opened_at stored as an ISO string for consistent ordering/comparison.

Local dev

cd internal/tracking/worker
pnpm install
pnpm dev

Tests

cd internal/tracking/worker
pnpm lint
pnpm build
pnpm test