# Monitor list health and domain authentication

Source: https://docs.rocketverifier.com/api/monitors
Endpoint: `POST https://api.rocketverifier.com/v1/monitors` (OAuth scope `monitors:write`)

> A monitor re-checks something on a daily or weekly schedule and alerts you when it gets worse. A list_health monitor re-verifies up to 5,000 addresses and alerts when the invalid plus risky share rises. A domain_auth monitor checks a sending domain's SPF, DKIM, DMARC and DNS blacklist listings for free and alerts on any regression.

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/monitors \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "northwind.io sending domain",
    "type": "domain_auth",
    "domain": "northwind.io",
    "frequency": "daily",
    "alert_threshold": 10
  }'
```

Node.js:

```js
import RocketVerifier from "@rocketverifier/sdk";

const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);

const monitor = await rv.monitors.create({
  name: "northwind.io sending domain",
  type: "domain_auth",
  domain: "northwind.io",
  frequency: "daily",
  alertThreshold: 10,
});
console.log(monitor.id, monitor.nextRunAt);
```

Python:

```python
import os
from rocketverifier import RocketVerifier

rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])

monitor = rv.monitors.create(
    name="northwind.io sending domain",
    type="domain_auth",
    domain="northwind.io",
    frequency="daily",
    alert_threshold=10,
)
print(monitor.id, monitor.next_run_at)
```

Response 200:

```json
{
  "id": "mN4xQ8rT2vB6yK1pZ7cW3a",
  "name": "northwind.io sending domain",
  "type": "domain_auth",
  "frequency": "daily",
  "domain": "northwind.io",
  "email_count": 0,
  "alert_threshold": 10,
  "is_active": true,
  "last_run_at": null,
  "next_run_at": "2026-11-11T09:42:17.208114+00:00",
  "last_result": null,
  "created_at": "2026-11-11T09:42:17.208114+00:00"
}
```

Monitors catch deliverability problems before your campaigns do. Each run compares its result with the previous one, and a regression fires a signed [`monitor.alert` webhook](#get-alerts-by-webhook).

## Choose a monitor type

| | `list_health` | `domain_auth` |
| --- | --- | --- |
| Checks | Re-verifies up to 5,000 addresses | SPF, DKIM, DMARC and DNS blacklist listings of one domain |
| Needs | `emails` | `domain` |
| Alerts when | The invalid plus risky share rises by `alert_threshold` percentage points or more | A record disappears, the authentication score drops by `alert_threshold` points or more, or the domain's mail servers get blacklisted |
| Cost | 1 credit per unique address per run, unknown results refunded | Free |

## Create a monitor

`POST /v1/monitors` creates a monitor that runs within 10 minutes and then on its schedule. It needs the `monitors:write` scope.

**Body**

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | A label for the monitor. required; up to 200 characters |
| `type` | enum | `list_health` re-verifies a list; `domain_auth` checks a sending domain. required; one of `list_health`, `domain_auth` |
| `frequency` | enum | How often the monitor runs. default "weekly"; one of `daily`, `weekly` |
| `domain` | string or null | Required for `domain_auth`. The sending domain to check. |
| `emails` | array of strings | Required for `list_health`. Up to 5,000 addresses, stored lowercased. |
| `alert_threshold` | integer | `list_health`: alert when the invalid plus risky share rises by at least this many percentage points since the last run. `domain_auth`: alert when the authentication score drops by at least this many points. 1 to 100; default 5 |

For a list, send the addresses in `emails`:

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/monitors \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter subscribers",
    "type": "list_health",
    "emails": ["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"],
    "frequency": "weekly",
    "alert_threshold": 5
  }'
```

Node.js:

```js
const monitor = await rv.monitors.create({
  name: "Newsletter subscribers",
  type: "list_health",
  emails: ["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"],
  frequency: "weekly",
  alertThreshold: 5,
});
```

Python:

```python
monitor = rv.monitors.create(
    name="Newsletter subscribers",
    type="list_health",
    emails=["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"],
    frequency="weekly",
    alert_threshold=5,
)
```

Addresses are trimmed and lowercased, and each must pass a basic syntax check. A list with an invalid address returns `400 invalid_emails` with up to 10 of them in `details.invalid_sample`.

## Read the monitor object

Every monitor endpoint returns this object. `last_result` holds the latest finished result.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `type` | enum | one of `list_health`, `domain_auth` |
| `frequency` | enum | one of `daily`, `weekly` |
| `domain` | string or null | The checked domain (`domain_auth`). |
| `email_count` | integer | Addresses on the list (`list_health`). |
| `alert_threshold` | integer |  |
| `is_active` | boolean | False while paused. |
| `last_run_at` | string (date-time) or null |  |
| `next_run_at` | string (date-time) or null |  |
| `last_result` | object or null | The latest finished result. See the monitors page for its shape per type. |
| `created_at` | string (date-time) |  |

### Domain authentication results

A `domain_auth` run records the domain's authentication setup and its blacklist status.

last_result (domain_auth):

```json
{
  "domain": "northwind.io",
  "has_spf": true,
  "has_dmarc": true,
  "has_dkim": true,
  "spf_record": "v=spf1 include:_spf.google.com ~all",
  "dmarc_policy": "quarantine",
  "authentication_score": 100,
  "deliverability_tier": "excellent",
  "is_blacklisted": false,
  "blacklist_listings": [],
  "blacklist_checked_ips": ["142.250.153.26", "142.250.153.27"],
  "checked_at": "2026-11-11T09:50:25.118034+00:00"
}
```

### List health results

A `list_health` run re-verifies the list as a bulk job on the priority lane. While the job runs, the run's result is a marker with the `job_id`. When the job completes, the run gets the summary below, and the summary becomes `last_result`.

Running:

```json
{ "status": "running", "job_id": "Vt2kP9wL4sX8nC1bR6mQ0e", "total": 3, "started_at": "2026-11-11T09:50:25.118034+00:00" }
```

last_result (list_health):

```json
{
  "total": 4820,
  "counts": { "valid": 4310, "invalid": 212, "risky": 96, "catch_all": 151, "disposable": 9, "unknown": 42 },
  "bounce_rate_equivalent": 6.4,
  "credits_used": 4778,
  "job_id": "Vt2kP9wL4sX8nC1bR6mQ0e",
  "checked_at": "2026-11-11T10:05:25.402871+00:00"
}
```

`bounce_rate_equivalent` is the share of the list classified `invalid` or `risky`, in percent. The full results of each run are in the job: read them with the [bulk job endpoints](https://docs.rocketverifier.com/api/batch#read-results-page-by-page).

## When alerts fire

A run alerts when it is worse than the previous finished run. The first run alerts only on problems that already exist.

- **`domain_auth`:** SPF, DMARC or DKIM was present and is gone; the authentication score dropped by `alert_threshold` points or more; or the domain's mail servers are newly listed on a DNS blacklist. A blacklist listing is `critical`, everything else is `warning`. A first run alerts when the domain is already blacklisted.
- **`list_health`:** `bounce_rate_equivalent` rose by `alert_threshold` percentage points or more. A first run alerts when it is already at `alert_threshold` or 20%, whichever is higher.

Alert:

```json
{
  "severity": "warning",
  "reasons": ["DMARC record is no longer present", "Authentication score dropped from 100 to 65"],
  "current": { "domain": "northwind.io", "has_dmarc": false, "authentication_score": 65 },
  "previous": { "domain": "northwind.io", "has_dmarc": true, "authentication_score": 100 }
}
```

`current` and `previous` are the full results; they are shortened here.

## List, get, update and delete monitors

Read monitors with `monitors:read`, and change them with `monitors:write`.

`GET /v1/monitors`

Returns every monitor as an array, most recently created first. Add `?type=list_health` or `?type=domain_auth` to filter.

`GET /v1/monitors/{monitorId}`

Returns one monitor with its latest result.

`PATCH /v1/monitors/{monitorId}`

Changes any subset of fields. Set `is_active` to `false` to pause the schedule and `true` to resume it. Sending `emails` replaces the whole list.

**Body**

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | A label for the monitor. |
| `frequency` | enum | one of `daily`, `weekly` |
| `is_active` | boolean | `false` pauses the schedule; `true` resumes it. |
| `alert_threshold` | integer | 1 to 100 |
| `domain` | string | A new domain for `domain_auth` monitors. |
| `emails` | array of strings | Replaces the list of a `list_health` monitor (up to 5,000). |

`DELETE /v1/monitors/{monitorId}`

Deletes the monitor and its run history, and returns `{"success": true, "message": "Monitor deleted"}`.

cURL:

```bash
curl -X PATCH https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
```

Node.js:

```js
const all = await rv.monitors.list();
await rv.monitors.update("mN4xQ8rT2vB6yK1pZ7cW3a", { isActive: false });
await rv.monitors.delete("mN4xQ8rT2vB6yK1pZ7cW3a");
```

Python:

```python
monitors = rv.monitors.list()
rv.monitors.update("mN4xQ8rT2vB6yK1pZ7cW3a", is_active=False)
rv.monitors.delete("mN4xQ8rT2vB6yK1pZ7cW3a")
```

## Run a monitor now

`POST /v1/monitors/{monitorId}/run` runs a monitor immediately and leaves its schedule unchanged. Use it to test a monitor right after you create it.

`POST /v1/monitors/{monitorId}/run`

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a/run \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
const { result, alert } = await rv.monitors.runNow("mN4xQ8rT2vB6yK1pZ7cW3a");
```

Python:

```python
outcome = rv.monitors.run_now("mN4xQ8rT2vB6yK1pZ7cW3a")
print(outcome["result"], outcome["alert"])
```

A `domain_auth` run finishes in the request and returns its full `result` and any `alert`. A `list_health` run starts a re-verification job, charged like any bulk job, and returns the running marker with the `job_id`. A list health monitor runs one re-verification at a time, so calling run again while one is running returns the same marker. A run that cannot start, for example because the balance does not cover the list, returns `400 run_failed`.

| Field | Type | Description |
| --- | --- | --- |
| `monitor_id` | string |  |
| `result` | object | The run result, or the running marker of a `list_health` re-verification. |
| `alert` | object or null | The alert raised by this run, if any. |

## Read run history

`GET /v1/monitors/{monitorId}/runs` lists past runs, most recent first, in pages of up to 100.

`GET /v1/monitors/{monitorId}/runs`

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer | Page number, starting at 1. min 1; default 1 |
| `limit` | integer | Runs per page. 1 to 100; default 20 |

cURL:

```bash
curl "https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a/runs?limit=10" \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
const { runs, hasMore } = await rv.monitors.runs("mN4xQ8rT2vB6yK1pZ7cW3a", 1, 10);
```

Python:

```python
page = rv.monitors.runs("mN4xQ8rT2vB6yK1pZ7cW3a", page=1, limit=10)
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `result` | object | The run's result. A `list_health` run reads `status: running` with its `job_id` until the job completes. |
| `changed` | boolean | True when the run found a regression. |
| `alert_fired` | boolean | True when a `monitor.alert` webhook was queued. |
| `error_message` | string or null |  |
| `run_at` | string (date-time) |  |

## Get alerts by webhook

Subscribe a [webhook](https://docs.rocketverifier.com/api/webhooks) to `monitor.alert`. Every alert arrives as a signed event that names the monitor and carries the alert.

monitor.alert:

```json
{
  "event_id": "3e8a1c7f-2b4d-4f9e-8a6c-1d5b7e9f0a24",
  "event": "monitor.alert",
  "timestamp": "2026-11-11T10:05:26.004211+00:00",
  "data": {
    "monitor_id": "mN4xQ8rT2vB6yK1pZ7cW3a",
    "monitor_name": "northwind.io sending domain",
    "monitor_type": "domain_auth",
    "severity": "warning",
    "reasons": ["DMARC record is no longer present"],
    "current": { "domain": "northwind.io", "has_dmarc": false, "authentication_score": 65 },
    "previous": { "domain": "northwind.io", "has_dmarc": true, "authentication_score": 100 }
  }
}
```

The run's `alert_fired` is `true` once the event is queued.

## Credits

- **`domain_auth`:** free. Runs use DNS lookups only.
- **`list_health`:** 1 credit per unique address per run, charged when the run starts. Unknown results and addresses on your suppression list are refunded when the run completes. A run the balance cannot cover charges nothing and records an error.

Creating and running monitors needs a balance above zero.

## Errors

| Status | `error.code` | When it happens |
| --- | --- | --- |
| 400 | `domain_required` | A `domain_auth` monitor has no `domain`. |
| 400 | `emails_required` | A `list_health` monitor has no `emails`. |
| 400 | `invalid_emails` | Addresses failed the syntax check. `details.invalid_sample` lists up to 10. |
| 400 | `too_many_emails` | More than 5,000 addresses. |
| 400 | `no_changes`, `invalid_frequency` | The update sent nothing to change, or an unknown `frequency`. |
| 400 | `run_failed` | A run now could not start, for example for lack of credits. |
| 401 | `unauthorized`, `api_key_expired` | The key is missing, invalid, revoked or expired. |
| 403 | `insufficient_scope` | The credential lacks `monitors:read` or `monitors:write`. |
| 403 | `insufficient_credits` | The balance is zero. |
| 404 | `not_found` | No monitor with this id on your account. |
| 422 | `validation_error` | `name` or `type` is missing, `type` or `frequency` is unknown, or `alert_threshold` is outside 1 to 100. |

Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors).

## Frequently asked questions

### Do monitors cost credits?

Domain authentication monitors are free. List health runs are charged like a bulk job, 1 credit per unique address, with unknown results refunded when the run completes.

### How soon does a new monitor run?

The scheduler checks for due monitors every 10 minutes, so a new monitor runs within 10 minutes and then every day or week. Call POST /v1/monitors/{monitorId}/run to run it immediately.

### How do I get alerts?

Subscribe a webhook to the monitor.alert event. Every regression sends a signed event with the reasons and the current and previous results.

### How do I pause a monitor?

PATCH the monitor with is_active set to false. Set it back to true to resume the schedule.
