https://api.rocketverifier.com/v1/monitorsMonitor list health and domain authentication
In short
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.
OAuth scope monitors:write
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
}'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);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){
"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.
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
A label for the monitor.
list_healthre-verifies a list;domain_authchecks a sending domain.list_healthdomain_authHow often the monitor runs.
dailyweekly- domainstring or null
Required for
domain_auth. The sending domain to check. - emailsarray of strings
Required for
list_health. Up to 5,000 addresses, stored lowercased. 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.
For a list, send the addresses in emails:
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
}'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,
});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.
- idstring
- namestring
- typeenumlist_healthdomain_auth
- frequencyenumdailyweekly
- domainstring or null
The checked domain (
domain_auth). - email_countinteger
Addresses on the list (
list_health). - alert_thresholdinteger
- is_activeboolean
False while paused.
- last_run_atstring (date-time) or null
- next_run_atstring (date-time) or null
- last_resultobject or null
The latest finished result. See the monitors page for its shape per type.
- created_atstring (date-time)
Domain authentication results#
A domain_auth run records the domain's authentication setup and its blacklist status.
{
"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.
{ "status": "running", "job_id": "Vt2kP9wL4sX8nC1bR6mQ0e", "total": 3, "started_at": "2026-11-11T09:50:25.118034+00:00" }{
"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.
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 byalert_thresholdpoints or more; or the domain's mail servers are newly listed on a DNS blacklist. A blacklist listing iscritical, everything else iswarning. A first run alerts when the domain is already blacklisted.list_health:bounce_rate_equivalentrose byalert_thresholdpercentage points or more. A first run alerts when it is already atalert_thresholdor 20%, whichever is higher.
{
"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.
/v1/monitorsReturns every monitor as an array, most recently created first. Add ?type=list_health or ?type=domain_auth to filter.
/v1/monitors/{monitorId}Returns one monitor with its latest result.
/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
/v1/monitors/{monitorId}Deletes the monitor and its run history, and returns {"success": true, "message": "Monitor deleted"}.
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}'const all = await rv.monitors.list();
await rv.monitors.update("mN4xQ8rT2vB6yK1pZ7cW3a", { isActive: false });
await rv.monitors.delete("mN4xQ8rT2vB6yK1pZ7cW3a");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.
/v1/monitors/{monitorId}/runcurl -X POST https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a/run \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"const { result, alert } = await rv.monitors.runNow("mN4xQ8rT2vB6yK1pZ7cW3a");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.
- monitor_idstring
- resultobject
The run result, or the running marker of a
list_healthre-verification. - alertobject 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.
/v1/monitors/{monitorId}/runsQuery parameters
Page number, starting at 1.
Runs per page.
curl "https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a/runs?limit=10" \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"const { runs, hasMore } = await rv.monitors.runs("mN4xQ8rT2vB6yK1pZ7cW3a", 1, 10);page = rv.monitors.runs("mN4xQ8rT2vB6yK1pZ7cW3a", page=1, limit=10)- idstring
- resultobject
The run's result. A
list_healthrun readsstatus: runningwith itsjob_iduntil the job completes. - changedboolean
True when the run found a regression.
- alert_firedboolean
True when a
monitor.alertwebhook was queued. - error_messagestring or null
- run_atstring (date-time)
Get alerts by webhook#
Subscribe a webhook to monitor.alert. Every alert arrives as a signed event that names the monitor and carries the alert.
{
"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.
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.
Updated 11 November 2026Suggest an edit