{"openapi":"3.1.0","info":{"title":"InboxGrade API","version":"1.0.0","summary":"Email deliverability grades, blacklist status, auth results, and historical trends — public read-only API.","description":"Query InboxGrade deliverability reports programmatically. No authentication required for the read endpoints below. Rate limits: ~100 requests/minute per IP. 429 responses include a Retry-After header. Try it with the demo token: `curl https://inboxgrade.io/api/v1/report/demo`.","contact":{"name":"InboxGrade API","email":"api@inboxgrade.io","url":"https://inboxgrade.io/api-docs"},"license":{"name":"Public read-only — no license required for API consumption"}},"servers":[{"url":"https://inboxgrade.io/api/v1","description":"Production"}],"paths":{"/report/{token}":{"get":{"operationId":"getReport","summary":"Fetch a single deliverability report by token","description":"Returns the full report payload for a given token. Use `demo` to get a hand-curated A- grade sample without running a real test. Tokens expire 30 days after the test is received.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]{6,12}$|^demo$"},"description":"The 6-12 character report token, or the literal string `demo`.","example":"demo"}],"responses":{"200":{"description":"Report found. `status` is `ready` or `pending`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"Invalid token format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Token not found. `status` is `not-found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}},"429":{"description":"Rate limit exceeded. Response includes a `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history/{ip}":{"get":{"operationId":"getHistoryByIp","summary":"All reports from a given sending IP, newest first","description":"Returns up to 100 recent reports for a sending IP address, plus a `trend` array suitable for charting.","parameters":[{"name":"ip","in":"path","required":true,"schema":{"type":"string"},"description":"IPv4 or IPv6 address.","example":"209.85.221.47"}],"responses":{"200":{"description":"History fetched successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/History"}}}},"400":{"description":"Invalid IP format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leaderboard":{"get":{"operationId":"getLeaderboard","summary":"Top sender domains ranked by average deliverability score","description":"Rolling-window leaderboard of sender domains, scored by average report grade.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":7},"description":"Window size in days (default 7, max 30)."},{"name":"min","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":1},"description":"Minimum test count per domain to qualify."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows returned (default 25, max 100)."}],"responses":{"200":{"description":"Leaderboard fetched successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Leaderboard"}}}}}}}},"components":{"schemas":{"Report":{"type":"object","properties":{"status":{"type":"string","enum":["ready","pending"],"example":"ready"},"token":{"type":"string","example":"demo"},"receivedAt":{"type":"string","format":"date-time","example":"2026-10-15T14:29:48.000Z"},"from":{"type":"string","example":"newsletter@acme.example"},"fromDomain":{"type":"string","example":"acme.example"},"senderIp":{"type":"string","example":"209.85.221.47"},"subject":{"type":"string","example":"Welcome to Acme — your account is ready"},"grade":{"type":"string","example":"A-","description":"A-F letter grade with optional +/- modifier."},"score":{"type":"number","example":92.5,"description":"Numeric score 0-100."},"checks":{"type":"object","properties":{"spf":{"type":"object","description":"SPF authentication result — `result`, `sender`, `mechanism`, `record`."},"dkim":{"type":"object","description":"DKIM result — `overallResult` plus per-signature `signatures[]`."},"dmarc":{"type":"object","description":"DMARC result — alignment, policy, record, fromDomain."},"blacklists":{"type":"array","description":"Each major RBL checked — `{name, listed, url}`."},"spam":{"type":"object","description":"SpamAssassin — `score`, `status`, `rules[]`."},"tls":{"type":"object","description":"TLS version + cipher negotiated by inbound MX."},"ptr":{"type":"object","description":"PTR / reverse DNS verdict + forward-confirmation."},"listUnsubscribe":{"type":"object","description":"List-Unsubscribe header presence + one-click (RFC 8058)."},"urls":{"type":"object","description":"Link analysis — shortener count, redirect mismatches, top domains."},"arc":{"type":"object","description":"ARC chain preservation across forwarding hops."},"spfAudit":{"type":"object","description":"SPF 10-lookup-limit audit + mechanism tree."},"mtaSts":{"type":"object","description":"MTA-STS policy mode + TLS-RPT setup."},"bimi":{"type":"object","description":"BIMI record + VMC presence."}}},"deliveryPath":{"type":"array","description":"Received-header chain, parsed into hops with timestamps + TLS versions.","items":{"type":"object"}},"reportUrl":{"type":"string","example":"https://inboxgrade.io/r/demo"}}},"History":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"ip":{"type":"string"},"count":{"type":"integer"},"tests":{"type":"array","items":{"type":"object","properties":{"token":{"type":"string"},"grade":{"type":"string"},"score":{"type":"number"},"receivedAt":{"type":"string"},"fromDomain":{"type":"string"},"reportUrl":{"type":"string"}}}},"trend":{"type":"array","items":{"type":"object","properties":{"score":{"type":"number"},"at":{"type":"string"}}}}}},"Leaderboard":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"windowDays":{"type":"integer","example":7},"minTests":{"type":"integer","example":1},"count":{"type":"integer"},"leaderboard":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"domain":{"type":"string","example":"acme.example"},"testCount":{"type":"integer"},"avgScore":{"type":"number"},"bestScore":{"type":"number"},"worstScore":{"type":"number"}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string","example":"invalid token format"}}},"NotFound":{"type":"object","properties":{"status":{"type":"string","example":"not-found"},"token":{"type":"string"}}}}},"x-rate-limit":{"requestsPerMinute":100,"scope":"per-IP","response":"429 with Retry-After header"},"x-contact":{"programmaticTestCreation":{"description":"POST /api/v1/tests requires an API key — email api@inboxgrade.io for a sandbox key within 24h.","email":"api@inboxgrade.io"}}}