# Monitor a list on a schedule

`POST /api/v1/email/monitors`

- Authentication: Secret API key as a bearer token
- Billing: Creation is free. Each run bills every address like a single lookup — 1 credit for a fresh deliverable or risky verdict; undeliverable, suppressed and 7-day repeats are free.
- Group: Monitors

Saves up to 500 addresses and re-verifies them every week or every month. The first run starts right away and only sets the baseline; from the next run on, every address that was deliverable last time and no longer is counts as decayed and is reported to the account's email. Runs honor the suppression list and the 7-day repeat cache, so a stable list costs little to keep watching.

Answers `201` with the monitor. The baseline run is queued, not finished: poll the monitor for `last_run_at` and `last_summary`.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | A label for the dashboard and the decay alerts. At most 100 characters. |
| `emails` | string[] | yes | 1 to 500 addresses; each item at most 254 characters. |
| `cadence` | string | yes | How often the list is re-verified. One of: weekly, monthly. |

## Example request

```bash
curl -X POST https://spaw.co/api/v1/email/monitors \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Newsletter list",
  "emails": [
    "mia@acme.com",
    "ben@acme.com"
  ],
  "cadence": "weekly"
}'
```

## Responses

### 201 — The monitor was saved and its baseline run queued.

```json
{
    "success": true,
    "data": {
        "monitor": {
            "id": 41,
            "name": "Newsletter list",
            "cadence": "weekly",
            "email_count": 2,
            "next_run_at": "2026-09-10T10:12:44+00:00",
            "last_run_at": null,
            "last_summary": null,
            "created_at": "2026-09-03T10:12:44+00:00"
        }
    }
}
```

### 401 — The key is missing, malformed, or revoked.

```json
{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 422 — The request body could not be validated; `error.errors` lists the fields.

```json
{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 429 — Over 5 requests per second for the key. Retry after the limit resets.

```json
{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

## Error codes

- `UNAUTHENTICATED` — https://spaw.co/docs/errors/UNAUTHENTICATED
- `VALIDATION_FAILED` — https://spaw.co/docs/errors/VALIDATION_FAILED
- `RATE_LIMITED` — https://spaw.co/docs/errors/RATE_LIMITED

---

Canonical page: https://spaw.co/docs/api/create-monitor · OpenAPI document: https://spaw.co/openapi.json · All endpoints: https://spaw.co/docs/api