Email Tracking Worker¶

The tracking worker handles open and click tracking for outgoing email. It is a FastAPI service that injects a 1x1 tracking pixel and rewrites links in outbound HTML, records open/click events in MySQL, manages the suppression list, and fires webhook events on engagement.

What It Does¶

• Injection API -- the Postfix tracking injector POSTs outbound HTML here; the service returns it with a pixel injected and links rewritten
• Open tracking -- serves the pixel and records an open event
• Click tracking -- records a click event and 302-redirects to the original URL
• Bounce and complaint ingestion -- feeds the suppression list
• Suppression list management -- suppress/unsuppress addresses, one-click unsubscribe
• Signed tracking IDs -- HMAC-SHA256-signed tokens prevent forged events
• Webhook events -- tracking.open, tracking.click, email.bounced, delivery.complaint via shared.webhook_dispatcher

How It Works¶

sequenceDiagram
    participant PF as Postfix<br/>(tracking_injector.py)
    participant TW as Tracking Worker<br/>:8086
    participant GW as API Gateway<br/>(public URLs)
    participant DB as MySQL
    participant R as Recipient's<br/>Email Client

    PF->>TW: POST /api/tracking/inject<br/>{html content, message metadata}
    TW->>TW: Generate signed tracking ID
    TW->>TW: Inject pixel + rewrite links
    TW-->>PF: Modified HTML

    Note over PF: Email delivered to recipient

    R->>GW: GET /api/v1/tracking/pixel/{tracking_id}
    GW->>TW: GET /open/{tracking_id}
    TW->>DB: INSERT open event
    TW-->>R: 1x1 transparent PNG

    R->>GW: GET /api/v1/tracking/click/{tracking_id}?url=...
    GW->>TW: GET /click/{tracking_id}
    TW->>DB: INSERT click event
    TW-->>R: 302 Redirect to original URL

Public URLs go through the API gateway¶

The pixel and click URLs embedded in mail must resolve on the public internet. They are built from TRACKING_BASE_URL plus TRACKING_PIXEL_PATH / TRACKING_CLICK_PATH (defaults /api/v1/tracking/pixel and /api/v1/tracking/click) -- i.e. they point at the API gateway's public hostname, and the gateway's /api/v1/tracking/* routes forward to this worker.

API Endpoints¶

Copied from the routers in worker/tracking/api/ (mounted in app.py; stats_api carries an /api prefix):

# tracking_api (event recording)
GET  /open/{tracking_id}                    -- Record open, serve pixel
GET  /click/{tracking_id}?url=              -- Record click, redirect
POST /api/tracking/bounce                   -- Ingest a bounce notification
POST /api/tracking/complaint                -- Ingest an FBL complaint

# suppression_api
POST   /tracking/suppress                   -- Suppress an address
DELETE /tracking/suppress/{email}           -- Remove a suppression
GET    /tracking/unsubscribe/{tracking_id}  -- One-click unsubscribe page
POST   /tracking/unsubscribe/{tracking_id}  -- One-click unsubscribe (RFC 8058)

# stats_api (mounted under /api)
POST /api/tracking/inject                   -- Inject pixel + rewrite links (called by Postfix)
GET  /api/tracking/stats/{email_id}         -- Stats for one message
GET  /api/tracking/stats/domain/{domain}    -- Per-domain stats
GET  /api/tracking/stats/summary            -- Summary stats
GET  /api/tracking/tenant/{tenant_id}/stats -- Per-tenant stats
GET  /api/tracking/health                   -- Stats subsystem health

# health_api
GET /health            -- Health check
GET /health/detailed   -- Detailed health
GET /ready             -- Readiness probe
GET /live              -- Liveness probe

# app.py
GET /metrics           -- Prometheus metrics

Tenant-facing access (pixel, click, unsubscribe, suppression management, stats) is proxied by the API gateway under /api/v1/tracking/* (worker/api/routes/tracking.py), with organization scoping enforced there -- wired up and working since 2026-08-08.

Tracking ID Structure¶

Tracking IDs are not JWTs. Each ID is the URL-safe base64 encoding of:

{email_id}:{recipient}:{tenant_id}:{domain_id}:{timestamp}:{nonce}:{signature}

where signature is the first 16 hex chars of an HMAC-SHA256 over the preceding fields, keyed with WEBHOOK_SECRET. decode_tracking_id() verifies the signature with a constant-time compare before any event is recorded, so events cannot be forged by guessing URLs.

Data Stores¶

Configuration¶

Docker Configuration¶

tracking:
  build:
    context: .
    dockerfile: ./worker/tracking/Dockerfile
  container_name: tracking
  ports:
    - "8086:8086"
  extra_hosts:
    - "host.docker.internal:host-gateway"

In production (docker-compose.prod.yml) the service runs with replicas: 2 -- container_name and the host port mapping are reset there, since fixed names and host ports cannot be shared between replicas; Traefik and the other services reach it by service name.

Connections to Other Services¶

• Postfix calls /api/tracking/inject from mailer/postfix/scripts/tracking_injector.py, which runs as the tracking-filter content filter on the submission (587), smtps (465), and internal 10587 listeners
• Webhook events are dispatched directly via shared.webhook_dispatcher (HTTP POST to WEBHOOK_URL), not via Redis pub/sub
• Analytics worker reads email_tracking for engagement reporting
• API gateway fronts all public and tenant-facing routes

Gotchas¶