日本語 / English

API v1

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.

ItemLimit
Daily checks (1 target = 1 count)1,000
Targets per batch100
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": "..."
}

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", ""))

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" }
HTTPerrorMeaning
400invalid_json / invalid_request / no_valid_targets / too_many_targets / invalid_target / invalid_callback_urlMalformed request, or over the per-batch limit (100)
401unauthorizedMissing / invalid / revoked key, or your plan does not include the API
403monitor_limit_reachedMonitor limit (50) reached
404not_foundUnknown endpoint, batch or monitor
409already_existsThe same target + URL is already monitored
413payload_too_largeRequest body too large
429daily_limit_exceededDaily limit (1,000) exceeded; see resets_at
503auth_unavailableAuthentication is temporarily unavailable; retry shortly

7. Notes

← Back to DNSBL Checker