Metrics

Overview

GET /api/v1/metrics defaults to the last 30 days. A window may not exceed 365 days.

These are the same numbers, from the same code, as the campaign report in the dashboard — so an agent reading this endpoint and a person reading the report cannot be told different things about the same window.

What is counted

Three rules, because each one changes the answer materially.

Live sending traffic only. Test-mode captures (ps_test_ sends) and lifecycle mail PristineSend sends to you — approval, quota and reputation notices — are both excluded. Counting either inflates volume, and since neither bounces or complains, both would pad the denominator and let a real complaint rate hide behind them.

Bounces and complaints are counted on their own timestamps, not on status. A message's status holds only its most recent event, so a complaint followed by an open would otherwise vanish from the count.

The window filters send time. A message sent inside the window that bounced after it still counts as a bounce for that window, because it belongs to the traffic you sent.

Get metrics

Optional start and end as ISO 8601 timestamps.

"color:#ff7b72">import { PristineSend } "color:#ff7b72">from "pristinesend"

"color:#ff7b72">const ps = "color:#ff7b72">new PristineSend(process.env.PRISTINESEND_API_KEY!)

"color:#ff7b72">const metrics = "color:#ff7b72">await ps.metrics.get({ start: "2026-08-01T00:00:00Z" })
console.log(metrics.sent, metrics.rates)

Response

{
  "data": {
    "window": { "start": "2026-08-01T00: 00: 00.000Z", "end": "2026-08-31T00: 00: 00.000Z" },
    "sent": 8422,
    "delivered": 8301,
    "opened": 3140,
    "clicked": 612,
    "bounced": 74,
    "complained": 3,
    "unsubscribed": 19,
    "rates": {
      "deliveryRate": 98.6,
      "openRate": 37.8,
      "clickRate": 7.4,
      "bounceRate": 0.9,
      "complaintRate": 0.04
    }
  }
}

Errors

A malformed or inverted window returns 400 invalid_field naming start or end. A window longer than 365 days is refused the same way.

If the counts cannot be read, this endpoint returns an error rather than zeros. A fabricated 0% bounce rate is a number you would act on, and it is indistinguishable from a genuinely clean window — so it is never returned. See Errors.