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/verify | Verify a single email, returns instantly. |
| POST | /api/v1/lists | Create a bulk list from a JSON array. |
| GET | /api/v1/lists/:id | Get a list's status. |
| GET | /api/v1/lists/:id/results | Get a list's results. |
| DELETE | /api/v1/lists/:id | Delete a list permanently (GDPR). |
| GET | /api/v1/credits | Get the remaining credit balance. |
| POST / GET / DELETE | /api/v1/webhooks | Register, 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.
| unauthorized | 401 | Key is missing or invalid. |
| forbidden | 403 | The key isn't allowed for this action (e.g. a publishable key querying the balance). |
| not_found | 404 | The record doesn't exist or isn't yours. Either way you get 404, never 403. |
| invalid_request | 400 | The body doesn't match the expected schema. |
| insufficient_credits | 402 | Credit balance is too low. |
| rate_limited | 429 | Request limit exceeded. Wait the time given in the Retry-After header. |
| too_large | 413 | Body size exceeds the limit. |
| internal | 500 | Server 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).