---
title: "Check an IP address or domain against blocklists"
method: GET
path: "/api/v1/tools/blocklist"
tags: ["Free DNS tools"]
---

# Check an IP address or domain against blocklists

`GET /api/v1/tools/blocklist`

## Request

- Base URL: `https://email-spam-tester.com` (the document declares no server; this is the origin it was published from)
- URL: `https://email-spam-tester.com/api/v1/tools/blocklist`
- Auth: none declared

An IPv4 address is checked against the same DNS blocklists as the report; an IPv6 address against the lists that publish IPv6 data; a domain against Spamhaus DBL, SURBL and URIBL. A list that times out or refuses our resolver is reported as such, never as clean. Status: fail if any list lists the target; otherwise error when more than half of the lists did not answer, warn when some did not, pass when all answered clean. Private, reserved and loopback addresses are refused with 422.

Free, no key. Limited to 30 requests a minute and 300 a day per client IP across all four tools; identical queries are answered from a 60-second cache. Any completed check is 200, including "no record" and "lookup failed"; `status` and `findings` carry the verdict. Each finding has a stable `code`, a `level` and `params`; `message` is the English sentence built from them.

## Query parameters

- `target` string, nullable: IPv4, IPv6 or domain, e.g. 203.0.113.5.

## Response `200`

Successful Response

- BlocklistOut
  - `tool` string, required
  - `query` object, required: The inputs after normalisation.
  - `checked_at` string, required: When the lookups ran, ISO 8601 UTC.
  - `duration_ms` integer, required
  - `status` 'pass' | 'warn' | 'fail' | 'error', required: Overall verdict. "error" means the check could not complete (timeout, SERVFAIL); it is never "pass" when a lookup the verdict needs failed.
  - `findings` Finding[], required
    - `code` string, required: Stable identifier, e.g. spf.too_many_lookups. The English template for every code is in /i18n/tools/findings.en.json on the website.
    - `level` 'pass' | 'info' | 'warn' | 'fail' | 'error', required
    - `params` object, required: Values the message is built from.
    - `message` string, required: The English sentence, params filled in.
  - `kind` 'ip' | 'domain', required
  - `lists` BlocklistRow[], required
    - `name` string, required
    - `zone` string, required
    - `kind` 'ip' | 'domain', required
    - `status` 'listed' | 'clean' | 'error' | 'refused', required
    - `codes` string[], required: A records the list returned.
    - `detail` string, nullable, required
  - `counts` BlocklistCounts, required
    - `listed` integer, required
    - `clean` integer, required
    - `error` integer, required: Lists that failed or refused to answer.

## Other responses

- `422`: The input is not something we can look up (detail.code says which).
- `429`: Too many requests from this address; Retry-After says when to come back.

---

[API](https://skmtc.dev/email-spam-tester/apis/email-spam-tester-api.md) · [All operations](https://skmtc.dev/email-spam-tester/apis/email-spam-tester-api/llms.txt) · [OpenAPI document](https://skmtc.dev/email-spam-tester/apis/email-spam-tester-api/revisions/476a4c86600d?raw)