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
/api/v1/blocklist-monitors
Returns a paginated list of all blocklist monitors in the project associated with your API key.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | — | Filter by status: clean, listed, or error |
per_page | integer | 25 | Results per page |
page | integer | 1 | Page 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
{
"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:
| Field | Type | Description |
|---|---|---|
uuid | string | Unique identifier (UUID v4). Used in all API URLs. |
host | string | IP address or hostname being monitored (e.g. 203.0.113.10 or mail.example.com) |
status | string | Current status: clean, listed, or error |
interval_hours | integer | Hours between scans (1–168) |
listed_on | array | List of blocklist names where the host is currently listed |
listed_count | integer | Number of blocklists currently listing this host |
is_active | boolean | Whether monitoring is active |
last_checked_at | string|null | ISO 8601 timestamp of the most recent scan |
last_error | string|null | Error message from the last failed scan, if any |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Status values
| Status | Meaning |
|---|---|
clean | Host is not listed on any monitored blocklists |
listed | Host appears on one or more blocklists — alert triggered |
error | Scan failed (DNS timeout, invalid host, etc.) |
Create a blocklist monitor
/api/v1/blocklist-monitors
Request body
| Field | Type | Required | Description |
|---|---|---|---|
host | string | Yes | IP address or hostname to monitor (max 255 characters) |
interval_hours | integer | No | Hours between scans, 1–168 (defaults to 24) |
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
{
"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:
{
"error": "The host field is required."
}
Get a blocklist monitor
/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
/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
| Field | Type | Description |
|---|---|---|
host | string | IP address or hostname (max 255 characters) |
interval_hours | integer | Hours 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
/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
/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
| Parameter | Type | Default | Description |
|---|---|---|---|
per_page | integer | 25 | Results per page |
page | integer | 1 | Page 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
{
"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
| Field | Type | Description |
|---|---|---|
status | string | Scan result: clean, listed, or error |
listed_on | array | Blocklist names where the host was found during this scan |
listed_count | integer | Number of blocklists listing the host at scan time |
error | string|null | Error message if the scan failed |
checked_at | string | ISO 8601 timestamp of when the scan ran |