Source: https://www.cleanmylist.io/developers
Markdown source: https://www.cleanmylist.io/developers.md
Description: Email verification over REST or MCP, with OAuth 2.1, API-key authentication, structured verdicts, and an OpenAPI contract.

# Email verification API

Verify a single email address with one HTTP call:

```bash
curl https://www.cleanmylist.io/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "sasha@thoughtbox.io"}'
```

Every response is one JSON object with a verdict, a confidence score, a
`reason_code`, and a plain-English reason.

## Endpoints

- `POST /v1/verify` — verify a single address (real-time, for signup forms).
- `POST /v1/verify/bulk` — verify up to 100 addresses in one call.
- `GET /v1/jobs` — list recent async verification jobs.
- `POST /v1/jobs` — create an async verification job for a full list.
- `GET /v1/jobs/:id` — inspect job status and analysis.
- `POST /v1/jobs/:id/start` — confirm and run a job, spending plan allowance or credits.
- `GET /v1/jobs/:id/results` — download CSV or paginated JSON results.
- `GET /v1/openapi.json` — the OpenAPI contract (machine-readable, no auth required).

## Model Context Protocol

Connect an AI client to https://www.cleanmylist.io/mcp. Interactive clients use
OAuth 2.1 authorization-code flow with S256 PKCE; headless automation can
send a workspace API key as a Bearer token. OAuth discovery starts at
https://www.cleanmylist.io/.well-known/oauth-protected-resource/mcp.

The MCP tool catalog is generated from the REST OpenAPI operations, and
tool calls execute the matching `/v1` route so validation, billing,
tenant isolation, errors, and response shapes keep one implementation.

## Notes for agents and integrators

- REST auth is a Bearer API key created in the dashboard under API keys.
- Verdicts are `deliverable`, `risky`, `undeliverable`, or `unknown`, always with a reason.
- For full CSV cleaning prefer the dashboard list runner or the jobs API, not the bulk endpoint.