email-stats

Query email delivery and engagement metrics

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.

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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

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.

X-Organization-Idstring

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.

Request body

fromstring 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.

tostring 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.

timezonestring

IANA timezone for dates and bucket boundaries. Defaults to UTC.

metricsEmailStatsQueryMetric[] 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.

filtersEmailStatsQueryFilters (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.

limitinteger

Grouped requests only. Maximum groups per page; defaults to 25. Each group retains its complete series.

starting_afterstring

Grouped requests only. Opaque next_cursor from the previous response. Mutually exclusive with ending_before.

ending_beforestring

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

Selected metrics, normalized bounds, and grouped navigation cursors.

data_as_ofstring date-time nullable required

Always null for this endpoint. It does not report a refresh boundary, claim completeness, or record request time.

next_cursorstring nullable required

Pass as starting_after for the next grouped page. Null when no next page exists or the request is ungrouped.

prev_cursorstring nullable required

Pass as ending_before for the previous grouped page. Null when no previous page exists or the request is ungrouped.

refresh_cursorstring 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.

Example response

{
  "data": [
    {
      "dimensions": {
        "template_id": "emt_01krdgeqcxet5s7t44vh8rt9mg",
        "ip_pool_id": "ipp_01krdgeqcxet5s7t44vh8rt9mg",
        "broadcast_id": "eb_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.