--- title: "Query email delivery and engagement metrics" method: POST path: "/v1/email/stats/query" tags: ["email-stats"] --- # Query email delivery and engagement metrics `POST /v1/email/stats/query` ## Request - Base URL: `https://us1.platform.bird.com` - URL: `https://us1.platform.bird.com/v1/email/stats/query` - Auth: one of: - HTTP bearer - API key in cookie `bird_session` Returns selected delivery, engagement, and latency metrics for the workspace. Combine filters, one grouping dimension, and a time grain for reports such as weekly deliveries by recipient domain for a campaign. Events are selected and bucketed by when they occurred. An open in the window can belong to a message sent earlier; later outcomes outside the window are excluded. Ungrouped requests return one summary; grouped pages retain each group's complete series. Counts deduplicate by each metric's identity; event counts are not audience sizes. Undefined rates or empty latency samples return null. Dates include whole local days. Instants include the quarter-hour containing the requested end. Responses echo normalized UTC bounds with an exclusive end. Follow cursors using the original body and replace the cursor fields. Requests can cover up to 365 local days or 720 hours for instant bounds, subject to available history. Unsupported combinations, unavailable history, or query-size limits return 422; a failed query returns no partial report. Idempotency is best-effort replay. Responses up to 256 KiB may be replayed while retained; larger valid responses up to 4 MiB are read again on retry. A key does not freeze an analytics snapshot. SDK iterators use your explicit key for the first page and a fresh automatic key per continuation page, reusing that page's key across retries. For a fresh read, omit the key or use a new one. ## Headers - `Idempotency-Key` string - `X-Workspace-Id` string - `X-Organization-Id` string ## Request body - EmailStatsQueryRequest: Select email metrics for one workspace and one time window. Group-only fields require group_by; defaults apply after grouping is selected. Queries are limited to 20,000 series points, 1,000,000 selected metric cells including period rows, and a 4 MiB JSON response. Unsupported combinations or unavailable history return 422. - `from` string, required: Inclusive start, as a calendar date or RFC 3339 instant. Use the same form for from and to. Instants round down to a local quarter-hour; use Z when timezone is supplied. - `to` string, required: Inclusive end. Dates include the whole local day; instants round down to a local quarter-hour and include that quarter-hour. Dates allow up to 365 local days; instants allow up to 720 hours, subject to available history. Preserve this original bound when following cursors. - `timezone` string: IANA timezone for dates and bucket boundaries. Defaults to UTC. - `metrics` EmailStatsQueryMetric[], required: Distinct metrics to return. Unselected metrics are absent. delivered and unique engagement counts estimate distinct message recipients. opens, opens_non_prefetched, clicks, unsubscribes, and oob_bounces estimate deduplicated events. effective_delivered and all_bounces are derived counts. Counts need not add up across buckets or groups. unique_opens and unique_clicks count message recipients, not distinct people across messages. Use returned period metrics; do not reconstruct totals from buckets or average rates or percentiles. delivered counts message recipients with a delivery event without subtracting later bounces. effective_delivered is max(delivered - oob_bounces, 0). open_rate uses unique_opens_non_prefetched divided by effective_delivered; click_rate uses unique_clicks divided by effective_delivered. bounce_rate uses min(bounced + oob_bounces, delivered + bounced) divided by (delivered + bounced). complaint_rate and unsubscribe_rate use complained and unsubscribes, respectively, divided by effective_delivered. Undefined rates are null. Engagement rates can exceed 1 across event-time windows. An unknown prefetch flag is treated as false. confirmed_unique_opens is the union of message recipients with opens or clicks; confirmed_unique_opens_non_prefetched excludes prefetched opens from that union. Differences between estimated distinct counts cannot establish exact audience overlaps or explain missing opens. Neither confirmation nor prefetch exclusion establishes a count or range of real people who engaged. Latency percentiles describe eligible measured logical events, excluding missing latency values and including zero. A percentile is null when no eligible samples exist. delivered is not the latency sample count. Report percentile values without inferring the unmeasured population or the distribution between them. They do not establish maxima or exact threshold counts; multiplying delivered by percentile fractions or subtracting processing and delivery percentiles cannot determine slow-message counts or a stage's latency. - `group_by` 'sending_domain' | 'category' | 'template_id' | 'tag' | 'recipient_domain' | 'mailbox_provider' | 'mailbox_provider_region' | 'sending_ip' | 'ip_pool_id' | 'broadcast_id' | 'country' | 'region' | 'city' | 'agent_family' | 'os_family' | 'device_family' | 'smtp_error_code' | 'feedback_type': Group by one recorded event dimension. Omit for a single ungrouped summary with optional series. Grouping by `tag` requires `filters.tag.name`. Missing values form a null group when the metric supports that dimension. A null value means the event lacks that attribution; it does not explain how the message was created or establish membership in another dimension such as a campaign. Every selected metric must support the grouping dimension and every filter dimension. Unsupported combinations return validation error `E04074`, even when the workspace has no events. - `sending_domain`, `category`, `template_id`, `tag`: all metrics. - `recipient_domain`, `ip_pool_id`, `broadcast_id`: all metrics except `sends_accepted`. - `mailbox_provider`, `mailbox_provider_region`: all metrics except `sends_accepted`, `accepted`, and `rejected`. - `sending_ip`: `delivered`, `bounced`, `hard_bounced`, `soft_bounced`, `admin_bounced`, `block_bounced`, `undetermined_bounced`, `deferred`, `oob_bounces`, `effective_delivered`, `all_bounces`, `delivery_rate`, `bounce_rate`, `deferral_rate`, `oob_rate`, `total_p50_ms`, `total_p95_ms`, and `total_p99_ms`. - `country`, `region`, `city`, `agent_family`, `os_family`, `device_family`: `opens`, `opens_non_prefetched`, `clicks`, `unique_opens`, `unique_opens_non_prefetched`, `unique_clicks`, `confirmed_unique_opens`, and `confirmed_unique_opens_non_prefetched`. - `smtp_error_code`: `bounced`, `hard_bounced`, `soft_bounced`, `admin_bounced`, `block_bounced`, and `undetermined_bounced`. - `feedback_type`: `complained`. - `grain` 'quarter_hour' | 'hour' | 'half_day' | 'day' | 'week' | 'month': Time buckets in the requested timezone. Weeks start on Monday; months start on the first day. Half days start at midnight and noon. Edge buckets count events inside the normalized period. - `filters` EmailStatsQueryFilters (unresolved $ref) - `sort` 'sends_accepted' | 'accepted' | 'processed' | 'delivered' | 'bounced' | 'hard_bounced' | 'soft_bounced' | 'admin_bounced' | 'block_bounced' | 'undetermined_bounced' | 'complained' | 'deferred' | 'rejected' | 'oob_bounces' | 'opens' | 'opens_non_prefetched' | 'clicks' | 'unsubscribes' | 'unique_opens' | 'unique_opens_non_prefetched' | 'unique_clicks' | 'confirmed_unique_opens' | 'confirmed_unique_opens_non_prefetched' | 'effective_delivered' | 'all_bounces' | 'delivery_rate' | 'bounce_rate' | 'complaint_rate' | 'deferral_rate' | 'open_rate' | 'click_rate' | 'unsubscribe_rate' | 'oob_rate' | 'processing_p50_ms' | 'processing_p95_ms' | 'processing_p99_ms' | 'total_p50_ms' | 'total_p95_ms' | 'total_p99_ms': Metric selected for period totals, time buckets, or group ranking. Counts estimate distinct identities; rates are ratios. Latency metrics measure milliseconds from Bird acceptance to processing or delivery. - `order` 'asc' | 'desc': Sort direction, ascending or descending. - `limit` integer: Grouped requests only. Maximum groups per page; defaults to 25. Each group retains its complete series. - `starting_after` string: Grouped requests only. Opaque next_cursor from the previous response. Mutually exclusive with ending_before. - `ending_before` string: Grouped requests only. Opaque prev_cursor for backward navigation, or refresh_cursor to read groups before the anchor in the current sort order. Mutually exclusive with starting_after. ## Response `200` Selected metrics, normalized bounds, and grouped navigation cursors. - EmailStatsQueryResponse: Selected email metrics with normalized bounds. Ungrouped requests return one group and null cursors, including empty windows. Grouped requests without observed groups return an empty data array. Live page reads can reflect new events or changed ranking. - `data` EmailStatsQueryGroup[], required - `dimensions` EmailStatsQueryDimensions, required: Contains the requested group_by property, including a null value when context is missing. Ungrouped results use an empty object. - `sending_domain` string, nullable: Recorded sending domain value. Null represents missing context and differs from an empty string. - `category` string, nullable: Recorded category value. Null represents missing context and differs from an empty string. - `template_id` string - `tag` string, nullable: Recorded tag value. Null represents missing context and differs from an empty string. - `recipient_domain` string, nullable: Recorded recipient domain value. Null represents missing context and differs from an empty string. - `mailbox_provider` string, nullable: Recorded mailbox provider value. Null represents missing context and differs from an empty string. - `mailbox_provider_region` string, nullable: Recorded mailbox provider region value. Null represents missing context and differs from an empty string. - `sending_ip` string, nullable: Recorded sending ip value. Null represents missing context and differs from an empty string. - `ip_pool_id` string - `broadcast_id` string - `country` string, nullable: Recorded country value. Null represents missing context and differs from an empty string. - `region` string, nullable: Recorded region value. Null represents missing context and differs from an empty string. - `city` string, nullable: Recorded city value. Null represents missing context and differs from an empty string. - `agent_family` string, nullable: Recorded agent family value. Null represents missing context and differs from an empty string. - `os_family` string, nullable: Recorded os family value. Null represents missing context and differs from an empty string. - `device_family` string, nullable: Recorded device family value. Null represents missing context and differs from an empty string. - `smtp_error_code` string, nullable: Recorded smtp error code value. Null represents missing context and differs from an empty string. - `feedback_type` string, nullable: Recorded feedback type value. Null represents missing context and differs from an empty string. - `metrics` EmailStatsQueryMetrics, required: Selected metric values. Counts are nonnegative approximate distinct counts. Period uniques and rates are computed independently of buckets; summing bucket or group values does not reconstruct period totals. Zero means a supported empty population; undefined rates and empty latency samples are null. - `sends_accepted` integer: Distinct sends accepted by Bird, counted by email identity. - `accepted` integer: Distinct message recipients accepted by Bird. - `processed` integer: Distinct message recipients processed for delivery. - `delivered` integer: Distinct message recipients with a delivery event. - `bounced` integer: Distinct message recipients with bounced events. - `hard_bounced` integer: Distinct message recipients with hard bounced events. - `soft_bounced` integer: Distinct message recipients with soft bounced events. - `admin_bounced` integer: Distinct message recipients with admin bounced events. - `block_bounced` integer: Distinct message recipients with block bounced events. - `undetermined_bounced` integer: Distinct message recipients with undetermined bounced events. - `complained` integer: Distinct message recipients with complained events. - `deferred` integer: Distinct message recipients with a deferral event. - `rejected` integer: Distinct message recipients rejected before provider delivery. - `oob_bounces` integer: Distinct out-of-band bounce events. - `opens` integer: Distinct open events, including prefetched opens. - `opens_non_prefetched` integer: Distinct open events excluding prefetched opens. An absent prefetch flag counts as false. - `clicks` integer: Distinct click events. - `unsubscribes` integer: Distinct unsubscribe events. - `unique_opens` integer: Distinct message recipients with an open event. - `unique_opens_non_prefetched` integer: Distinct message recipients with a non-prefetched open event. - `unique_clicks` integer: Distinct message recipients with a click event. - `confirmed_unique_opens` integer: Distinct message recipients with an open or click event, deduplicated across both. - `confirmed_unique_opens_non_prefetched` integer: Distinct message recipients with a non-prefetched open or click event, deduplicated across both. - `effective_delivered` integer: Delivered recipients less out-of-band bounce events, calculated as `max(delivered - oob_bounces, 0)`. - `all_bounces` integer: In-band bounced recipients plus out-of-band bounce events, calculated as `bounced + oob_bounces`. - `delivery_rate` number, double, nullable: Ratio of `effective_delivered / (delivered + bounced)`, from 0 to 1. Null when `delivered + bounced` is zero. - `bounce_rate` number, double, nullable: Ratio of `all_bounces / (delivered + bounced)`, capped at 1. Null when `delivered + bounced` is zero. - `complaint_rate` number, double, nullable: Ratio of `complained / effective_delivered`. Uncapped and can exceed 1 when complaints and deliveries fall in different windows. Null when `effective_delivered` is zero. - `deferral_rate` number, double, nullable: Ratio of `deferred / (delivered + bounced)`, capped at 1. Null when `delivered + bounced` is zero. - `open_rate` number, double, nullable: Ratio of `unique_opens_non_prefetched / effective_delivered`. Uncapped and can exceed 1 when opens and deliveries fall in different windows. Null when `effective_delivered` is zero. - `click_rate` number, double, nullable: Ratio of `unique_clicks / effective_delivered`. Uncapped and can exceed 1 when clicks and deliveries fall in different windows. Null when `effective_delivered` is zero. - `unsubscribe_rate` number, double, nullable: Ratio of `unsubscribes / effective_delivered`, using distinct unsubscribe events as the numerator. Uncapped and can exceed 1. Null when `effective_delivered` is zero. - `oob_rate` number, double, nullable: Ratio of `oob_bounces / (delivered + bounced)`, using distinct out-of-band bounce events as the numerator. Uncapped and can exceed 1. Null when `delivered + bounced` is zero. - `processing_p50_ms` integer, nullable: Processing latency at the 50th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `processing_p95_ms` integer, nullable: Processing latency at the 95th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `processing_p99_ms` integer, nullable: Processing latency at the 99th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `total_p50_ms` integer, nullable: Delivery latency at the 50th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `total_p95_ms` integer, nullable: Delivery latency at the 95th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `total_p99_ms` integer, nullable: Delivery latency at the 99th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `series` EmailStatsQueryPoint[]: Present when grain is requested; absent otherwise. - `bucket` string, date-time, required: Nominal bucket start as a UTC RFC 3339 instant. - `metrics` EmailStatsQueryMetrics, required: Selected metric values. Counts are nonnegative approximate distinct counts. Period uniques and rates are computed independently of buckets; summing bucket or group values does not reconstruct period totals. Zero means a supported empty population; undefined rates and empty latency samples are null. - `sends_accepted` integer: Distinct sends accepted by Bird, counted by email identity. - `accepted` integer: Distinct message recipients accepted by Bird. - `processed` integer: Distinct message recipients processed for delivery. - `delivered` integer: Distinct message recipients with a delivery event. - `bounced` integer: Distinct message recipients with bounced events. - `hard_bounced` integer: Distinct message recipients with hard bounced events. - `soft_bounced` integer: Distinct message recipients with soft bounced events. - `admin_bounced` integer: Distinct message recipients with admin bounced events. - `block_bounced` integer: Distinct message recipients with block bounced events. - `undetermined_bounced` integer: Distinct message recipients with undetermined bounced events. - `complained` integer: Distinct message recipients with complained events. - `deferred` integer: Distinct message recipients with a deferral event. - `rejected` integer: Distinct message recipients rejected before provider delivery. - `oob_bounces` integer: Distinct out-of-band bounce events. - `opens` integer: Distinct open events, including prefetched opens. - `opens_non_prefetched` integer: Distinct open events excluding prefetched opens. An absent prefetch flag counts as false. - `clicks` integer: Distinct click events. - `unsubscribes` integer: Distinct unsubscribe events. - `unique_opens` integer: Distinct message recipients with an open event. - `unique_opens_non_prefetched` integer: Distinct message recipients with a non-prefetched open event. - `unique_clicks` integer: Distinct message recipients with a click event. - `confirmed_unique_opens` integer: Distinct message recipients with an open or click event, deduplicated across both. - `confirmed_unique_opens_non_prefetched` integer: Distinct message recipients with a non-prefetched open or click event, deduplicated across both. - `effective_delivered` integer: Delivered recipients less out-of-band bounce events, calculated as `max(delivered - oob_bounces, 0)`. - `all_bounces` integer: In-band bounced recipients plus out-of-band bounce events, calculated as `bounced + oob_bounces`. - `delivery_rate` number, double, nullable: Ratio of `effective_delivered / (delivered + bounced)`, from 0 to 1. Null when `delivered + bounced` is zero. - `bounce_rate` number, double, nullable: Ratio of `all_bounces / (delivered + bounced)`, capped at 1. Null when `delivered + bounced` is zero. - `complaint_rate` number, double, nullable: Ratio of `complained / effective_delivered`. Uncapped and can exceed 1 when complaints and deliveries fall in different windows. Null when `effective_delivered` is zero. - `deferral_rate` number, double, nullable: Ratio of `deferred / (delivered + bounced)`, capped at 1. Null when `delivered + bounced` is zero. - `open_rate` number, double, nullable: Ratio of `unique_opens_non_prefetched / effective_delivered`. Uncapped and can exceed 1 when opens and deliveries fall in different windows. Null when `effective_delivered` is zero. - `click_rate` number, double, nullable: Ratio of `unique_clicks / effective_delivered`. Uncapped and can exceed 1 when clicks and deliveries fall in different windows. Null when `effective_delivered` is zero. - `unsubscribe_rate` number, double, nullable: Ratio of `unsubscribes / effective_delivered`, using distinct unsubscribe events as the numerator. Uncapped and can exceed 1. Null when `effective_delivered` is zero. - `oob_rate` number, double, nullable: Ratio of `oob_bounces / (delivered + bounced)`, using distinct out-of-band bounce events as the numerator. Uncapped and can exceed 1. Null when `delivered + bounced` is zero. - `processing_p50_ms` integer, nullable: Processing latency at the 50th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `processing_p95_ms` integer, nullable: Processing latency at the 95th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `processing_p99_ms` integer, nullable: Processing latency at the 99th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `total_p50_ms` integer, nullable: Delivery latency at the 50th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `total_p95_ms` integer, nullable: Delivery latency at the 95th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `total_p99_ms` integer, nullable: Delivery latency at the 99th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists. - `period` EmailStatsQueryPeriod, required: Normalized half-open period. The response end is exclusive; replay the original inclusive request bounds when following cursors. - `from` string, date-time, required: Inclusive normalized start as a UTC instant. - `to` string, date-time, required: Exclusive normalized end as a UTC instant. - `timezone` string, required: Timezone used to normalize bounds and buckets. - `grain` 'quarter_hour' | 'hour' | 'half_day' | 'day' | 'week' | 'month', required: Time buckets in the requested timezone. Weeks start on Monday; months start on the first day. Half days start at midnight and noon. Edge buckets count events inside the normalized period. - `data_as_of` string, date-time, nullable, required: Always null for this endpoint. It does not report a refresh boundary, claim completeness, or record request time. - `next_cursor` string, nullable, required: Pass as starting_after for the next grouped page. Null when no next page exists or the request is ungrouped. - `prev_cursor` string, nullable, required: Pass as ending_before for the previous grouped page. Null when no previous page exists or the request is ungrouped. - `refresh_cursor` string, nullable, required: Anchor for the first group. Pass as ending_before to read groups sorting before it. Null for empty or ungrouped results. Ranking can change between reads; refresh by repeating the original query. ## Other responses - `400`: Bad request - `401`: Authentication required - `403`: Insufficient permissions - `404`: Resource not found - `409`: Resource conflict - `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. - `429`: Rate limit exceeded - `500`: Internal server error - `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation. --- [API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)