DNSBL API

API reference

DNSBL HTTP endpoints on api.syndaq.com.

All DNSBL endpoints are served from https://api.syndaq.com/v1/dnsbl/.

Authenticated requests require a valid DNSBL key. Lookup routes require your bl_sec_ secret key.

Endpoints overview

Method	Path	Auth	Purpose
GET	`/v1/dnsbl/lookup`	Secret key	Lookup by `?ip=` query parameter
GET	`/v1/dnsbl/lookup/{ip}`	Secret key	Lookup by IP in the URL path
GET	`/v1/dnsbl/status`	Public or secret key	Plan limits and quota snapshot

Response headers

Successful and error responses may include:

Header	Description
`X-Request-Id`	Unique ID for support and log correlation
`X-RateLimit-Limit`	Plan requests per minute for this key
`X-RateLimit-Remaining`	Requests left in the current minute window
`X-RateLimit-Reset`	Unix timestamp when the minute window resets
`X-Quota-Limit`	Monthly quota for the subscription
`X-Quota-Remaining`	Lookups left this calendar month (UTC)
`X-Quota-Period`	Current quota month (`YYYY-MM`)
`Retry-After`	Seconds to wait after HTTP 429

GET /v1/dnsbl/lookup

Checks a public IPv4 address against Syndaq's configured DNSBL zones.

Request

Pass the target IP using one of these forms:

GET /v1/dnsbl/lookup/8.8.8.8
GET /v1/dnsbl/lookup?ip=8.8.8.8

IPv4 only. IPv6 is not supported on this product.

Headers:

Authorization: Bearer bl_sec_YOUR_SECRET_KEY

Success response (200)

{
  "success": true,
  "ip": "8.8.8.8",
  "cached": true,
  "fetched_at": "2026-07-15 12:00:00.000",
  "listed": false,
  "list_count": 0,
  "lists": [],
  "checked": 8,
  "request_id": "e6d04020be9b57b1e1069d6e483c0443"
}

When an address is listed, listed is true and lists contains each matching zone:

{
  "listed": true,
  "list_count": 2,
  "lists": [
    {
      "zone": "bl.spamcop.net",
      "name": "SpamCop",
      "responses": ["127.0.0.2"]
    },
    {
      "zone": "dnsbl.sorbs.net",
      "name": "SORBS",
      "responses": ["127.0.0.6"]
    }
  ],
  "checked": 8
}

Zones queried include Spamhaus ZEN, SpamCop, Barracuda, SORBS, UCEPROTECT Level 1, PSBL, and DroneBL. Exact zone coverage may expand over time; use checked for the count on each response.

Response fields

Field	Type	Description
`ip`	string	Normalized IPv4 address that was checked
`cached`	boolean	`true` when Syndaq already holds a recent result for this lookup
`fetched_at`	string	When this result was last retrieved
`listed`	boolean	`true` if any zone returned a listing
`list_count`	integer	Number of zones that listed the IP
`lists`	array	Matching zone objects (`zone`, `name`, `responses`)
`checked`	integer	Number of DNSBL zones queried for this check

GET /v1/dnsbl/status

Returns key status, plan limits, and quota usage without performing a lookup.

Request

GET /v1/dnsbl/status
Authorization: Bearer bl_sec_YOUR_SECRET_KEY

The public key (bl_pub_) is accepted on this route.

Success response (200)

{
  "success": true,
  "status": "active",
  "product": "dnsbl",
  "plan": "starter",
  "rate_limit_per_minute": 120,
  "monthly_quota": 10000,
  "quota_unlimited": false,
  "quota_remaining": 9842,
  "quota_period": "2026-07",
  "database_records": 125000
}

Errors

Failed requests return JSON with success: false, error, error_code, and usually request_id.

HTTP	error_code	Typical cause
400	`invalid_ip`	Missing or malformed IP address
401	`missing_credentials`	No API key provided
401	`invalid_api_key`	Unknown, inactive, or revoked key
401	`wrong_key_type`	Public key used on a lookup endpoint
403	`ip_not_allowed`	Caller IP not on the key allowlist
422	`ip_not_routable`	Private, reserved, non-routable, or IPv6 address
429	`rate_limit_exceeded`	Per-minute limit exceeded
429	`quota_exceeded`	Monthly quota exhausted
502	`lookup_failed`	Temporary DNSBL query failure
500	`internal_error`	Unexpected server error

Handle non-200 responses in your application and retry transient errors with exponential backoff.