IP Blacklist Check API — /api/v1/security/blacklist

Streams each blacklist verdict as an SSE event. Useful for diagnosing email deliverability and reputation issues.

• Method GET
• Path /api/v1/security/blacklist
• Stability STABLE
• Version v2026-05-15
• Summary Check an IP against 30+ public DNSBL / RBL databases (SSE).

Pass these as query-string parameters (or, where indicated, in the request headers). Required params marked required.

• ip (required) — string IPv4 or IPv6 address.
• count — integer, default 10 Max number of RBLs to query (1–20).

All successful responses follow the standard `{ success: true, data: {...} }` envelope. Notable fields on the data object for this endpoint:

• event: result — SSE Per-RBL verdict. `data: {rbl, listed, response, lookupMs}`.
• event: done — SSE Final summary. `data: {checked, listed}`.

Truncated but representative example for a real lookup:

{
  "stream": [
    "event: result\ndata: {\"rbl\": \"zen.spamhaus.org\", \"listed\": false, \"lookupMs\": 18}\n\n",
    "event: result\ndata: {\"rbl\": \"bl.spamcop.net\", \"listed\": false, \"lookupMs\": 24}\n\n",
    "event: done\ndata: {\"checked\": 10, \"listed\": 0}\n\n"
  ]
}

Errors return HTTP status codes paired with stable machine-readable codes. Match on the code field rather than the human-readable message.

• 400 INVALID_IP Not a valid IP.

Patterns we recommend when integrating this endpoint:

• Use `count` ≥ 15 for definitive verdicts; smaller samples miss niche RBLs.
• An IP showing up on 2+ major RBLs is the threshold most major mail providers use.

• Which RBLs are queried? Spamhaus, SpamCop, Barracuda, SORBS, CBL, PSBL, and 30+ others. We pick the most-trusted ones first.