Skip to main content

Convex Integration

Convex provides real-time database capabilities for Kinetic Email's tracking system.

Why Convex?​

Email interaction tracking requires:

  • Real-time updates — See opens and clicks as they happen
  • High write throughput — Tracking pixels fire frequently
  • Low-latency reads — Station dashboard needs instant data
  • Simple schema — Event-based data is naturally document-oriented

Convex handles all of these better than polling a traditional database.

Schema​

// convex/schema.ts
trackingEvents: defineTable({
  sendId: v.string(),
  userId: v.optional(v.string()),
  actionId: v.string(),
  timestamp: v.number(),
  metadata: v.optional(v.object({ ... })),
})

Data Flow​

Email opened in client
    │
    ▼
Tracking pixel loads: GET /api/track-pixel?sendId=...&actionId=open
    │
    ▼
Vercel function logs event to Convex
    │
    ▼
Convex triggers real-time subscription
    │
    ▼
Station dashboard updates instantly

Configuration​

Set VITE_CONVEX_URL to your Convex deployment URL. Deploy Convex functions with:

npx convex deploy

The build pipeline runs Convex deploy first, before the Vite build.

Station Dashboard​

The Kinetic Database page (/station/database) queries Convex in real-time to display:

  • Open rates by send
  • Interaction heatmaps
  • Engagement timelines
  • Action breakdowns (which tabs/options were most popular)