Template Metrics API

GET /notifications/{id}/metrics returns the delivery funnel for one notification template as a time series: sent, delivered, opened, clicked, errors, and undeliverable, broken out per provider and channel inside every bucket. Use it to build your own dashboards, alert when a delivery rate drops, pull the numbers into a warehouse or BI tool, or let an agent answer “how is this template doing?” without opening the Courier app.

Endpoint

GET https://api.courier.com/notifications/{id}/metrics Authenticate with your workspace API key as a Bearer token: Authorization: Bearer <token>. id is the template ID (nt_ prefix) or its alias. Full parameter and response details are on the reference page.

Pick a window

Two ways to set the window:

lookback: an ISO 8601 duration counted back from now, like P30D, P12W, or PT12H. If you send no window at all, Courier uses P30D.
start and end: ISO 8601 timestamps with an offset, like 2026-08-01T00:00:00Z. Supply both or neither. Either one alone returns 400, as does a start that is not earlier than end. An end in the future is accepted and not clamped, so the trailing buckets come back empty.

If you send both, start and end win and lookback is ignored. All boundaries are UTC. There is no timezone support, so a “day” is a UTC day. Courier widens the window to whole buckets, so every bucket the window touches comes back complete. A request for the last 36 hours at DAY granularity returns two full days, not a day and a half. The response echoes the snapped start and end. Label charts with those, not with the values you requested.

Pick a granularity

granularity sets the bucket size: HOUR, DAY (the default), WEEK, or MONTH. WEEK buckets start on Sunday. A finer granularity caps the window it can cover:

Granularity	Maximum window
`HOUR`	7 days
`DAY`	90 days
`WEEK`	Uncapped
`MONTH`	Uncapped

A wider window returns 400. Use a coarser granularity instead of splitting the range across calls. WEEK and MONTH have no window cap, but every response is limited to 1000 buckets, and a request that would exceed that also returns 400.

Read the response

{
  "notificationId": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "granularity": "DAY",
  "start": "2026-08-17T00:00:00Z",
  "end": "2026-08-20T00:00:00Z",
  "series": [
    { "period": "2026-08-17T00:00:00Z", "data": [] },
    {
      "period": "2026-08-18T00:00:00Z",
      "data": [
        { "provider": "sendgrid", "channel": "email", "sent": 412, "delivered": 408, "opened": 173, "clicked": 41, "errors": 0, "undeliverable": 4 },
        { "provider": "twilio", "channel": "sms", "sent": 96, "delivered": 95, "opened": 0, "clicked": 12, "errors": 1, "undeliverable": 0 }
      ]
    }
  ]
}

series holds one entry per bucket between the snapped start and end, oldest first. Each entry has a period, the start of the bucket in UTC, and a data array with one row per provider and channel that handled a message in that bucket. Quiet buckets are still returned, with data: [], so a series is plottable as-is with no gap filling on your side. There is no bucket-level total. Sum the rows in a bucket to get one, and compute rates from the sums:

function totals(bucket) {
  return bucket.data.reduce(
    (acc, row) => ({
      sent: acc.sent + row.sent,
      delivered: acc.delivered + row.delivered,
      opened: acc.opened + row.opened,
    }),
    { sent: 0, delivered: 0, opened: 0 }
  );
}

for (const bucket of metrics.series) {
  const { sent, delivered, opened } = totals(bucket);
  const deliveryRate = sent ? delivered / sent : null;
  const openRate = delivered ? opened / delivered : null;
  console.log(bucket.period, { sent, deliveryRate, openRate });
}

Guard the division: an empty bucket has a sent of zero.

delivered depends on the provider reporting delivery back to Courier, and opened is always 0 on channels with no open tracking. See Analytics to set up delivery tracking for your providers.

Fetch the last 7 days

curl "https://api.courier.com/notifications/$TEMPLATE_ID/metrics?lookback=P7D&granularity=DAY" \
  -H "Authorization: Bearer $COURIER_API_KEY"

// npm install @trycourier/courier
import Courier from "@trycourier/courier";

const client = new Courier();

const metrics = await client.notifications.getMetrics(templateId, {
  lookback: "P7D",
  granularity: "DAY",
});

console.log(metrics.start, metrics.end, metrics.series.length);

# pip install trycourier
from courier import Courier

client = Courier()

metrics = client.notifications.get_metrics(
    template_id,
    lookback="P7D",
    granularity="DAY",
)

print(metrics.start, metrics.end, len(metrics.series))

Plan limits and rate limits

Plan	Max lookback	Requests per second
Developer (free)	30 days	1
Business	90 days	2
Enterprise	730 days	5

Rate limits are per workspace, and every response carries RateLimit-* headers so you can pace a backfill.

A window that reaches further back than your plan allows returns 402, not a truncated series. Check the plan cap before you widen a range. A 429 carries Retry-After: wait that many seconds before retrying.

Errors

Status	`type`	When it happens
400	`invalid_params`	A malformed duration or timestamp, one of `start`/`end` without the other, a `start` that is not earlier than `end`, a granularity too fine for the window, or more than 1000 buckets. For example: `Granularity HOUR is too fine for the requested 90 day range.`
402	`payment_required`	The window exceeds your plan’s lookback cap: `Requested date range exceeds your plan's maximum lookback of 30 days.`
429	`rate_limit_exceeded`	Too many requests per second for the plan. Retry after the seconds in `Retry-After`.
503	`service_unavailable`	`Metrics are temporarily unavailable.` Retry after the seconds in `Retry-After`.

Good to know

An unknown template ID returns 200 with an all-empty series, not 404. Confirm the ID before you conclude a template sent nothing.
Messages sent without a template never appear here.
This endpoint is per-template only. To cover the whole workspace, list your templates with GET /notifications and call metrics for each one.
Available in the US region only.

Analytics: view these metrics in the Courier app.
Create and edit templates via API: the rest of the /notifications API.
Message Logs: per-message delivery detail instead of aggregates.

Platform

Developer Tools

Help

Template Metrics API

Endpoint

Pick a window

Pick a granularity

Read the response

Fetch the last 7 days

Plan limits and rate limits

Errors

Good to know

​Endpoint

​Pick a window

​Pick a granularity

​Read the response

​Fetch the last 7 days

​Plan limits and rate limits

​Errors

​Good to know

​Related

Endpoint

Pick a window

Pick a granularity

Read the response

Fetch the last 7 days

Plan limits and rate limits

Errors

Good to know

Related