# Watch DNS blacklists (DNSBL monitor)

The **DNSBL** monitor (API type `dnsbl`, shown in the app as **DNSBL check**) looks your domain's addresses up in
DNS-based blacklists (DNSBLs) and alerts you when one of them lists you. A listing quietly sends your email to spam
folders and can get your site flagged by security software - usually long before anyone tells you.

:::tip[Attached or standalone]
A Website, Ping or Port monitor can carry DNSBL as an [attached sub-check](/monitors/types/attached-sub-checks/).
Use a standalone DNSBL monitor when you want the **What to check** scope (all IPs, or your mail servers), when
the address has no other monitor, or when a single listing should alert you - the attached check alerts only at
two listings.
:::

## At a glance

| | |
|---|---|
| API type token | `dnsbl` |
| Runs from | HostTracker's own internal check network - no location picker |
| Schedule | every 6 hours, fixed |
| Plan gates | the DNSBL type is a package feature (`dnsbl`) |

## How it decides

Each check resolves the addresses in scope and queries them against HostTracker's catalogue of blacklists.

- **Down** when the address is listed on **any** blacklist that counts (the catalogue weights each list; listings
  on minor lists and listings you muted are shown but do not count). The alert names the lists.
- **Down** when the domain does not exist in DNS at all.
- An IPv6-only host cannot be tested by IPv4 blacklists; the check stays Up and notes that.
- If some blacklists do not answer, the check concludes on the ones that did; if none answer, it tries again at
  the next run instead of guessing.

## Settings reference

The name, tags, **Full Log**, **Open Stats** and subscriptions work as described in
[Common monitor fields](/monitors/types/http/#common-monitor-fields).

| Setting (app label) | API field | Type / allowed values | Default | Plan limits | What it does for you |
|---|---|---|---|---|---|
| **Domain / IP** | `url` | domain or IP | required | - | What to check. |
| **What to check** (Check Configuration) | `settings.scope` | `firstWebIp` (**Web address IP**), `allWebIps` (**All web IPs**), `webAndMx` (**Web + mail (MX)**) | `firstWebIp` | - | Only the first A record, every A record, or every A record plus the IPs of your MX mail servers - the ones spam filters look up. |
| Interval | `interval` | ignored | 6 hours | - | Fixed; a sent value is replaced and the response carries a warning. Cron is not supported. |
| Locations | `locations` | not accepted | - | - | Sending pools is refused. |

When you change only `url` in an update, the stored scope is kept.

### Blacklist status and muting

In the editor, **Blacklist status** lists every current listing: **Blacklist**, **Listed endpoint**, a **Note**
from the list, a **MAJOR** marker for significant lists, a **Delist** link to the list's removal page, and
**Mute** / **Unmute**. A muted listing stays visible but no longer turns the monitor Down - use it for a list you
have decided to ignore.

## Set it up in the app

1. On the **Sites** dashboard, click **Add Monitor** and choose **DNSBL check** in **Monitoring Type**.
2. Enter the domain or IP in **Domain / IP** and a name.
3. In **Check Configuration**, choose **What to check** - **Web + mail (MX)** when email reputation matters.
4. Click **Save**. After the first check, open the monitor to see **Blacklist status**.

## Do it with the API or MCP

```bash
curl -X POST https://api2.host-tracker.com/monitor \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "type": "dnsbl", "url": "example.com", "settings": { "scope": "webAndMx" } }'
```

Update the scope:

```bash
curl -X PATCH https://api2.host-tracker.com/monitor/<monitor-id> \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "settings": { "scope": "allWebIps" } }'
```

Read the listings with `GET /monitor/{monitorId}/attached` (the `dnsbl` block: `listings[]` with `name`, `host`,
`txt`, `weight`, `removalUrl`, `muted`, plus `checkedAt`), and mute or unmute with:

```bash
curl -X POST https://api2.host-tracker.com/monitor/<monitor-id>/attached/dnsbl/mute \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "listings": ["<blacklist name>"], "muted": true }'
```

MCP: `create_monitor(type="dnsbl", url="example.com", settingsJson="{\"scope\":\"webAndMx\"}")` - no `interval`,
no `pools`. Read listings with `get_monitor(id, expand="attached")`.

## Recipes

- **Mail deliverability** - scope `webAndMx` on your mail domain.
- **A server with several addresses** - scope `allWebIps`.
- **A shared-hosting IP** - put the IP itself in `url`.

## What happens next

The first check runs shortly after you save, then every 6 hours. A new listing turns the monitor Down and alerts the
subscribed contacts; a still-listed monitor repeats the reminder at most once a day. Delisting is done on the
blacklist's own site (the **Delist** link); the monitor turns Up at the next check after the list drops you.

## Limits and gotchas

- The address must not contain `!##` (`422 invalid_settings`).
- `403 package_limit` - your package does not include DNSBL monitors.
- `422 validation_failed` with `reason: pool_not_supported_for_type` - omit `locations`.
- HostTracker checks DNS blacklists only. It does not monitor SPF, DKIM, DMARC or email delivery.

## Related

- [Attach sub-checks to a monitor](/monitors/types/attached-sub-checks/)
- [Web Risk monitor](/monitors/types/web-risk/)
- [Ping monitor](/monitors/types/ping/)