Credits and billing

EmailValidator uses a credit system. Each validated email address costs one credit.

On this page

How charging works

Credits are deducted when the work is accepted, not when the result comes back:

  • POST /api/v1/verify deducts one credit when the check is submitted — before it runs, and whether you wait for the result synchronously or collect it later.
  • POST /api/v1/verify/batch deducts one credit per valid email row when the job starts, at upload time. The charged field in the response is the number actually billed.

Charging up front is what lets the API answer 402 immediately instead of accepting work it cannot pay for. Rows that could not be processed are refunded when the job finishes, and a job that fails outright is refunded in full — a refund lands back on the same balance it was taken from (free credits refund to free, paid to paid).

Checking your balance

GET /api/v1/credits
X-Api-Key: ev_your_key

200 OK:

{
  "credits_remaining": 4817,
  "free_credits": 317,
  "paid_credits": 4500
}

credits_remaining is the sum of free_credits and paid_credits. It is null for system and demo accounts.

Free credits are spent before paid ones.

Insufficient credits

When a request would exceed your balance, the API returns 402 and does no work.

POST /api/v1/verify/batch tells you exactly how short you are, in machine-readable fields — so you can top up by shortfall and retry without parsing prose:

{
  "status": 402,
  "code": "insufficient_credits",
  "error": "Insufficient credits.",
  "shortfall": 5,
  "balance": 5,
  "required": 10
}

POST /api/v1/verify returns the plain error envelope — a single check costs one credit, so there is nothing to itemise:

{
  "status": 402,
  "code": "insufficient_credits",
  "error": "Insufficient credits."
}

Top up your balance in the dashboard, then retry. If you sent an Idempotency-Key with the rejected request you may safely reuse it: a 402 releases the key rather than pinning it. See Idempotency.

Test mode

Test-mode keys (beginning with ev_test_) cost zero credits. Use them for integration tests and CI pipelines. See Test mode.