Query email delivery and engagement metrics
/v1/email/stats/queryconst { data } = await bird.email.stats.query({
from: "2026-09-23",
to: "2026-09-24",
metrics: ["delivered", "bounce_rate"],
group_by: "recipient_domain",
grain: "week",
limit: 25,
});
for (const group of data) {
console.log(group.dimensions, group.metrics, group.series);
}stats = client.email.stats.query(
from_="2026-09-23",
to="2026-09-24",
metrics=["delivered", "bounce_rate"],
group_by="recipient_domain",
grain="week",
limit=25,
)
for group in stats.data:
print(group.dimensions, group.metrics, group.series)stats, err := client.Email.Stats.QueryPage(context.Background(), bird.EmailStatsQueryParams{
From: "2026-09-23",
To: "2026-09-24",
Metrics: []bird.EmailStatsQueryMetric{"delivered", "bounce_rate"},
GroupBy: bird.Ptr(bird.EmailStatsQueryDimension("recipient_domain")),
Grain: bird.Ptr(bird.EmailStatsQueryGrain("week")),
Limit: bird.Ptr(25),
}, "")
if err != nil {
log.Fatal(err)
}
for _, group := range stats.Data {
fmt.Println(group.Dimensions, group.Metrics, group.Series)
}$params = (new \MessageBird\Wire\Model\EmailStatsQueryRequest())
->setFrom('2026-09-23')
->setTo('2026-09-24')
->setMetrics(['delivered', 'bounce_rate'])
->setGroupBy('recipient_domain')
->setGrain('week')
->setLimit(25);
$stats = $bird->email->stats->query($params)->fetch();
foreach ($stats->data as $group) {
print_r([$group->getDimensions(), $group->getMetrics(), $group->getSeries()]);
}bird email stats query \
--from 2026-09-23 \
--grain week \
--group-by recipient_domain \
--limit 25 \
--metrics delivered \
--metrics bounce_rate \
--to 2026-09-24curl -X POST "https://us1.platform.bird.com/v1/email/stats/query" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": "2026-09-23",
"to": "2026-09-24",
"metrics": [
"delivered",
"bounce_rate"
],
"group_by": "recipient_domain",
"grain": "week",
"limit": 25
}'{
"data": [
{
"dimensions": {
"recipient_domain": "gmail.com"
},
"metrics": {
"delivered": 12,
"bounce_rate": 0.2
},
"series": [
{
"bucket": "2026-09-21T00:00:00Z",
"metrics": {
"delivered": 12,
"bounce_rate": 0.2
}
}
]
}
],
"period": {
"from": "2026-09-23T00:00:00Z",
"to": "2026-09-25T00:00:00Z",
"timezone": "UTC",
"grain": "week"
},
"data_as_of": null,
"next_cursor": null,
"prev_cursor": null,
"refresh_cursor": "eyJ2IjoxLCJ3b3Jrc3BhY2UiOiJ3c18wMTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInF1ZXJ5IjoiYjM3MDNiMWVmNDNkZjExZDNlYzcwMGY2MmViNTdlZGIwYjAzODI4Yzk5ZTkxYzY4MzJhYWNjYTIwMzZhNDc3MSIsIm51bGwiOmZhbHNlLCJpbnRlZ2VyIjoxMiwia2V5IjoiZ21haWwuY29tIn0"
}
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.
Corps de la requête
fromInclusive 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.
toInclusive 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.
timezoneIANA timezone for dates and bucket boundaries. Defaults to UTC.
metricsDistinct 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_byGroup 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 exceptsends_accepted.mailbox_provider,mailbox_provider_region: all metrics exceptsends_accepted,accepted, andrejected.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, andtotal_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, andconfirmed_unique_opens_non_prefetched.smtp_error_code:bounced,hard_bounced,soft_bounced,admin_bounced,block_bounced, andundetermined_bounced.feedback_type:complained.
Possible values: 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
grainTime 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.
Possible values: quarter_hour, hour, half_day, day, week, month
filtersFilter recorded event context with include/exclude predicates. Include values combine with OR; dimensions combine with AND. Exclude-only predicates retain missing values. Tag filters require one case-sensitive name; a name without values requires presence. Each predicate accepts at most 20 distinct values across include and exclude. Every selected metric must support every filter dimension, using the same compatibility rules as group_by. Resolve template and IP-pool names to IDs before filtering. Broadcast filters use IDs. Current names do not establish historical attribution.
sortGrouped requests only. Rank groups by this selected metric; defaults to the first metrics entry. Undefined values sort last in either direction. Ties use the dimension value ascending, with null last.
Possible values: 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
orderGrouped requests only. Defaults to desc.
Possible values: asc, desc
limitGrouped requests only. Maximum groups per page; defaults to 25. Each group retains its complete series.
starting_afterGrouped requests only. Opaque next_cursor from the previous response. Mutually exclusive with ending_before.
ending_beforeGrouped 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.
Contenu de la réponse
dataAfficher les attributs enfants
data.dimensionsContains the requested group_by property, including a null value when context is missing. Ungrouped results use an empty object.
data.metricsSelected 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.
data.seriesPresent when grain is requested; absent otherwise.
Afficher les attributs enfants
data.series.bucketNominal bucket start as a UTC RFC 3339 instant.
data.series.metricsSelected 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.
Afficher les attributs enfants
data.series.metrics.sends_acceptedDistinct sends accepted by Bird, counted by email identity.
data.series.metrics.acceptedDistinct message recipients accepted by Bird.
data.series.metrics.processedDistinct message recipients processed for delivery.
data.series.metrics.deliveredDistinct message recipients with a delivery event.
data.series.metrics.bouncedDistinct message recipients with bounced events.
data.series.metrics.hard_bouncedDistinct message recipients with hard bounced events.
data.series.metrics.soft_bouncedDistinct message recipients with soft bounced events.
data.series.metrics.admin_bouncedDistinct message recipients with admin bounced events.
data.series.metrics.block_bouncedDistinct message recipients with block bounced events.
data.series.metrics.undetermined_bouncedDistinct message recipients with undetermined bounced events.
data.series.metrics.complainedDistinct message recipients with complained events.
data.series.metrics.deferredDistinct message recipients with a deferral event.
data.series.metrics.rejectedDistinct message recipients rejected before provider delivery.
data.series.metrics.oob_bouncesDistinct out-of-band bounce events.
data.series.metrics.opensDistinct open events, including prefetched opens.
data.series.metrics.opens_non_prefetchedDistinct open events excluding prefetched opens. An absent prefetch flag counts as false.
data.series.metrics.clicksDistinct click events.
data.series.metrics.unsubscribesDistinct unsubscribe events.
data.series.metrics.unique_opensDistinct message recipients with an open event.
data.series.metrics.unique_opens_non_prefetchedDistinct message recipients with a non-prefetched open event.
data.series.metrics.unique_clicksDistinct message recipients with a click event.
data.series.metrics.confirmed_unique_opensDistinct message recipients with an open or click event, deduplicated across both.
data.series.metrics.confirmed_unique_opens_non_prefetchedDistinct message recipients with a non-prefetched open or click event, deduplicated across both.
data.series.metrics.effective_deliveredDelivered recipients less out-of-band bounce events, calculated as max(delivered - oob_bounces, 0).
data.series.metrics.all_bouncesIn-band bounced recipients plus out-of-band bounce events, calculated as bounced + oob_bounces.
data.series.metrics.delivery_rateRatio of effective_delivered / (delivered + bounced), from 0 to 1. Null when delivered + bounced is zero.
data.series.metrics.bounce_rateRatio of all_bounces / (delivered + bounced), capped at 1. Null when delivered + bounced is zero.
data.series.metrics.complaint_rateRatio of complained / effective_delivered. Uncapped and can exceed 1 when complaints and deliveries fall in different windows. Null when effective_delivered is zero.
data.series.metrics.deferral_rateRatio of deferred / (delivered + bounced), capped at 1. Null when delivered + bounced is zero.
data.series.metrics.open_rateRatio 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.
data.series.metrics.click_rateRatio of unique_clicks / effective_delivered. Uncapped and can exceed 1 when clicks and deliveries fall in different windows. Null when effective_delivered is zero.
data.series.metrics.unsubscribe_rateRatio of unsubscribes / effective_delivered, using distinct unsubscribe events as the numerator. Uncapped and can exceed 1. Null when effective_delivered is zero.
data.series.metrics.oob_rateRatio 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.
data.series.metrics.processing_p50_msProcessing latency at the 50th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists.
data.series.metrics.processing_p95_msProcessing latency at the 95th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists.
data.series.metrics.processing_p99_msProcessing latency at the 99th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists.
data.series.metrics.total_p50_msDelivery latency at the 50th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists.
data.series.metrics.total_p95_msDelivery latency at the 95th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists.
data.series.metrics.total_p99_msDelivery latency at the 99th percentile, in integer milliseconds from Bird acceptance. One sample per logical event; null when no eligible sample exists.
periodNormalized half-open period. The response end is exclusive; replay the original inclusive request bounds when following cursors.
data_as_ofAlways null for this endpoint. It does not report a refresh boundary, claim completeness, or record request time.
next_cursorPass as starting_after for the next grouped page. Null when no next page exists or the request is ungrouped.
prev_cursorPass as ending_before for the previous grouped page. Null when no previous page exists or the request is ungrouped.
refresh_cursorAnchor 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.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.