FOR DEVELOPERS

Email verification API.

Use a single-address check for forms, or asynchronous tasks for client lists. Keep your existing email provider.

START WITH ONE ADDRESS

Your first request.

Use the free demo endpoint without a key. It is rate limited and intended for trying the service.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

For paid checks, buy a package and use /v1/fast-verify with your key in X-API-Key. Keep keys out of URLs, source control and analytics.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Python example

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Node.js example

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

A LIST IN, RESULTS OUT

Verify a larger list.

POST /v1/tasks

Submit up to 10,000 addresses per task. Keep the returned task ID and inspect accepted, skipped and invalids: not every input is necessarily queued. Duplicates, malformed and suppressed addresses can be removed, and a low balance can cause partial acceptance.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

Poll the status, then fetch each result page. A response containing only invalid inputs can have an empty task ID; do not poll it.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Completed task results are JSON. Continue fetching pages until the full accepted list has been retrieved. For automated completion, pass a webhook with mode: "completed" when creating the task.

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

Consult the schema for webhook configuration and signature verification before enabling it in production.

UNDERSTAND THE RESPONSE

Format is not existence.

These are separate signals. A well-formed address can still be nonexistent, disposable or impossible to confirm.

Field	Meaning
`valid`	The address passed syntax validation. This alone does not confirm its mailbox.
`exists`	The mailbox probe result. Interpret it together with errors and catch-all signals.
`disposable`	The domain was recognised as a temporary email provider.
`accept_all`	The server accepts arbitrary addresses; the specific mailbox cannot be reliably confirmed.
`error_category`	Explains a failure or risk, such as no_mx, risky, or a temporary server issue.
`permanent_error`	A permanent failure was returned during the check. A temporary failure should not be treated as a permanent rejection.
`ttl`	A retry/cache timing hint in seconds when returned.

Verification cannot guarantee delivery, eliminate complaints, or prove ownership of a mailbox.

Know your balance.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

The response includes remaining, reserved and used credits, key type and expiration. A standard verification uses one credit; actual filtering and charging depend on the route and task acceptance. Check the response before treating a complete uploaded list as processed.

A 429 response means requests are being limited. Back off before retrying. Other errors can be returned as JSON or text in the current API; do not interpret HTTP errors as verification results.

The verification contract.

Download OpenAPI JSON

The public contract covers demo, fast verification, tasks, task status, results and account balance. Delivery and admin endpoints are outside this verification reference.

Need help connecting your platform? support@zbounce.net