API documentation
One endpoint does most of the work. Everything else is jobs, billing and polling a long job until it finishes.
curl -s -X POST "https://app.zapbounce.com/api/v1/verify" \
-H "X-API-Key: $ZB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"emails":["ada@example.com"]}'
{
"node": "verify-1",
"results": [
{
"id": "5821",
"email": "ada@example.com",
"status": "catch_all",
"reasonCode": "CATCH_ALL",
"provider": "other",
"flags": [],
"smtpCode": 250,
"checkedAt": "2026-10-26T10:02:41.000Z"
}
]
}Every result carries a status, a reasonCode from a closed list, the provider we detected and the literal smtpCode the server gave. An address we could not get an answer on comes back as unknown, and its credit is refunded. role, disposable and free_provider travel in a flagsarray, as flags about the address and never as statuses.
The four verdicts
These are the only values the status field takes. Branch on them. The reason codes underneath can grow, so treat one you don't recognize as extra detail.
valid
Valid
The mailbox accepted the address at the SMTP step.
invalid
Invalid
The server rejected the address outright.
catch_all
Catch-all
The domain accepts every address, so the mailbox cannot be confirmed.
unknown
Unknown
The server would not give a straight answer. We say so, and we do not bill it.
Reference
API authentication
Authenticate to the ZapBounce API with a scoped key in the X-API-Key header. Key prefixes, the four scopes, and why a key never belongs in a URL.
API error codes
Every error shape the ZapBounce API returns, the machine codes to branch on, whether a retry will help, and why a failed request never costs a credit.
API rate limits
How the ZapBounce API limits request rates, the headers that report the limit, and the backoff on a 429 that stops a retry storm from hurting your results.
API versioning
The ZapBounce API is versioned in the URL path. What the /v1 prefix means, which older unversioned paths still work, and how to parse responses safely.
Bulk verification endpoint
POST /v1/jobs submits up to 50,000 addresses for background verification. How a job is created, deduplicated and billed, and how to list your jobs.
Credits endpoint
GET /v1/credits/balance returns your credit balance and /ledger lists every grant, reservation and refund. What spends a credit and what comes back.
Idempotency keys
Send Idempotency-Key when you create a job so a retried request never creates a second job or spends credits twice, even when the first reply was lost.
Job status and results
GET /v1/jobs/{id} reports a job's progress and verdict counts. Read per-address rows, download CSV, cancel or delete a job, and what each status means.
Paginating results
List endpoints paginate with page and pageSize and return items plus a meta object. The limits, the response shape, and which routes use it.
Single verification endpoint
POST /v1/verify checks up to 20 addresses in real time: syntax, MX and the SMTP handshake. Every request and response field, billing and errors documented.
Verification result codes
ZapBounce's four statuses, eleven reason codes and three flags: what each one means, the SMTP behavior behind it, and which statuses spend a credit.
Before you build against this
Get a key and try it
100 free checks a month, no card.