Email deliverability stats
GET/api/v1/email/stats
curl -X GET 'https://www.unitpost.com/api/v1/email/stats' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'User-Agent: my-app/1.0'{
"windowDays": 0,
"clampedToRetentionDays": 0,
"totals": {
"sent": 0,
"delivered": 0,
"opened": 0,
"clicked": 0,
"bounced": 0,
"complained": 0,
"failed": 0,
"bounced_permanent": 0,
"bounced_transient": 0,
"suppressed": 0,
"unsubscribed": 0
},
"rates": {
"delivery": 0,
"open": 0,
"click": 0,
"bounce": 0,
"complaint": 0,
"unsubscribe": 0
},
"domain_id": "domain_123",
"from": "you@yourdomain.com",
"to": "customer@example.com",
"series": {
"grain": "5m",
"time_zone": "string",
"buckets": [
{
"bucket": "string",
"sends": 0
}
]
}
}Retrieve aggregate deliverability and engagement metrics for your workspace over a rolling window. You get totals (sent, delivered, opened, clicked, bounced, complained, failed) alongside the rates that matter — delivery, open, click, bounce, and complaint. Open and click rates count only emails where that tracking was enabled, so turning tracking off for transactional mail won't skew them. Bounces are split into permanent and transient, with the sends that skipped a suppressed recipient and the unsubscribes your emails led to. Control the window with days (1–365, default 30), or count a period with from and to; add grain (and tz) for the send volume per bucket, as the dashboard home charts it. domain_id counts one sending domain. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. For the individual emails behind these numbers, see List sent emails. Requires the emails:read capability.
Parameters6 fields
| Field | Type | Description |
|---|---|---|
days | integer · query | Window size in days (1–365). Defaults to 30; values above 365 are rejected. |
from | string · query | Start of a period, with `to` (instead of `days`). ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). Not in the future. |
to | string · query | End of the period, exclusive. At most 366 days after `from`; with `grain`, at most 6 hours (`5m`), 3 days (`1h`) or 93 days (`1d`) (a longer period keeps its totals, without `series`). With `days`, `from` and `to` are ignored. |
grain | string · query | With `from` and `to`: return `series`, the send volume per bucket of five minutes, an hour or a day. |
tz | string · query | With `grain`: the IANA time zone the buckets are keyed in (default `UTC`). |
domain_id | string · query | Count only emails sent from this domain (`dom_…`). |
Response · 200 fields8 fields
| Field | Type | Description |
|---|---|---|
windowDaysrequired | integer | The window, in days (a period's length, rounded up). |
clampedToRetentionDays | integer | Non-null when the window reached past the plan's log retention: counting starts this many days back (data past the retention horizon is purged). |
totalsrequired | object | — |
ratesrequired | object | Percentages (one decimal). delivery/bounce/complaint are vs sent; open/click are vs delivered with that tracking on; unsubscribe vs delivered. |
domain_id | string | null | The sending domain counted (`domain_id`), or null for every domain. |
from | string | Start of the window counted (UTC). |
to | string | End of the window counted, exclusive (UTC). |
series | object | null | The send volume per `grain` bucket over `from`–`to`, as the dashboard home charts it; null without `grain`. |