API docs

Public REST API: authentication, endpoints, error dictionary, sandbox key.

Authentication

Send an Authorization: Bearer <key> header with every request. You generate keys while signed in (Settings → API keys). The API never creates keys, so a stolen key can't mint more of itself.

curl https://your-domain.com/api/v1/verify \
  -H "Authorization: Bearer cl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"name@example.com"}'

Sandbox key

A key starting with cl_test_ never reaches the worker and never touches credits. Send the test addresses to try each status: ok@sandbox.test, invalid@sandbox.test, catch_all@sandbox.test, disposable@sandbox.test, role@sandbox.test, unknown@sandbox.test. Every other address returns unknown, so a test key left in production never approves a real address.

Endpoints

Seven endpoints, all outside the [locale] prefix, like this page:

POST/api/v1/verifyVerify a single email, returns instantly.
POST/api/v1/listsCreate a bulk list from a JSON array.
GET/api/v1/lists/:idGet a list's status.
GET/api/v1/lists/:id/resultsGet a list's results.
DELETE/api/v1/lists/:idDelete a list permanently (GDPR).
GET/api/v1/creditsGet the remaining credit balance.
POST / GET / DELETE/api/v1/webhooksRegister, list, or remove a webhook endpoint.

Error dictionary

Every error has the same shape: { error: { code, message, request_id } }. The code is one of the values below.

unauthorized401Key is missing or invalid.
forbidden403The key isn't allowed for this action (e.g. a publishable key querying the balance).
not_found404The record doesn't exist or isn't yours. Either way you get 404, never 403.
invalid_request400The body doesn't match the expected schema.
insufficient_credits402Credit balance is too low.
rate_limited429Request limit exceeded. Wait the time given in the Retry-After header.
too_large413Body size exceeds the limit.
internal500Server error, retry.

Idempotency

Send an Idempotency-Key header and a second request with the same key returns the first successful response unchanged. Errors are not stored: after a 4xx or 5xx the same key runs the request again. The same key with a different body returns 400. While the first request is still running, a second one gets 429 with Retry-After: 1; retry and you get the first response. The stored response never contains an email address.

Rate limit

Each key currently gets 60 requests per minute, measured on a sliding 60-second window. Past that, you get a 429 with a Retry-After header.

A publishable (browser) key also starts at most 500 verifications per 24 hours by default; you change that on the API keys screen. Past it, requests get a 429 and cost no credit.

Ready-made integrations

Check these before calling the API directly:

  • Mailchimp sync: pull a list, verify it, write tags back (Settings → Integrations).
  • Webhook: a signed POST when a bulk job finishes (X-Clearlist-Signature).
Email Verification API Documentation | CleanBounceList