Tracking & Analytics

The Tracking system records engagement events for notifications -- opens, clicks, and delivery status. The TrackingController at /api/v1/notifications/track provides tracking pixel endpoints for email opens, click redirect endpoints, and analytics APIs.

Track Email Open

Embedded in emails as a 1x1 transparent GIF. When the email client loads the image, it records an open event.

Endpoint: GET /api/v1/notifications/track/open/{trackingId}

The response is a 1x1 transparent GIF image with Cache-Control: no-cache, no-store, must-revalidate headers to ensure each open is recorded.

Track Link Click

Wrapped around links in email templates. Records the click event and redirects to the target URL.

Endpoint: GET /api/v1/notifications/track/click/{trackingId}

GET /api/v1/notifications/track/click/track-abc-123?url=https://acme.matih.ai/dashboard&label=dashboard-link

The response is a 302 Found redirect to the target URL.

Analytics Summary

Get engagement analytics for a tenant over a time period.

Endpoint: GET /api/v1/notifications/track/analytics/{tenantId}

curl "http://localhost:8085/api/v1/notifications/track/analytics/550e8400-e29b-41d4-a716-446655440000?startTimeEpoch=1707696000000&endTimeEpoch=1707782400000" \
  -H "Authorization: Bearer ${TOKEN}"

Response:

{
  "tenantId": "550e8400-...",
  "period": { "start": "2026-02-12T00:00:00Z", "end": "2026-02-13T00:00:00Z" },
  "totalSent": 1250,
  "totalDelivered": 1230,
  "totalOpened": 456,
  "totalClicked": 123,
  "deliveryRate": 0.984,
  "openRate": 0.371,
  "clickRate": 0.100,
  "bounceRate": 0.008,
  "byChannel": {
    "EMAIL": { "sent": 800, "delivered": 790, "opened": 350, "clicked": 100 },
    "SLACK": { "sent": 300, "delivered": 300, "opened": 106, "clicked": 23 },
    "PUSH": { "sent": 150, "delivered": 140, "opened": 0, "clicked": 0 }
  }
}

Notification Stats

Get stats for a specific notification.

Endpoint: GET /api/v1/notifications/track/stats/{notificationId}

Engagement Timeline

Get hourly engagement data for visualization.

Endpoint: GET /api/v1/notifications/track/timeline/{tenantId}

Preferences Unsubscribe