reports

Deliverability time series

GET /v1/reports/deliverability

Auth required reports.view

Time-bucketed counts of sent, delivered, bounced, complained, and suppressed, with a per-bucket delivery_rate. Numbers match what you see in the SendOps dashboard. Buckets are aligned to UTC (day = midnight UTC; week = Monday 00:00 UTC; month = first of month 00:00 UTC). Empty periods are not zero-filled — buckets with no underlying events are omitted entirely.

Formula: delivery_rate = delivered / sent, a ratio in [0, 1]. When sent is zero, delivery_rate is 0.0 (never null). suppressed counts SES Reject events — sends SES dropped against the account-level suppression list — not the size of your suppression table.

Default window is the trailing 30 days. A from older than your plan's retention returns 403 plan_retention_exceeded with a retention_days extension.

Query parameters

from string<date-time> optional

Window start (RFC 3339). Defaults to 30 days ago.

to string<date-time> optional

Window end (RFC 3339). Defaults to now.

group_by string enum optional

Time-bucket size for the report. UTC-aligned: day = midnight UTC; week = Monday 00:00 UTC (ISO week); month = first of month 00:00 UTC. Buckets with no underlying events are omitted, not zero-filled.

channel string<uuid> optional

Filter by channel UUID. Malformed values return 422 validation_failed.

identity string optional

Filter by sending identity. Accepts a full email address (the local-part is ignored — only the domain matches) or a bare domain.

Responses

200 Deliverability buckets, oldest-first application/json

401 Missing, malformed, or unknown API key application/problem+json

403 Key lacks the required scope or plan limit violated application/problem+json

422 Query parameter or path value failed validation application/problem+json

429 Per-org rate limit exceeded application/problem+json

500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json