Coverage
What we can check, what answered, and what is left out.
Sources by family
Check one target
An IP or a domain. Every source, or it says unknown.
Bulk check
Paste targets or upload a csv. Up to 30,000 a day.
Monitors
One run a day at 06:00 New York, and a message only when something changes.
Recent changes
Domains
Authentication health for every domain checked. Public DNS only.
Sources
Every source we know about, including the ones that do not answer.
Docs
Everything the backend team needs. Keys, check, bulk, watchlist, limits.
Keys
One shared key, sent either as a header or as a bearer token. Nothing else is needed.
X-API-Key: <key> Authorization: Bearer <key>
A missing or wrong key returns 401. /v1/health is the only route that needs no key.
The key lives only on the box, in /opt/blacklist/.env. It is never in the repo.
POST /v1/check
curl -X POST http://2.24.141.32/v1/check \
-H "X-API-Key: <key>" \
-H "Content-Type: application/json" \
-d '{"target":"brainnerapply.com"}'
A domain or an ip. Every applicable source is asked in parallel: 19 for a domain, 57 for an ip. Takes about 2 seconds.
{
"target": "brainnerapply.com",
"result": "listed",
"summary": {"sources_checked": 19, "passed": 17, "listed": 2,
"unknown": 0, "not_applicable": 3, "unverified": 1},
"listed_on": [{"zone": "dbl.spamhaus.org", "codes": ["127.0.1.2"], "meaning": "..."}],
"sources": [{"zone": "...", "status": "clean", "codes": []}],
"health": {"verdict": "strong", "score": 5}
}
result is listed, clean or unknown. Unknown means a source did not answer. It is never reported as clean.
POST /v1/bulk
Three ways in. All of them return a job id.
# 1. a csv file, one target per line
curl -X POST http://2.24.141.32/v1/bulk \
-H "X-API-Key: <key>" -F "file=@targets.csv"
# 2. a json body
curl -X POST http://2.24.141.32/v1/bulk \
-H "X-API-Key: <key>" -H "Content-Type: application/json" \
-d '{"targets":["a.com","1.2.3.4"]}'
# 3. poll the job curl http://2.24.141.32/v1/bulk/<job> -H "X-API-Key: <key>"
Returns done, total, status and, when complete, one row per target with its result, the sources it was listed on, and its auth score.
Up to 30,000 targets per day. 200 targets take about 3 minutes.
Watchlist
The daily run checks this list. Pausing keeps the row and stops the check, so nothing is lost.
GET /v1/watchlist?kind=domain|ip
POST /v1/watchlist {"target":"a.com"} or {"targets":["a.com","1.2.3.4"]}
POST /v1/watchlist/<target>/pause
POST /v1/watchlist/<target>/restore
DELETE /v1/watchlist/<target>
Today the list holds a small active set and everything else paused, until the final list is chosen.
MXToolbox compatible routes
What Inframail calls instead of their current provider. Raw key in Authorization.
GET /api/v1/lookup/blocklist/<domain-or-ip> GET /api/v1/lookup/ptr/<ip> GET /api/v1/lookup/dmarc/<domain> GET /api/v1/lookup/dkim/<selector>._domainkey.<domain> GET /api/v1/Usage
Answers are provider shaped: Failed, Passed, Warnings, Timeouts. A source that did not answer is never a pass.
A required list failing returns 503, not an empty Failed. IPv6 is rejected with 400.
Other endpoints
Status codes
Prompt for an agent
Check these domains against every blacklist and tell me, for each one, how many sources it passed, how many it failed, which sources it is listed on, and whether its spf, dmarc and dkim are healthy. Post them to http://2.24.141.32/v1/bulk with the header X-API-Key, poll the job until it is complete, and give me a table.
Prompt to explain a listing to a client
This domain is listed on <source> with code <code>. Explain in two short paragraphs what that list is, why a sending domain ends up on it, and the exact steps to get removed. No jargon, no alarm.