日本語 / English

API v1

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": "..."
}

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

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" }
HTTPerror意味
400invalid_json / invalid_request / no_valid_targets / too_many_targets / invalid_target / invalid_callback_urlリクエストの内容が不正、または上限(1バッチ100件)超過
401unauthorizedAPIキーがない・無効・失効、またはプランにAPIが含まれていない
403monitor_limit_reached監視の登録上限(50件)に達している
404not_foundエンドポイント・バッチ・監視が存在しない
409already_exists同じ対象・同じURLの監視が登録済み
413payload_too_largeリクエストボディが大きすぎる
429daily_limit_exceeded1日の判定件数(1,000件)を超過。resets_at にリセット時刻
503auth_unavailable認証サービスが一時的に利用できない。少し待って再試行

7. 注意事項

← DNSBLチェッカーのトップへ