Metrics breakdown

Ranked metric tables by domain, mailbox provider, tag, template, bounce code and more.

Answers "which domain / provider / tag is dragging my numbers down?" in one call: a ranked table of delivery and engagement metrics for any supported dimension, with per-row rates and an optional per-day trend series for sparklines.

GET /v3/metrics/breakdown

Query parameters

Parameter	Type	Required	Description
`dimension`	string	Required	`sending_domain`, `recipient_domain`, `mailbox_provider` (Gmail, Microsoft, Yahoo…), `tag`, `template`, `bounce_code` (provider bounce type/subtype), `complaint_type`, `country` (engagement geo) or `client` (email client family).
`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 for the trend day-buckets. Default `UTC`.
`sort`	string	Optional	Metric to rank by: `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked`, `unique_opens`, `unique_clicks` or `failed`. Default depends on the dimension (e.g. `bounced` for `bounce_code`).
`limit`	integer	Optional	Rows to return, 1–200. Default 50.
`include_trend`	boolean	Optional	`true` adds a per-day `trend` series of the sort metric to every row — ready for sparklines. Default `false`.

Response

Returns { dimension, period, timezone, sort, total, data } where total is the count of distinct dimension values in the window (before limit) and each row carries key, label (template name or country name where the key is an ID/code), the full counter set including unique_opens/unique_clicks, per-row delivery_rate, bounce_rate, complaint_rate, open_rate and click_rate, and trend when requested.

The trend series (include_trend)

With include_trend=true, every row gains a trend array — one { timestamp, value } entry per day in the window, where value is that day’s count of the `sort` metric only (not the whole counter set, which keeps the payload small). Days are bucketed in the timezone you pass and timestamp is each day’s start (ISO 8601). It’s built for a per-row sparkline: the ranked table shows *who* is worst right now, and the trend shows *whether it’s getting worse*. For example, dimension=mailbox_provider&sort=bounced&include_trend=true returns each provider’s daily bounce count, so a provider ramping up blocks stands out at a glance. Omit it (default false) when you only need the totals — the response is smaller and faster.

jsonOne row with include_trend=true

{
  "key": "google.com",
  "label": "Gmail",
  "sent": 4210,
  "delivered": 4158,
  "bounced": 39,
  "bounce_rate": 0.00926,
  "trend": [
    { "timestamp": "2026-08-27T00:00:00.000Z", "value": 6 },
    { "timestamp": "2026-08-28T00:00:00.000Z", "value": 19 },
    { "timestamp": "2026-08-29T00:00:00.000Z", "value": 14 }
  ]
}

Responses

Status	Description
`200`	OK. Ranked rows for the dimension with counts, rates and optional `trend`.
`400`	Invalid query parameters (unknown dimension or sort metric, window over 366 days).
`401`	Missing or invalid API key.

Code examples

cURL

curl https://api.wemail.io/v3/metrics/breakdown \
  -H "Authorization: Bearer afn_live_…"

Node.js

const res = await fetch("https://api.wemail.io/v3/metrics/breakdown", {
  headers: {
    Authorization: `Bearer ${process.env.WEMAIL_API_KEY}`,
  },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.wemail.io/v3/metrics/breakdown",
    headers={"Authorization": f"Bearer {os.environ['WEMAIL_API_KEY']}"},
)
data = r.json()