Get statistics by template
Returns aggregate delivery and engagement counts grouped by the template each message was sent with, so a template's deliverability and engagement can be compared side by side. Attribution is by the template used at send time; only messages sent with a template appear here, so a workspace that has sent none returns an empty list rather than an error. Each row is keyed by the template ID (emt_…); a template deleted after sending still appears by its ID.
Rows are ranked by the sort metric (default processed) descending and paginated with the requested limit (default 50, hard maximum 200). Rows are computed against event time (not send time), so engagement received during the period for messages sent earlier is included.
The maximum window is 365 days; requesting a longer range returns 422.
Request
- Base URL: https://us1.platform.bird.com
- URL: https://us1.platform.bird.com/v1/email/stats/templates
- Auth: one of:
- HTTP bearer
- API key in cookie bird_session
Query parameters
Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.
Start date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in timezone (a UTC day when timezone is omitted). Defaults to 30 days before to when omitted; with include_trend=true and trend_grain=hourly the default tightens to 29 days before to, keeping the defaulted window within the 720-hour trend cap.
End date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in timezone (a UTC day when timezone is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days.
IANA timezone identifier used to group statistics, for example Asia/Kathmandu. The default is UTC. Day and hour boundaries, including the default window when from and to are omitted, follow this timezone. When this parameter is set, pass from and to as calendar days or Z instants instead of timestamps with explicit UTC offsets.
Not supported on breakdown endpoints; supplying it returns 422. To compare categories use GET /v1/email/stats/categories; the summary, daily, and hourly statistics accept category as a filter.
Metric to rank breakdown rows by, applied descending. Shared by the breakdowns whose rows have the full delivery, engagement, and latency block: tags, sending domains, categories, recipient domains, templates, and broadcasts. Any count or rate can be used. A row whose rate is undefined, because its denominator was zero, sorts last. A bounce sub-type is nested under bounces in each row, so its sort name reflects that, for example bounces.hard and bounces.hard_rate. oob_bounces is distinct from bounced: it counts out-of-band bounces, failure notifications that arrive after delivery was already confirmed.
Metric to rank rows by, applied descending. Any count or rate in the response may be used; rows whose rate is undefined (zero denominator) sort last. Defaults to processed.
Maximum number of template rows to return, ranked by the sort field descending.
When true, each row also has a trend array: a short per-bucket series of that template's delivery and engagement rates over the window. Returned only when limit is 50 or fewer and the window is at most 90 days (trend_grain=daily) or 720 hours (trend_grain=hourly); a larger request returns 422. When from is omitted and trend_grain=hourly, the default start tightens to 29 days before to, keeping the window inside 720 hours, so a request built entirely from defaults always fits the cap.
Bucket grain for a stats trend series.
Bucket grain for the trend series. Has no effect unless include_trend=true.
Headers
Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.
Response
Per-template breakdown for the requested period.
Example response
{
"period": {
"from": "2026-05-01",
"to": "2026-05-25",
"data_as_of": "2026-05-25T14:03:10Z"
},
"data": [
{
"template_id": "emt_01krdgeqcxet5s7t44vh8rt9mg",
"delivery": {
"accepted": 14820,
"processed": 14810,
"delivered": 14720,
"bounced": 90,
"bounces": {
"hard": 12410,
"soft": 14290,
"admin": 410,
"block": 920,
"undetermined": 80,
"hard_rate": 0.454,
"soft_rate": 0.523,
"admin_rate": 0.015,
"block_rate": 0.0337,
"undetermined_rate": 0.0029
},
"complained": 3,
"deferred": 14,
"rejected": 10,
"oob_bounces": 2,
"effective_delivered": 14718,
"all_bounces": 92,
"oob_rate": 0.00014,
"delivery_rate": 0.9939,
"bounce_rate": 0.0061,
"complaint_rate": 0.0002
},
"engagement": {
"opens": 5420,
"opens_non_prefetched": 3210,
"unique_opens": 3640,
"unique_opens_non_prefetched": 2480,
"clicks": 924,
"unique_clicks": 621,
"unsubscribes": 12,
"open_rate": 0.1683,
"click_rate": 0.0422,
"unsubscribe_rate": 0.0009
},
"latency": {
"processing": {
"p50_ms": 420,
"p95_ms": 1820,
"p99_ms": 4920
},
"delivery": {
"p50_ms": 420,
"p95_ms": 1820,
"p99_ms": 4920
},
"total": {
"p50_ms": 420,
"p95_ms": 1820,
"p99_ms": 4920
}
},
"trend": [
{
"bucket": "2026-05-12"
}
]
}
],
"total": 42,
"next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
"refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}Changes
No recorded changes to this operation across all 2 revisions of this API.