Metrics summary

One aggregate for the window: counts, rates, bounce classes, unique opens and latency percentiles.

A single aggregate object over the window — lifecycle counts with derived rates, hard/soft bounce classification, engagement including unique opens and clicks, and p50/p95/p99 latency for processing, delivery and total time. Add compare=previous_period to get the immediately preceding window plus deltas, ready for "vs last period" tiles.

GET /v3/metrics/summary

Query parameters

Parameter	Type	Required	Description
`since`	ISO-8601	Optional	Window start. Default: 30 days ago. Window may not exceed 366 days.
`until`	ISO-8601	Optional	Window end — ISO 8601 instant or calendar day (YYYY-MM-DD = end of that day in `timezone`, inclusive). Default: now.
`timezone`	string	Optional	IANA timezone, echoed back (e.g. `Europe/Athens`). Default `UTC`.
`compare`	string	Optional	`previous_period` — include a `comparison` object: the preceding window of equal length plus a `delta` of percentage changes and rate percentage-point differences.
`domain`	string	Optional	Only count events whose message was sent from this domain.
`recipient_domain`	string	Optional	Only count events for recipients at this mailbox domain.
`tag`	string	Optional	Only count events carrying this tag (event or parent message).
`template`	string	Optional	Only count events whose message used this template ID.

Response

delivery carries sent, delivered, bounced (with a bounces breakdown: hard, soft, suppressed, undetermined and per-class rates), complained, delayed, rejected, failed, plus delivery_rate, bounce_rate and complaint_rate (0–1 fractions of sent, null when nothing was sent). engagement carries opens, opens_direct (fetched by the recipient client rather than an image proxy), unique_opens/unique_clicks (distinct message + recipient pairs), clicks, unsubscribes and rates over delivered. latency carries p50_ms/p95_ms/p99_ms for processing (accepted → handed to the outbound MTA), delivery (MTA → recipient MX accept) and total.

Responses

Status	Description
`200`	OK. `{ period, delivery, engagement, latency, timezone, comparison? }`.
`400`	Invalid query parameters (unknown timezone, `since` after `until`, window over 366 days).
`401`	Missing or invalid API key.

Code examples

cURL

# Window summary with previous-period comparison
curl -G https://api.wemail.io/v3/metrics/summary \
  -H "Authorization: Bearer afn_live_…" \
  --data-urlencode "timezone=Europe/Athens" \
  --data-urlencode "compare=previous_period"

# Which mailbox provider is bouncing us?
curl -G https://api.wemail.io/v3/metrics/breakdown \
  -H "Authorization: Bearer afn_live_…" \
  --data-urlencode "dimension=mailbox_provider" \
  --data-urlencode "sort=bounced" \
  --data-urlencode "include_trend=true"

Node.js

const summary = await wemail.metrics.summary({
  timezone: "Europe/Athens",
  compare: "previous_period",
});
console.log(summary.delivery.delivery_rate, summary.comparison.delta.delivery_rate_pp);

const providers = await wemail.metrics.breakdown({
  dimension: "mailbox_provider",
  sort: "bounced",
});
for (const row of providers.data) console.log(row.key, row.bounce_rate);

Python

summary = wemail.metrics.summary(timezone="Europe/Athens", compare="previous_period")
providers = wemail.metrics.breakdown(dimension="mailbox_provider", sort="bounced")

PHP

$summary = $wemail->metrics->summary(['compare' => 'previous_period']);
$providers = $wemail->metrics->breakdown(['dimension' => 'mailbox_provider', 'sort' => 'bounced']);

Ruby

summary = wemail.metrics.summary(compare: "previous_period")
providers = wemail.metrics.breakdown(dimension: "mailbox_provider", sort: "bounced")

summary, _ := client.Metrics.Summary(ctx, &wemail.MetricsSummaryParams{Compare: "previous_period"})
providers, _ := client.Metrics.Breakdown(ctx, &wemail.MetricsBreakdownParams{Dimension: "mailbox_provider", Sort: "bounced"})

Java

wemail.metrics().summary(MetricsSummaryParams.builder().compare("previous_period").build());
wemail.metrics().breakdown(MetricsBreakdownParams.builder().dimension("mailbox_provider").sort("bounced").build());

.NET

var summary = await wemail.Metrics.SummaryAsync(new MetricsSummaryParams { Compare = "previous_period" });
var providers = await wemail.Metrics.BreakdownAsync(new MetricsBreakdownParams { Dimension = "mailbox_provider", Sort = "bounced" });