DNSBLチェッカー API 利用ガイド
複数のドメイン・IPアドレスを一括でブラックリスト判定するバッチAPIと、状態が変わったときに通知するWebhook監視のリファレンス。
1. 概要とプラン
APIは、会員登録(無料)をすれば利用できます。現在は当面の間、無料で提供しています(有料化する場合は、事前にお知らせします)。会員登録はメールアドレスだけ(パスワードなし)で、当サイトの会員ページから行えます。
| 項目 | 上限 |
|---|---|
| 1日の判定件数(対象1件=1カウント) | 1,000 |
| バッチ1回あたりの対象数 | 100 |
| Webhook監視の登録数(ブラックリスト掲載状況の監視) | 50 (1日1回判定) |
2. 認証(APIキー)
APIキーは https://dnsblchecker.com/account で発行します(メールのログインリンクでログインします)。キーは発行直後の1回だけ表示され、当サイトにはハッシュしか保存されません。再発行すると以前のキーは無効になります。
すべてのリクエストに X-API-Key ヘッダーでキーを付けてください。通信は HTTPS のみです。
curl https://dnsblchecker.com/api/v1/monitors -H "X-API-Key: dnsbl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
キーは秘密情報です。ブラウザ側のコードやリポジトリに含めないでください。
3. バッチ判定
POST/api/v1/batch
複数のドメイン名・IPアドレスをまとめて判定します。すでに判定済み(30日以内の結果)の対象はすぐ結果が返り、未判定の対象はサーバー側で順次判定されます(通常は数十秒〜数分)。
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"]}'
レスポンス(未判定の対象があれば 202、すべて判定済みなら 200):
{
"batch_id": 1,
"status": "processing",
"count": 2,
"pending": 1,
"rejected": [],
"poll_url": "https://dnsblchecker.com/api/v1/batch/1"
}
不正な形式の対象は rejected に理由付きで返り、カウントされません。重複は1件にまとめられます。
GET/api/v1/batch/{batch_id}
status が done になるまで数秒おきに取得してください(目安: 5〜10秒間隔)。
{
"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, // 応答が得られなかったリスト数
"listed_on": [
{ "list": "ZapBL RHSBL", "zone": "rhsbl.zapbl.net", "response": "127.0.0.2" }
]
}
]
}
バッチは作成したアカウントからのみ取得できます。
4. Webhook監視
登録した対象を毎日1回自動で判定し、初回と判定(listed/clean)が変わったときだけ、あなたのURLへ署名付きで通知します。
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...", // この1回しか表示されません
"note": "..."
}
callback_urlは https のみ。ホスト名が公開IPに解決できないもの(社内・ローカルアドレス)は登録できません。リダイレクトは辿りません。- 同じ対象と同じ
callback_urlの組み合わせは重複登録できません(409)。 signing_secretは必ず保管してください。紛失した場合は監視を削除して登録し直します。
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 }
]
}
提供条件が変わり、会員がAPIを利用できなくなった場合は、監視が suspended になり通知が止まります。利用できる状態に戻ると自動的に再開します。
DELETE/api/v1/monitors/{monitor_id}
{ "deleted": true, "monitor_id": 1 }
5. 通知(Webhook)の受け取り方
変化があると、登録したURLへ次のJSONが POST されます。
{
"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" } ]
}
リクエストには X-DNSBL-Signature: sha256=<hex> ヘッダーが付きます。値は、生のリクエストボディを signing_secret で HMAC-SHA256 した16進文字列です。受信側で必ず検証してください。
// 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", ""))
2xxを返すと配信成功です。それ以外や通信失敗のときは、翌日の判定で再度通知を試みます(last_delivery_errorに理由が残ります)。- タイムアウトは10秒です。重い処理はキューに積んで先に
2xxを返してください。 - 同じイベントが再送されても問題ないよう、
monitor_idとchecked_atで冪等に処理してください。
6. エラー
エラーは次の形式の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 | 意味 |
|---|---|---|
| 400 | invalid_json / invalid_request / no_valid_targets / too_many_targets / invalid_target / invalid_callback_url | リクエストの内容が不正、または上限(1バッチ100件)超過 |
| 401 | unauthorized | APIキーがない・無効・失効、またはプランにAPIが含まれていない |
| 403 | monitor_limit_reached | 監視の登録上限(50件)に達している |
| 404 | not_found | エンドポイント・バッチ・監視が存在しない |
| 409 | already_exists | 同じ対象・同じURLの監視が登録済み |
| 413 | payload_too_large | リクエストボディが大きすぎる |
| 429 | daily_limit_exceeded | 1日の判定件数(1,000件)を超過。resets_at にリセット時刻 |
| 503 | auth_unavailable | 認証サービスが一時的に利用できない。少し待って再試行 |
7. 注意事項
- 判定結果は、ブラックリスト事業者(DNSBL)の応答をそのまま反映したものです。掲載の有無や解除は各事業者が決めるため、当サイトでは削除・解除できません。
- バッチの結果は最大30日間のキャッシュを含みます。最新の状態は
checked_atで確認してください。Webhook監視は毎回新規に判定します。 - 仕様は予告なく機能追加されることがあります。レスポンスに未知のフィールドが増えても動くように実装してください。