Skip to content
RocketVerifierDOCS
POSThttps://api.rocketverifier.com/v1/monitors

Monitor 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
  }'
Response 200
{
  "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_healthdomain_auth
ChecksRe-verifies up to 5,000 addressesSPF, DKIM, DMARC and DNS blacklist listings of one domain
Needsemailsdomain
Alerts whenThe invalid plus risky share rises by alert_threshold percentage points or moreA record disappears, the authentication score drops by alert_threshold points or more, or the domain's mail servers get blacklisted
Cost1 credit per unique address per run, unknown results refundedFree

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

  • namestringrequiredup to 200 characters

    A label for the monitor.

  • typeenumrequired

    list_health re-verifies a list; domain_auth checks a sending domain.

    list_healthdomain_auth
  • frequencyenumdefault "weekly"

    How 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.

  • alert_thresholdinteger1 to 100default 5

    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
  }'

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.

Domain authentication results#

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

last_result (domain_auth)
{
  "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
{ "status": "running", "job_id": "Vt2kP9wL4sX8nC1bR6mQ0e", "total": 3, "started_at": "2026-11-11T09:50:25.118034+00:00" }
last_result (list_health)
{
  "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 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
{
  "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

  • namestring

    A label for the monitor.

  • dailyweekly
  • is_activeboolean

    false pauses the schedule; true resumes it.

  • alert_thresholdinteger1 to 100
  • domainstring

    A new domain for domain_auth monitors.

  • emailsarray of strings

    Replaces the list of a list_health monitor (up to 5,000).

DEL/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}'

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 -X POST https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a/run \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"

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.

  • resultobject

    The run result, or the running marker of a list_health re-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.

GET/v1/monitors/{monitorId}/runs

Query parameters

  • pageintegermin 1default 1

    Page number, starting at 1.

  • limitinteger1 to 100default 20

    Runs per page.

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

    The run's result. A list_health run reads status: running with its job_id until the job completes.

  • changedboolean

    True when the run found a regression.

  • True when a monitor.alert webhook 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.

monitor.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#

Statuserror.codeWhen it happens
400domain_requiredA domain_auth monitor has no domain.
400emails_requiredA list_health monitor has no emails.
400invalid_emailsAddresses failed the syntax check. details.invalid_sample lists up to 10.
400too_many_emailsMore than 5,000 addresses.
400no_changes, invalid_frequencyThe update sent nothing to change, or an unknown frequency.
400run_failedA run now could not start, for example for lack of credits.
401unauthorized, api_key_expiredThe key is missing, invalid, revoked or expired.
403insufficient_scopeThe credential lacks monitors:read or monitors:write.
403insufficient_creditsThe balance is zero.
404not_foundNo monitor with this id on your account.
422validation_errorname 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