Metrics & analytics

Time-bucketed delivery and engagement counters, gap-filled and timezone-aware.

Three endpoints cover analytics: this page’s time series (GET /v3/metrics), the summary (GET /v3/metrics/summary — lifecycle counts, bounce classes, unique opens/clicks, latency percentiles, previous-period comparison), and the breakdown (GET /v3/metrics/breakdown — ranked tables across nine dimensions such as mailbox provider, country and template).

Time-bucketed sending statistics for your account. Every bucket carries the full set of counters — sent, delivered, bounced, complained, opened, clicked, unsubscribed, delayed, rejected and failed — so one call powers a whole dashboard. For window totals with rates and latency percentiles use GET /v3/metrics/summary; for ranked tables per domain, tag, provider and more use GET /v3/metrics/breakdown.

GET /v3/metrics

Query parameters

Parameter	Type	Required	Description
`since`	ISO-8601	Optional	Window start — ISO 8601 instant or calendar day (YYYY-MM-DD = that day’s 00:00 in `timezone`). Default: 30 days ago.
`until`	ISO-8601	Optional	Window end — ISO 8601 instant or calendar day (YYYY-MM-DD = end of that day in `timezone`, inclusive). Default: now.
`resolution`	string	Optional	Bucket size: `hour`, `day`, `week` or `month`. Default `day`. Window caps: 31 days at `hour`, 366 days at `day`.
`timezone`	string	Optional	IANA timezone the buckets are computed in (e.g. `Europe/Athens`). Default `UTC`.
`group_by`	string	Optional	`domain` (sending domain) or `status` (event type). Adds a `groups` array of per-key bucket series alongside the overall totals.
`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

Returns { data, resolution, timezone, period: { since, until }, group_by, groups? } where data is an array of buckets: { timestamp, sent, delivered, bounced, complained, opened, clicked, unsubscribed, delayed, rejected, failed } and groups (present when group_by is set) contains { key, data } series per sending domain or event type. The main series is gap-filled — every bucket in the window is present, zeroed when idle — so it charts directly with no client-side filling. Group series are sparse.

Responses

Status	Description
`200`	OK. Gap-filled, time-bucketed counts with the `resolution`, `timezone`, `period` and any `group_by`.
`400`	Invalid query parameters (unknown timezone, `since` after `until`, window too large for the resolution).
`401`	Missing or invalid API key.

Code examples

cURL

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

Node.js

const res = await fetch("https://api.wemail.io/v3/metrics", {
  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",
    headers={"Authorization": f"Bearer {os.environ['WEMAIL_API_KEY']}"},
)
data = r.json()