Gmail

Email tracking worker

GitHub Edit page

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