JSON API & MCP access to your delivery data.

cURL — overview

curl -s "https://bigstats.email/api/public/v1/overview?range=7d" \
  -H "Authorization: Bearer $BIGSTATS_TOKEN"

cURL — bounce CSV export

curl -s "https://bigstats.email/api/public/v1/events?event_type=bounced&range=7d&format=csv&limit=5000" \
  -H "Authorization: Bearer $BIGSTATS_TOKEN" -o bounces.csv

cURL — shared pool diagnosis

# Which senders share 203.0.113.42, and how is each one doing?
curl -s "https://bigstats.email/api/public/v1/pool-detail?mode=ip&key=203.0.113.42&range=30d&compare=true" \
  -H "Authorization: Bearer $BIGSTATS_TOKEN"

# Where is that IP struggling, by ISP group?
curl -s "https://bigstats.email/api/public/v1/pool-domains?mode=ip&key=203.0.113.42&group_by=isp&range=30d" \
  -H "Authorization: Bearer $BIGSTATS_TOKEN"

JavaScript / TypeScript

const res = await fetch(
  "https://bigstats.email/api/public/v1/domains?range=30d&group_by=isp",
  { headers: { Authorization: `Bearer ${process.env.BIGSTATS_TOKEN}` } },
);
if (!res.ok) throw new Error(`BigStats API ${res.status}`);
const { rows } = await res.json();

for (const r of rows) {
  console.log(r.bucket, r.delivered, r.bounced);
}

Python

import os, requests

r = requests.get(
    "https://bigstats.email/api/public/v1/events",
    params={"event_type": "bounced", "limit": 1000},
    headers={"Authorization": f"Bearer {os.environ['BIGSTATS_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
for e in r.json()["events"]:
    print(e["occurred_at"], e["smtp_code"], e["bounce_category"], e["diagnostic"])

Example response — /overview

{
  "range": "7d",
  "from": "2026-07-28T19:00:00.000Z",
  "to": "2026-08-04T19:00:00.000Z",
  "totals": {
    "injected": 41293811, "delivered": 40510442, "deferred": 612004,
    "bounced": 402118, "opened": 9120344, "clicked": 1044219, "complained": 3122
  },
  "previous": { "delivered": 38911204, "bounced": 448190 },
  "series": [{ "bucket": "2026-07-28", "delivered": 5712001, "bounced": 61224 }]
}

Request

POST /api/public/ingest/kumomta?key=ga_live_…
Content-Type: application/json
# the key may also be sent as the header: x-bigstats-key: ga_live_…

# a single record …
{ "type": "Delivery", "recipient": "jordan@gmail.com", "timestamp": 1785000012 }

# … or a batch: a JSON array, newline-delimited JSON,
# or an object wrapper using "events", "records" or "logs"
{ "records": [
  { "type": "Reception", "recipient": "jordan@gmail.com", "timestamp": 1785000000 },
  { "type": "Delivery",  "recipient": "jordan@gmail.com", "timestamp": 1785000012 }
] }

Response

HTTP/1.1 200 OK
{ "ok": true, "received": 2 }

# failures
401 { "error": "missing ingest key" }      # no ?key= and no x-bigstats-key header
401 { "error": "invalid ingest key" }      # unknown or deactivated key
400 { "error": "no events found in payload" }
413 { "error": "too many events in one batch" }   # hard cap of 25,000 records per POST
500 { "error": "could not store events" }  # safe to retry; duplicates are dropped

MCP endpoint (Streamable HTTP)

https://bigstats.email/mcp

Client config (Claude Desktop / Cursor style)

{
  "mcpServers": {
    "bigstats": {
      "url": "https://bigstats.email/mcp"
    }
  }
}