Skip to main content

Tracking API

Kinetic Email tracks email opens and interactions through tracking pixels — tiny transparent images embedded in the email HTML that fire a request when loaded.

How Tracking Works​

Email is sent with embedded tracking pixels
    │
    ▼
Email client renders email → pixel image loads
    │
    ▼
Server logs interaction event to real-time database
    │
    ▼
Station dashboard shows live analytics

Capabilities​

  • Open tracking — Detect when a recipient opens the email
  • Interaction tracking — Track which tabs, carousel slides, survey options, or quiz answers the recipient engaged with
  • Real-time analytics — Events are stored in Convex for instant dashboard updates

GET /api/track-pixel​

Runs on the Vercel Edge runtime and always returns a 1x1 transparent GIF, even on error, so a tracking failure never breaks the email.

Query parameters: u (hashed user ID), s (send ID), e (email name), a (action ID), plus optional src (kinetic | amp), db (workspace database ID), and p (project ID). AMP interactions are logged through the companion POST /api/track-amp-event Edge endpoint.

Privacy​

  • Recipient emails are never stored raw. Send paths substitute {{UUID}} with a SHA-256 hash of the lowercased email + salt. If an ESP substitutes a raw address into the u parameter, the pixel endpoint detects the @ and applies the same hash server-side before anything is logged.
  • IP addresses are salted-hashed (SHA-256 with IP_SALT, truncated). If the salt is missing or too short, the IP is dropped entirely rather than stored weakly hashed.

Kinetic Interaction Tracking​

Beyond simple opens, kinetic emails can track specific interactions. Each interactive element (tab, carousel slide, survey option) can embed its own tracking reference. When the recipient interacts with that element, the CSS :checked state triggers a background-image load that records the event.

This enables analytics like:

  • "62% of recipients clicked Tab 2 (Pricing)"
  • "Survey option A was selected 3x more than option B"
  • "Carousel slide 3 had the highest engagement"

Data & Analytics​

Events are stored in a real-time database and displayed on the Station admin dashboard, including:

  • Open rates per send
  • Interaction heatmaps
  • Engagement timelines
  • Per-element action breakdowns