Developers

Email verification API.

The same scoring engine that powers bulk runs, exposed as a small HTTP API. Validate email addresses in real time, right in your signup form.

Get an API key OpenAPI JSON →

POST /v1/verify

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

Endpoints

Realtime checks and full-list jobs.

Verify addresses synchronously or create, start, inspect, and download an asynchronous bulk job.

Method	Path	What it does
POST	/v1/verify	Verify a single address
POST	/v1/verify/bulk	Verify up to 100 addresses synchronously
GET	/v1/jobs	List recent verification jobs
POST	/v1/jobs	Create a bulk verification job
GET	/v1/jobs/{id}	Get a job's status and analysis
POST	/v1/jobs/{id}/start	Confirm and run a job (debits credits)
GET	/v1/jobs/{id}/results	Download job results
GET	/v1/openapi.json	Fetch the OpenAPI contract.

MCP

Use the same API from your AI client.

Connect to one remote endpoint. OAuth 2.1 is the recommended interactive flow; workspace API keys remain available for headless and local automation.

The MCP catalog is generated from the REST OpenAPI operations, and every tool call runs through the matching /v1 route. Billing, tenant isolation, validation, and response shapes therefore have one owner.

Remote endpoint

https://www.cleanmylist.io/mcp

OAuth clients discover authorization automatically. To use an API key, send it as a Bearer token as shown here.

Scopes: mcp:read for job status and results, mcp:write for checks and job starts. An API key carries both.
Approval: A workspace owner or admin approves the grant and picks the workspace it applies to.
Revoking: Connections are listed on your API keys page and can be revoked at any time. They also revoke automatically when the granting member loses admin access. Setup guide →

{
  "mcpServers": {
    "cleanmylist": {
      "url": "https://www.cleanmylist.io/mcp",
      "headers": {
        "Authorization": "Bearer ${CML_KEY}"
      }
    }
  }
}

verify_email: Verify a single address
verify_emails: Verify up to 100 addresses synchronously
list_verification_jobs: List recent verification jobs
create_verification_job: Create a bulk verification job
get_verification_job: Get a job's status and analysis
start_verification_job: Confirm and run a job (debits credits)
get_verification_job_results: Download job results

Batch checks

Verify a small batch in one request.

Use the bulk endpoint for signup imports and small forms. For full CSV cleaning, use the dashboard list runner.

POST /v1/verify/bulk

curl https://www.cleanmylist.io/v1/verify/bulk \
  -H "Authorization: Bearer $CML_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["one@example.com","two@example.com"]}'

Response shape

One JSON object, every time.

Every verification returns the same shape — a verdict, a score, the reason, and a per-stage breakdown. The fields are stable; we add, we never remove.

verdict — deliverable | risky | undeliverable
score — 0 to 100, with feature contributions on request
reason — single canonical string for the verdict
checks — per-stage signals, useful for audit logs
latency_ms — total ms spent on the address
model_version — for reproducibility on re-verification

{
  "verdict": "deliverable",
  "score": 98,
  "reason": "All checks passed",
  "reason_code": "ok",
  "checks": [
    { "name": "syntax", "status": "pass", "message": "Syntax OK" },
    { "name": "mx_records", "status": "pass", "message": "MX records found" }
  ],
  "latency_ms": 657,
  "model_version": "v1.1-heuristic",
  "ran_at": "2026-05-18T10:22:18Z"
}

Examples

Copy-pasteable HTTP examples.

SDKs can come later. V1 keeps the public contract small and easy to call from any stack.

curlHTTP: curl -X POST https://www.cleanmylist.io/v1/verify ...
Node.jsfetch: await fetch('/v1/verify', { method: 'POST', ... })
Pythonhttpx: httpx.post('https://www.cleanmylist.io/v1/verify', ...)

Rate limits + reliability

Honest numbers, in writing.

Limits are per workspace, not per key. Need higher throughput or a dedicated probe pool? Talk to us — volume customers get bespoke limits.

P50 verify latency

Measuring

P99 verify latency

Measuring

Default rate limit

1,000 / min

Bulk API batch cap

100

Dashboard list cap

1,000,000

Status

Published

Ship a verify endpoint into your signup today.

Get an API key, add one HTTP call, and ship the diff before standup. We will refund the credits if it does not feel right.

Clean your list free Talk to us first