DNSBL Checker API Documentation
Reference for the batch API that checks many domains and IP addresses against DNSBLs, and for webhook monitoring that notifies you when a verdict changes.
1. Overview and plan
The API is available to registered members, and is free of charge for now (we will announce in advance if this changes). Sign-up needs only an email address (no password) on the members page of this site.
| Item | Limit |
|---|---|
| Daily checks (1 target = 1 count) | 1,000 |
| Targets per batch | 100 |
| Monitored targets (blacklist status, via webhook) | 50 (checked once a day) |
2. Authentication (API key)
Issue your key at https://dnsblchecker.com/account (you log in with an emailed link). The key is shown only once, and only its hash is stored. Re-issuing invalidates the previous key.
Send the key in the X-API-Key header on every request. HTTPS only.
curl https://dnsblchecker.com/api/v1/monitors -H "X-API-Key: dnsbl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Treat the key as a secret: never embed it in browser code or commit it to a repository.
3. Batch check
POST/api/v1/batch
Checks several domains / IP addresses at once. Targets with a result from the last 30 days are answered immediately; the others are queued and checked on the server (usually within tens of seconds to a few minutes).
curl -X POST https://dnsblchecker.com/api/v1/batch \
-H "X-API-Key: $DNSBL_API_KEY" -H "Content-Type: application/json" \
-d '{"targets":["example.com","example.net"]}'
Response (202 if some targets are still pending, 200 if all are done):
{
"batch_id": 1,
"status": "processing",
"count": 2,
"pending": 1,
"rejected": [],
"poll_url": "https://dnsblchecker.com/api/v1/batch/1"
}
Malformed targets are returned in rejected with a reason and are not counted. Duplicates are merged.
GET/api/v1/batch/{batch_id}
Poll until status is done (every 5-10 seconds is plenty).
{
"batch_id": 1,
"status": "done",
"created": "2026-09-19 14:18:21",
"count": 2,
"pending": 0,
"results": [
{
"target": "example.com",
"type": "domain",
"status": "done",
"verdict": "listed", // "listed" | "clean"
"checked_at": "2026-09-19 12:26",
"lists_checked": 80,
"listed_count": 5,
"error_count": 4, // lists that did not answer
"listed_on": [
{ "list": "ZapBL RHSBL", "zone": "rhsbl.zapbl.net", "response": "127.0.0.2" }
]
}
]
}
A batch can only be read by the account that created it.
4. Webhook monitoring
Registered targets are checked automatically once a day. You are notified at your URL, with a signature, on the first check and whenever the verdict (listed/clean) changes.
POST/api/v1/monitors
curl -X POST https://dnsblchecker.com/api/v1/monitors \
-H "X-API-Key: $DNSBL_API_KEY" -H "Content-Type: application/json" \
-d '{"target":"example.com","callback_url":"https://your-app.example/hooks/dnsbl"}'
{
"monitor_id": 1,
"target": "example.com",
"type": "domain",
"callback_url": "https://your-app.example/hooks/dnsbl",
"signing_secret": "51789368dc8705e2...", // shown only once
"note": "..."
}
callback_urlmust be https, and its host must resolve to a public IP (no private / local addresses). Redirects are not followed.- The same target +
callback_urlpair cannot be registered twice (409). - Store
signing_secretsafely. If you lose it, delete the monitor and register it again.
GET/api/v1/monitors
{
"count": 1, "limit": 50,
"monitors": [
{ "monitor_id": 1, "target": "example.com", "type": "domain",
"callback_url": "https://your-app.example/hooks/dnsbl",
"state": "active", // "active" | "suspended"
"last_verdict": "clean", "last_listed_count": 0,
"last_checked_at": "2026-09-19 14:18:57",
"last_delivery_error": null }
]
}
If a member loses API access (for example if the terms of provision change), monitors become suspended and notifications stop; they resume automatically when access is restored.
DELETE/api/v1/monitors/{monitor_id}
{ "deleted": true, "monitor_id": 1 }
5. Receiving webhook notifications
When something changes, this JSON is sent as a POST to your URL.
{
"event": "monitor.status_changed", // "monitor.initial" | "monitor.status_changed"
"monitor_id": 1,
"target": "example.com",
"type": "domain",
"verdict": "listed",
"previous_verdict": "clean",
"listed_count": 5,
"lists_checked": 80,
"checked_at": "2026-09-19 14:18",
"listed_on": [ { "list": "ZapBL RHSBL", "zone": "rhsbl.zapbl.net", "response": "127.0.0.2" } ]
}
Each request carries an X-DNSBL-Signature: sha256=<hex> header: the HMAC-SHA256 of the raw request body, keyed with your signing_secret. Always verify it on your side.
// PHP
$body = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_DNSBL_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $body, $signingSecret);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }
# Python
import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, request.headers.get("X-DNSBL-Signature", ""))
- Return
2xxto acknowledge. On any other status or a connection failure, delivery is retried at the next daily check (the reason is kept inlast_delivery_error). - The timeout is 10 seconds. Queue heavy work and return
2xxfirst. - Handle events idempotently (use
monitor_id+checked_at) in case one is redelivered.
6. Errors
Errors are returned as JSON:
{ "error": "daily_limit_exceeded", "message": "Daily request limit exceeded for your plan.", "limit": 1000, "used": 1000, "resets_at": "2026-09-20T00:00:00+09:00" }
| HTTP | error | Meaning |
|---|---|---|
| 400 | invalid_json / invalid_request / no_valid_targets / too_many_targets / invalid_target / invalid_callback_url | Malformed request, or over the per-batch limit (100) |
| 401 | unauthorized | Missing / invalid / revoked key, or your plan does not include the API |
| 403 | monitor_limit_reached | Monitor limit (50) reached |
| 404 | not_found | Unknown endpoint, batch or monitor |
| 409 | already_exists | The same target + URL is already monitored |
| 413 | payload_too_large | Request body too large |
| 429 | daily_limit_exceeded | Daily limit (1,000) exceeded; see resets_at |
| 503 | auth_unavailable | Authentication is temporarily unavailable; retry shortly |
7. Notes
- Verdicts reflect the answers of each DNSBL operator as-is. Listing and delisting are decided by the operators; we cannot remove entries.
- Batch results may come from a cache of up to 30 days; check
checked_at. Webhook monitoring always performs a fresh check. - New response fields may be added without notice; ignore fields you do not recognise.