bird email stats query

Usage

bird email stats query [flags]

Description

Query email delivery and engagement metrics

Query email analytics and stats for marketing and transactional delivery, bounces, opens, clicks, engagement rates, and latency percentiles. Use for comparisons, combined filters, ranked groups by template, campaign tag, recipient domain, or mailbox provider, and complete time series. If the tag name and requested values are supplied, call this tool directly with filters.tag; no tag lookup is needed. Use bird email stats by-tag only to discover unknown tags. Select grain=quarter_hour for 15-minute activity; omit group_by for a summary. Check group_by and filter compatibility before calling. Country, region, city, and device/client dimensions support engagement counts only: do not request delivered or open_rate for them. Explain an unsupported combination before offering a different report. Every selected metric must support every grouping and filter dimension. Campaigns may use tags or broadcasts; templates can span campaigns. Establish activity from period-scoped stats, not resource creation dates. Use category for recorded marketing/transactional classification and resolve template names to IDs. Event-time windows include engagement on earlier sends; they cannot select a send-date cohort or establish send batches. Compare periods independently with the same filters and metrics. Use bird email stats summary for a supported single-filter aggregate with built-in comparison. Use returned period metrics; distinct counts need not add up across buckets or groups. Read metric descriptions for rate denominators and eligible latency samples. Engagement cannot establish a human count; latency percentiles cannot establish maxima or exact threshold counts. Delivery describes mail-server acceptance. Inbox placement, reading time, revenue, and conversion attribution require other evidence; this limitation concerns email stats, not the whole platform. Unsupported combinations and unavailable history return 422; explain a limitation before changing the population or period. Follow cursors by replaying the original body and changing its cursor fields; the response period has an exclusive end and must not replace the request end. Use a new idempotency key for each continuation page; reuse a key only to retry the same page.

Build the request from flags, a JSON EmailStatsQueryRequest body via --body-file ("-" reads stdin), or both — a flag overrides the matching body field. Run --example to print a ready-to-edit body, or --dry-run to print the resolved request without sending it.

Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after.

Procedure

Step 2 of 2 of "Analyze email performance". Previous: bird email stats by-tag.

Examples

# print the body shape (no credentials needed)
bird email stats query --example

# the body it prints:

{
  "from": "2026-09-23",
  "grain": "week",
  "group_by": "recipient_domain",
  "limit": 25,
  "metrics": ["delivered", "bounce_rate"],
  "to": "2026-09-24"
}

Options

Filters

Pagination

Request

Related