API Reference

Metrics

Delivery and engagement totals for your workspace over a window, plus the rates derived from them. Requires the metrics:read scope.

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

Four 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.

A click on the unsubscribe link is not a click. A message whose only clicks were on its unsubscribe link is left out of clicked: that is someone leaving, not engagement. It still counts as delivered and opened, because clicking a link in the email proves both.

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.

import { PristineSend } from "pristinesend"

const ps = new PristineSend(process.env.PRISTINESEND_API_KEY!)

const metrics = 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.