InboxGrade API

GET /api/v1/report/{token}

Fetch a single deliverability report by token.

$ curl https://inboxgrade.io/api/v1/report/4059d72c51

{
  "status": "ready",
  "token": "4059d72c51",
  "receivedAt": "2026-10-12T15:29:48.000Z",
  "from": "newsletter@acme.example",
  "fromDomain": "acme.example",
  "senderIp": "209.85.221.47",
  "grade": "A",
  "score": 100.0,
  "checks": {
    "spf": { ... },
    "dkim": { ... },
    "dmarc": { ... },
    "blacklists": [ ... ],
    "spam": { ... },
    "tls": { ... },
    "ptr": { ... },
    "listUnsubscribe": { ... },
    "urls": { ... },
    "arc": { ... },
    "spfAudit": { ... },
    "mtaSts": { ... },
    "bimi": { ... }
  },
  "deliveryPath": [ ... ],
  "reportUrl": "https://inboxgrade.io/r/4059d72c51"
}

Returns 404 for unknown tokens, 200 with status: "pending" if the test hasn't been received yet.

GET /api/v1/history/{ip}

All reports from a given sending IP, newest first. Capped at 100 rows.

$ curl https://inboxgrade.io/api/v1/history/209.85.221.47

{
  "status": "ok",
  "ip": "209.85.221.47",
  "count": 3,
  "tests": [
    { "token": "4059d72c51", "grade": "A", "score": 100.0, "receivedAt": "...", "fromDomain": "acme.example", "reportUrl": "..." },
    ...
  ],
  "trend": [ { "score": 100.0, "at": "..." } ]
}

GET /api/v1/leaderboard

Top sender domains in the last 7 days. Query params:

• days — rolling window (default 7, max 30)
• min — minimum test count per domain (default 1, max 100)
• limit — rows returned (default 25, max 100)

$ curl 'https://inboxgrade.io/api/v1/leaderboard?days=30&min=3&limit=10'

{
  "status": "ok",
  "windowDays": 30,
  "minTests": 3,
  "count": 10,
  "leaderboard": [
    { "rank": 1, "domain": "acme.example", "testCount": 5, "avgScore": 98.4, "bestScore": 100.0, "worstScore": 94.0 },
    ...
  ]
}

Programmatic test creation

The read endpoints above are for post-hoc lookup. You probably want to mint tests from code — that's how you wire this into CI, monitoring, or a dashboard.

Email api@inboxgrade.io with your use case and you'll get a sandbox key within 24h.

The endpoint is POST /api/v1/tests. Full docs ship with the first key.

Rate limits + fair use

• Shared quota per Vercel platform (currently generous).
• Expect 429 Too Many Requests if you hammer. Back off exponentially.
• Reports are cached 60s, history 120s, leaderboard 300s at the edge.
• Please attribute: "deliverability grade by inboxgrade.io" if you re-publish scores.