bird email stats query

bird email stats query [flags]

Get selected email metrics

Select email metrics over a date or instant window, optionally grouped by one dimension with complete time series per group. Events are selected and bucketed by when they occurred, including activity on messages sent earlier. Filters match recorded event context. Unsupported combinations and unavailable history return 422. 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.

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

# the body it prints:

{
  "filters": {
    "tag": {
      "name": "campaign"
    }
  },
  "from": "2026-08-03",
  "grain": "quarter_hour",
  "group_by": "sending_domain",
  "metrics": ["sends_accepted"],
  "order": "asc",
  "sort": "sends_accepted",
  "timezone": "Europe/Amsterdam",
  "to": "2026-08-16"
}