Read your analytics

NevarMail provides comprehensive analytics for monitoring email delivery, opens, clicks, bounces, and other engagement events.

All endpoints on this page require a signed-in browser session. API keys are not accepted here and receive a 403 SESSION_ONLY error. Two analytics endpoints are API-key-callable: GET /api/v1/analytics/summary for org-level counts and GET /api/v1/analytics/messages/:messageId for one message's event timeline (see API Reference).

Summary

Get a high-level overview of your email performance for a given date range:

GET /api/analytics/summary?from=2026-03-01T00:00:00Z&to=2026-03-22T23:59:59Z

{
  "totalSent": 150,
  "totalDelivered": 145,
  "totalOpened": 50,
  "totalClicked": 12,
  "totalBounced": 3,
  "deliveryRate": 96.67,
  "openRate": 34.48,
  "clickRate": 24.0,
  "bounceRate": 2.0
}

Query parameters

All analytics endpoints accept optional date range parameters. If omitted, they default to the last 30 days.

Delivery report

GET /api/analytics/delivery-report

The current implementation does not break results down by day or by provider: dailyStats is always empty, and providerBreakdown always contains a single synthetic "all" entry summing every provider together.

{
  "dailyStats": [],
  "providerBreakdown": [
    { "provider": "all", "sent": 150, "delivered": 145, "bounced": 3 }
  ]
}

Bounce report

Analyze bounce patterns to identify delivery issues:

GET /api/analytics/bounce-report

{
  "totalBounces": 5,
  "bouncesByReason": [
    { "reason": "invalid_address", "count": 3 },
    { "reason": "mailbox_full", "count": 2 }
  ],
  "bouncesByProvider": [
    { "provider": "sendgrid", "count": 5 }
  ]
}

Per-email stats

Get the event timeline for a specific email:

GET /api/analytics/stats/:emailId

{
  "emailId": "550e8400-e29b-41d4-a716-446655440000",
  "events": [
    { "type": "sent", "timestamp": "2026-03-22T12:00:00.000Z", "metadata": null },
    { "type": "delivered", "timestamp": "2026-03-22T12:00:03.000Z", "metadata": null },
    { "type": "opened", "timestamp": "2026-03-22T12:00:10.000Z", "metadata": null },
    { "type": "clicked", "timestamp": "2026-03-22T12:01:30.000Z", "metadata": null }
  ]
}

Event types

The types below describe events NevarMail tracks. sent is recorded when NevarMail hands the message to your provider. delivered, bounced and the rest arrive from your provider's event webhook: a managed account has it pointed at NevarMail automatically; on a SendGrid account you connected yourself, point its Event Webhook at NevarMail (Settings → Providers) or these events never arrive and every message stays at sent. Only opened, clicked, and bounced can be recorded manually via POST /api/analytics/track -- see the warning below.

Track custom events

Manually record an opened, clicked, or bounced event for an email:

POST /api/analytics/track
{
  "emailId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "clicked",
  "recipient": "user@example.com",
  "provider": "sendgrid",
  "url": "https://yourdomain.com/promo",
  "metadata": { "campaign": "spring-2026" }
}

Returns { "tracked": true } on success.

Warning -- false success on sent/delivered: passing type: "sent" or type: "delivered" does not record anything (those event types are only ever produced automatically), but the endpoint still returns { "tracked": true }. Do not rely on the response to confirm a sent or delivered event was recorded -- only pass opened, clicked, or bounced.

Key metrics explained