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

SNS HTTPS subscription endpoint

https://bigstats.email/api/public/ingest/ses?key=<INGEST_KEY>

Request

curl -X POST https://bigstats.email/api/public/ingest/signalmta \
  -H "Content-Type: application/json" \
  -H "X-BigStats-Key: <INGEST_KEY>" \
  -d @envelope.json

SignalMTA delivered → delivered

{
  "id": "evt_delivered_0001",
  "type": "delivered",
  "createdAt": "2026-09-28T15:04:05Z",
  "endpoint": "ep_bigstats",
  "observability": {
    "tenant": "brand-a",
    "stream": "newsletter-sept"
  },
  "data": {
    "messageId": "<msg-0001@brand.example.com>",
    "rcptTo": [
      "test.user@gmail.com"
    ],
    "route": {
      "tenant": "brand-a",
      "stream": "newsletter-sept",
      "pool": "pool-marketing",
      "sendingIp": "203.0.113.42"
    },
    "remoteMta": "gmail-smtp-in.l.google.com",
    "smtpCode": 250,
    "response": "250 2.0.0 OK"
  }
}

SignalMTA deferred → deferred

{
  "id": "evt_deferred_0001",
  "type": "deferred",
  "createdAt": "2026-09-28T15:04:05Z",
  "endpoint": "ep_bigstats",
  "observability": {
    "tenant": "brand-a",
    "stream": "newsletter-sept"
  },
  "data": {
    "messageId": "<msg-0001@brand.example.com>",
    "rcptTo": [
      "test.user@gmail.com"
    ],
    "route": {
      "tenant": "brand-a",
      "stream": "newsletter-sept",
      "pool": "pool-marketing",
      "sendingIp": "203.0.113.42"
    },
    "smtpCode": 421,
    "enhancedStatus": "4.7.0",
    "response": "421 4.7.0 Try again later"
  }
}

SignalMTA bounced → bounced

{
  "id": "evt_bounced_0001",
  "type": "bounced",
  "createdAt": "2026-09-28T15:04:05Z",
  "endpoint": "ep_bigstats",
  "observability": {
    "tenant": "brand-a",
    "stream": "newsletter-sept"
  },
  "data": {
    "messageId": "<msg-0001@brand.example.com>",
    "rcptTo": [
      "test.user@gmail.com"
    ],
    "route": {
      "tenant": "brand-a",
      "stream": "newsletter-sept",
      "pool": "pool-marketing",
      "sendingIp": "203.0.113.42"
    },
    "smtpCode": 550,
    "enhancedStatus": "5.1.1",
    "classification": "bad-mailbox",
    "response": "550 5.1.1 The email account that you tried to reach does not exist."
  }
}

SignalMTA complaint → complained

{
  "id": "evt_complaint_0001",
  "type": "complaint",
  "createdAt": "2026-09-28T15:04:05Z",
  "endpoint": "ep_bigstats",
  "observability": {
    "tenant": "brand-a",
    "stream": "newsletter-sept"
  },
  "data": {
    "messageId": "<msg-0001@brand.example.com>",
    "rcptTo": [
      "test.user@gmail.com"
    ],
    "route": {
      "tenant": "brand-a",
      "stream": "newsletter-sept",
      "pool": "pool-marketing",
      "sendingIp": "203.0.113.42"
    },
    "category": "abuse"
  }
}

SignalMTA suppressed → rejected

{
  "id": "evt_suppressed_0001",
  "type": "suppressed",
  "createdAt": "2026-09-28T15:04:05Z",
  "endpoint": "ep_bigstats",
  "observability": {
    "tenant": "brand-a",
    "stream": "newsletter-sept"
  },
  "data": {
    "messageId": "<msg-0001@brand.example.com>",
    "rcptTo": [
      "test.user@gmail.com"
    ],
    "route": {
      "tenant": "brand-a",
      "stream": "newsletter-sept",
      "pool": "pool-marketing",
      "sendingIp": "203.0.113.42"
    },
    "explanation": "Recipient on suppression list"
  }
}

MCP endpoint (Streamable HTTP)

https://bigstats.email/mcp

Client config (Claude Desktop / Cursor style)

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