−50%

50% off your first month on any paid plan · code WELCOME50 · until Nov 30

Start free →

Blocklist Monitors

Blocklist Monitors

Blocklist monitors check whether your IP address or domain is listed on email blocklists (DNSBLs). Being listed can cause email delivery failures and damage your sender reputation. The API lets you create, list, update, and delete blocklist monitors programmatically.

List blocklist monitors

GET /api/v1/blocklist-monitors

Returns a paginated list of all blocklist monitors in the project associated with your API key.

Query parameters

ParameterTypeDefaultDescription
statusstring—Filter by status: clean, listed, or error
per_pageinteger25Results per page
pageinteger1Page number
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/blocklist-monitors?status=listed&per_page=10"
$response = Http::withToken('YOUR_API_KEY')
    ->get('https://watchcron.com/api/v1/blocklist-monitors', [
        'status'   => 'listed',
        'per_page' => 10,
    ]);

$monitors = $response->json('data');
import requests

response = requests.get(
    "https://watchcron.com/api/v1/blocklist-monitors",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"status": "listed", "per_page": 10},
)

monitors = response.json()["data"]
const response = await fetch(
  "https://watchcron.com/api/v1/blocklist-monitors?status=listed&per_page=10",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data: monitors } = await response.json();
req, _ := http.NewRequest("GET",
    "https://watchcron.com/api/v1/blocklist-monitors?status=listed&per_page=10", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response 200 OK

JSON
{
  "data": [
    {
      "uuid": "f6a7b8c9-d0e1-2345-fabc-456789012345",
      "host": "203.0.113.10",
      "status": "listed",
      "interval_hours": 24,
      "listed_on": ["zen.spamhaus.org", "bl.spamcop.net"],
      "listed_count": 2,
      "is_active": true,
      "last_checked_at": "2026-10-25T14:30:00Z",
      "last_error": null,
      "created_at": "2026-09-01T10:00:00Z",
      "updated_at": "2026-10-25T14:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 8,
      "per_page": 10,
      "current_page": 1,
      "last_page": 1
    }
  }
}

Blocklist monitor object

Every blocklist monitor response includes these fields:

FieldTypeDescription
uuidstringUnique identifier (UUID v4). Used in all API URLs.
hoststringIP address or hostname being monitored (e.g. 203.0.113.10 or mail.example.com)
statusstringCurrent status: clean, listed, or error
interval_hoursintegerHours between scans (1–168)
listed_onarrayList of blocklist names where the host is currently listed
listed_countintegerNumber of blocklists currently listing this host
is_activebooleanWhether monitoring is active
last_checked_atstring|nullISO 8601 timestamp of the most recent scan
last_errorstring|nullError message from the last failed scan, if any
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Status values

StatusMeaning
cleanHost is not listed on any monitored blocklists
listedHost appears on one or more blocklists — alert triggered
errorScan failed (DNS timeout, invalid host, etc.)

Create a blocklist monitor

POST /api/v1/blocklist-monitors

Request body

FieldTypeRequiredDescription
hoststringYesIP address or hostname to monitor (max 255 characters)
interval_hoursintegerNoHours between scans, 1–168 (defaults to 24)
What gets checked: WatchCron queries dozens of well-known DNSBLs (Spamhaus, Barracuda, SpamCop, and others) for your IP or hostname. You will receive an alert the moment your host appears on any blocklist.
curl -X POST https://watchcron.com/api/v1/blocklist-monitors \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "host": "203.0.113.10",
       "interval_hours": 12
     }'
$response = Http::withToken('YOUR_API_KEY')
    ->post('https://watchcron.com/api/v1/blocklist-monitors', [
        'host'           => '203.0.113.10',
        'interval_hours' => 12,
    ]);

$monitor = $response->json('data');
import requests

response = requests.post(
    "https://watchcron.com/api/v1/blocklist-monitors",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "host": "203.0.113.10",
        "interval_hours": 12,
    },
)

monitor = response.json()["data"]
const response = await fetch("https://watchcron.com/api/v1/blocklist-monitors", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    host: "203.0.113.10",
    interval_hours: 12,
  }),
});

const { data: monitor } = await response.json();
body := strings.NewReader(`{
  "host": "203.0.113.10",
  "interval_hours": 12
}`)

req, _ := http.NewRequest("POST", "https://watchcron.com/api/v1/blocklist-monitors", body)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response 201 Created

JSON
{
  "data": {
    "uuid": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "host": "203.0.113.10",
    "status": "clean",
    "interval_hours": 12,
    "listed_on": [],
    "listed_count": 0,
    "is_active": true,
    "last_checked_at": null,
    "last_error": null,
    "created_at": "2026-10-26T10:00:00Z",
    "updated_at": "2026-10-26T10:00:00Z"
  }
}

Validation errors

If the host is missing or invalid, the API returns 422:

422 response
{
  "error": "The host field is required."
}

Get a blocklist monitor

GET /api/v1/blocklist-monitors/{uuid}

Returns full details for a single blocklist monitor.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/blocklist-monitors/f6a7b8c9-d0e1-2345-fabc-456789012345"
$uuid = 'f6a7b8c9-d0e1-2345-fabc-456789012345';

$response = Http::withToken('YOUR_API_KEY')
    ->get("https://watchcron.com/api/v1/blocklist-monitors/{$uuid}");

$monitor = $response->json('data');
uuid = "f6a7b8c9-d0e1-2345-fabc-456789012345"

response = requests.get(
    f"https://watchcron.com/api/v1/blocklist-monitors/{uuid}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

monitor = response.json()["data"]
const uuid = "f6a7b8c9-d0e1-2345-fabc-456789012345";

const response = await fetch(
  `https://watchcron.com/api/v1/blocklist-monitors/${uuid}`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data: monitor } = await response.json();

Returns the same monitor object as shown in Blocklist monitor object. Returns 404 if the UUID does not exist or belongs to a different project.

Update a blocklist monitor

PUT /api/v1/blocklist-monitors/{uuid}

Updates one or more fields on an existing blocklist monitor. Only include the fields you want to change — all fields are optional.

Request body

FieldTypeDescription
hoststringIP address or hostname (max 255 characters)
interval_hoursintegerHours between scans, 1–168
curl -X PUT https://watchcron.com/api/v1/blocklist-monitors/f6a7b8c9-d0e1-2345-fabc-456789012345 \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "host": "mail.example.com",
       "interval_hours": 6
     }'
$response = Http::withToken('YOUR_API_KEY')
    ->put("https://watchcron.com/api/v1/blocklist-monitors/{$uuid}", [
        'host'           => 'mail.example.com',
        'interval_hours' => 6,
    ]);
response = requests.put(
    f"https://watchcron.com/api/v1/blocklist-monitors/{uuid}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "host": "mail.example.com",
        "interval_hours": 6,
    },
)
const response = await fetch(`https://watchcron.com/api/v1/blocklist-monitors/${uuid}`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    host: "mail.example.com",
    interval_hours: 6,
  }),
});

Returns 200 OK with the updated monitor object.

Delete a blocklist monitor

DELETE /api/v1/blocklist-monitors/{uuid}

Permanently deletes a blocklist monitor and all its associated scan logs.

curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/blocklist-monitors/f6a7b8c9-d0e1-2345-fabc-456789012345"
$response = Http::withToken('YOUR_API_KEY')
    ->delete("https://watchcron.com/api/v1/blocklist-monitors/{$uuid}");
response = requests.delete(
    f"https://watchcron.com/api/v1/blocklist-monitors/{uuid}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
const response = await fetch(
  `https://watchcron.com/api/v1/blocklist-monitors/${uuid}`,
  {
    method: "DELETE",
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  }
);

Returns 204 No Content on success. This action is irreversible.

List scan logs

GET /api/v1/blocklist-monitors/{uuid}/logs

Returns a paginated list of scan logs for a specific blocklist monitor, ordered from newest to oldest.

Query parameters

ParameterTypeDefaultDescription
per_pageinteger25Results per page
pageinteger1Page number
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/blocklist-monitors/f6a7b8c9-d0e1-2345-fabc-456789012345/logs?per_page=10"
$uuid = 'f6a7b8c9-d0e1-2345-fabc-456789012345';

$response = Http::withToken('YOUR_API_KEY')
    ->get("https://watchcron.com/api/v1/blocklist-monitors/{$uuid}/logs", [
        'per_page' => 10,
    ]);

$logs = $response->json('data');
uuid = "f6a7b8c9-d0e1-2345-fabc-456789012345"

response = requests.get(
    f"https://watchcron.com/api/v1/blocklist-monitors/{uuid}/logs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"per_page": 10},
)

logs = response.json()["data"]
const uuid = "f6a7b8c9-d0e1-2345-fabc-456789012345";

const response = await fetch(
  `https://watchcron.com/api/v1/blocklist-monitors/${uuid}/logs?per_page=10`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data: logs } = await response.json();
req, _ := http.NewRequest("GET",
    "https://watchcron.com/api/v1/blocklist-monitors/f6a7b8c9-d0e1-2345-fabc-456789012345/logs?per_page=10", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response 200 OK

JSON
{
  "data": [
    {
      "status": "listed",
      "listed_on": ["zen.spamhaus.org", "bl.spamcop.net"],
      "listed_count": 2,
      "error": null,
      "checked_at": "2026-10-25T14:30:00Z"
    },
    {
      "status": "clean",
      "listed_on": [],
      "listed_count": 0,
      "error": null,
      "checked_at": "2026-10-24T14:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 55,
      "per_page": 10,
      "current_page": 1,
      "last_page": 6
    }
  }
}

Log entry fields

FieldTypeDescription
statusstringScan result: clean, listed, or error
listed_onarrayBlocklist names where the host was found during this scan
listed_countintegerNumber of blocklists listing the host at scan time
errorstring|nullError message if the scan failed
checked_atstringISO 8601 timestamp of when the scan ran
Pricing Docs
Log in Start free →