POST /batches takes an array of addresses and returns immediately with a batch id. Verification happens in the background, paced against each receiving domain so we do not get our own probe traffic blocked, which would make your results worse.
Duplicates are collapsed before any connection opens. If the same address appears forty times in a list, it is checked once, returned forty times, and billed once. Your credit balance should match the number of distinct addresses we could resolve, never the row count of the file.
A batch of 10,000 usually finishes in minutes. A batch loaded with Yahoo-hosted and Microsoft-hosted domains takes longer, because those are the hosts that make us back off between probes.
curl https://api.zapbounce.com/v1/batches \
-H "Authorization: Bearer zb_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "q4-webinar-list",
"emails": ["ada@example.com", "grace@example.org"],
"webhook_url": "https://yourapp.com/hooks/zapbounce"
}'{
"batch_id": "bat_8f2c1d",
"status": "queued",
"submitted": 2,
"unique": 2,
"created_at": "2026-09-18T10:04:00Z"
}Fields
| Field | Type | What it carries |
|---|---|---|
| emails | array | Up to 100,000 per batch. Larger lists go through file upload instead. |
| name | string | Your label. It comes back on the status call and in the webhook, so use something you will recognize in three months. |
| webhook_url | string | Optional. We POST the completion event here instead of making you poll. |
| unique | integer | Distinct addresses after deduplication. This is the number that can be billed, minus whatever comes back unknown. |
An 8,400-row webinar export, start to finish
Say you export 8,400 registrants from a webinar tool. That's far under the 100,000 cap, so a JSON body is fine. You name the batch 2026-10-partner-webinar, attach a webhook_url, and send an Idempotency-Key built from your export job's id.
Back comes submitted: 8400 and unique: 8050. So 350 rows were repeats, mostly people who registered twice. Before you submit, compare your balance from GET /credits with the row count. The row count is the most the batch can cost, and a balance below it risks a 402.
When the batch completes, give every verdict a home before you open your email tool. Valid goes to the main send. Invalid goes to suppression. Catch-all gets its own segment, and unknown waits in a retry pile. Then apply the flags inside each pile: a role address follows whatever rule you've set, and a disposable one is dropped.
Splitting, deduping and resubmitting: what helps
Don't split one list into many small batches to make it faster. Pacing happens per receiving domain, so ten batches that all contain the same slow mail host wait on that host ten times over. You also burn through the ten-submissions-a-minute limit for nothing.
Skip the manual dedupe step if its only purpose is saving money, because repeats are collapsed and billed once anyway. Trimming spaces and lowercasing is still worth doing. This reference doesn't yet say whether Ada@Example.com and ada@example.com collapse into one, and cleaning them up first removes the question.
Resubmitting the unknown pile a day later is cheap, since unknowns weren't billed the first time and only a definitive verdict costs a credit. Greylisting and throttling are temporary, so some of those addresses will resolve. Addresses on hosts that accept everything by policy won't change, however many times you ask.
Questions developers ask
How large can one batch be?
100,000 addresses in the JSON body. Above that, upload a file and let us stream it.
Am I billed for duplicates?
No. We collapse them before checking and bill the distinct address once.
Can I cancel a running batch?
Yes, and you are billed for whatever finished before the cancel landed. The partial results stay available for download.
What if my list has 40% catch-all domains?
You will see that in the summary, which is the point. A verifier that returned those as valid would be selling you a nicer-looking number and the same bounces.