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.
Afficher les paramètres enfants
filters.sending_domainMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.categoryMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.template_idMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.tagSelect one case-sensitive tag name. A name without values requires that tag to exist. Exclude-only predicates retain events without that tag. Include and exclude together accept at most 20 distinct normalized values with no overlap.
filters.recipient_domainMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.mailbox_providerMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.mailbox_provider_regionMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.sending_ipMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.ip_pool_idMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.broadcast_idMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.countryMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.regionMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
Afficher les paramètres enfants
filters.region.includefilters.region.excludefilters.cityMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.agent_familyMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.os_familyMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.device_familyMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.smtp_error_codeMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
filters.feedback_typeMatch recorded values using include or exclude. Include values combine with OR; exclusions remove matches. Missing values survive exclude-only predicates. Supply a nonempty array; at most 20 distinct values across both arrays are accepted after normalization, with no overlap.
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
dataperiodNormalized 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.