Get mailbox email statistics
Returns the mailbox's sent and received email statistics over a time window: a period-wide summary plus a bucketed series. Sent-mail metrics have the same delivery, engagement, and latency breakdowns as the email stats endpoints. received counts mail that arrived at the mailbox.
Rows are bucketed by the time the event happened rather than the time the message was sent, so engagement that arrived during the period for a message sent earlier is counted here. Statistics start when the mailbox starts sending and receiving; the mailbox's all-time message_count and thread_count live on the mailbox resource itself.
from and to accept either calendar days (YYYY-MM-DD, day granularity only) or RFC 3339 instants (hour granularity only). Both bounds must use the same form. Window caps depend on granularity: 365 days at day, 30 days at hour. Set timezone to report in a local zone instead of UTC.
Request
- Base URL: https://us1.platform.bird.com
- URL: https://us1.platform.bird.com/v1/email/mailboxes/{mailbox_id}/stats
- Auth: one of:
- HTTP bearer
- API key in cookie bird_session
Query parameters
Inclusive start of the window: a calendar day (YYYY-MM-DD, day granularity only) or an RFC 3339 instant rounded down to the hour (hour granularity only). Interpreted in timezone, or in UTC when timezone is omitted. A numeric UTC offset is rejected when timezone is set; use a calendar day or a Z (UTC) instant. Must use the same form as to. Defaults to 30 days before to at day granularity and 7 days before to at hour, when omitted.
Inclusive end of the window: a calendar day (YYYY-MM-DD, day granularity only) or an RFC 3339 instant rounded down to the hour (hour granularity only). Interpreted in timezone, or in UTC when timezone is omitted. A numeric UTC offset is rejected when timezone is set; use a calendar day or a Z (UTC) instant. Must use the same form as from. Defaults to today (day) or the current hour (hour) in that timezone when omitted. Window may not exceed 365 days at day or 30 days at hour granularity.
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.
Granularity of the series: day (default) or hour. Echoed back as period.grain.
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
The mailbox's sent and received email statistics for the requested period.
Example response
{
"period": {
"from": "2026-05-01",
"to": "2026-05-31",
"grain": "day",
"data_as_of": "2026-05-25T14:03:10Z"
},
"summary": {
"sends_accepted": 231,
"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
}
},
"received": 519
},
"data": [
{
"bucket": "2026-07-21",
"sends_accepted": 12,
"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
}
},
"received": 34
}
]
}Changes
No recorded changes to this operation across all 2 revisions of this API.