# Domain DNSBL

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/domain/dnsbl` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/domain-dnsbl |

## Description

Check if a domain or IP address is listed in DNS-based blacklists (DNSBL), with detailed provider-level detection and category information.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/domain/dnsbl' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Check blacklisted IP address

```json
{
  "address": "185.122.xx.xx",
  "detected": {
    "count": 5,
    "providers": [
      "dbl.spamhaus.org",
      "spambot.bls.digibase.ca",
      "abuse-contacts.abusix.org",
      "origin.asn.cymru.com",
      "peer.asn.cymru.com"
    ],
    "categories": {
      "dbl.spamhaus.org": [
        "unknown"
      ],
      "peer.asn.cymru.com": [
        "unknown"
      ],
      "origin.asn.cymru.com": [
        "unknown"
      ],
      "spambot.bls.digibase.ca": [
        "unknown"
      ],
      "abuse-contacts.abusix.org": [
        "unknown"
      ]
    }
  },
  "providers": {
    "failed": [
      "list.bbfh.org",
      "dnsbl.darklist.de",
      "dnsbl.isx.fr"
    ],
    "domains": [
      "dbl.spamhaus.org",
      "spambot.bls.digibase.ca",
      "zen.spamhaus.org"
    ],
    "failed_count": 23,
    "domains_count": 271
  },
  "blacklisted": true
}
```

## Documentation

## Overview
The Domain DNSBL endpoint checks any domain or IP address against hundreds of DNS-based blacklists (DNSBL). It reveals whether the target is blacklisted, which providers detected it, and in which abuse categories.

## Quickstart
```
GET https://api.piloterr.com/v2/domain/dnsbl?query=185.122.10.10
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Domain name or IPv4 address to check |

## Response fields
| Field | Type | Description |
|---|---|---|
| `address` | string | The checked domain or IP |
| `blacklisted` | boolean | Whether listed in any DNSBL |
| `detected.count` | number | Number of detecting providers |
| `detected.providers` | array | Providers that flagged the address |
| `detected.categories` | object | Per-provider category labels |
| `providers.failed_count` | number | Count of unavailable providers |
| `providers.domains_count` | number | Total DNSBL domains checked |

## Notes
- Categories: `unknown`, `spam`, `exploits`, `phish`, `malware`, `cnc`, `abused`, `legit`.
- `blacklisted: false` does not guarantee legitimacy.

## Main use cases
- Screen sender IPs before configuring email delivery infrastructure
- Automate spam prevention by blocking blacklisted IPs
- Monitor your mail server IP reputation for unexpected blacklisting
- Enrich security threat intelligence with real-time DNSBL data