- authentication
- Secret API key as a bearer token
- billing
- Each address bills like a single lookup — 1 credit for a fresh deliverable or risky verdict whose mailbox check was definite, an unverified answer free, an undeliverable one free within your email fair use and 1 credit past it (`fair_use_billed` on the item), everything else free — and the call stops cleanly where the balance ends.
Verifies a list synchronously under the exact single-lookup billing rules. Every address is prepared first, then all the mailbox probes that are still needed are sent to the verification provider together, so a full batch takes about as long as a handful of single lookups. data.results[] mirrors the single-address response per item, in input order, and each item's meta carries credits_used, cache_hit, suppressed, refreshed and fair_use_billed.
Addresses on your suppression list are served from the stored verdict at no cost and marked suppressed: true. Repeats inside the list are verified once. The list is walked in order and stops where the balance would run out: running out of credits mid-batch returns the paid partial results with meta.stopped_reason: "insufficient_credits" and processed lower than requested, never discarding billed work. Only a batch whose first lookup is refused answers the typed 402. A key with a daily credit cap stops the list the same way once the cap is spent: the addresses already paid for come back with meta.stopped_reason: "key_spend_cap", and a call that starts with the cap already spent answers 429 KEY_SPEND_CAP_REACHED and runs nothing.
A batch counts as one request against the rate limit. refresh, max_age and timeout work exactly as on the single-address endpoint and apply to every address in the list; each item's meta.refreshed says whether its earlier answer was discarded.
Every item carries index, its zero-based position in the list you sent, and input, the address exactly as you sent it. A batch stopped early by stopped_reason answers only a prefix of the list, so those two are what line an answer up with the row it came from.
Request body
| field | type | description |
|---|---|---|
| emailsrequired | string[] | 1 to 50 addresses; each item at most 254 characters. |
| refresh | boolean | null | Apply to every address — discard earlier answers, probe again, bill as fresh when answered. Repeats inside the list are still verified once. |
| max_age | integer | null | Seconds. Refresh only the addresses whose earlier answer is older than this. |
| timeout | integer | null | Seconds the mailbox handshake may wait, for every address in the call. |
Example request
curl -X POST https://spaw.co/api/v1/email/batch \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{
"emails": [
"[email protected]",
"[email protected]",
"[email protected]"
]
}'This endpoint has no console on its page. It bills once per item in the list, so what one run costs depends on what you paste in. The single-value endpoint for the same signal is runnable instead.
Responses
200One result per processed address, plus the batch totals.
{
"success": true,
"data": {
"results": [
{
"index": 0,
"input": "[email protected]",
"data": {
"email": "[email protected]",
"deliverable": "deliverable",
"reason": null,
"risk_score": 0,
"risk_level": "low"
},
"meta": {
"credits_used": 1,
"cache_hit": false,
"suppressed": false,
"refreshed": false,
"fair_use_billed": false
}
},
{
"index": 1,
"input": "[email protected]",
"data": {
"email": "[email protected]",
"deliverable": "risky",
"reason": "role",
"risk_score": 30,
"risk_level": "medium"
},
"meta": {
"credits_used": 1,
"cache_hit": false,
"suppressed": false,
"refreshed": false,
"fair_use_billed": false
}
},
{
"index": 2,
"input": "[email protected]",
"data": {
"email": "[email protected]",
"deliverable": "deliverable",
"reason": null,
"risk_score": 0,
"risk_level": "low"
},
"meta": {
"credits_used": 0,
"cache_hit": false,
"suppressed": false,
"refreshed": false,
"fair_use_billed": false
}
}
]
},
"meta": {
"requested": 3,
"processed": 3,
"credits_used": 2,
"credits_remaining": 7,
"stopped_reason": null,
"request_id": "req_01m1kgdrtqdvwnks99vfgx2rcw"
}
}401The key is missing, malformed, or revoked.
{
"success": false,
"error": {
"code": "UNAUTHENTICATED",
"message": "Provide a valid API key as a bearer token.",
"request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
}
}402The balance is empty. The lookup did not run.
{
"success": false,
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Your credit balance is empty.",
"request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
}
}422The request body could not be validated; `error.errors` lists the fields.
{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "The email field is required.",
"errors": {
"email": [
"The email field is required."
]
},
"request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
}
}429Over 5 requests per second for the key. Retry after the limit resets.
{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the limit resets.",
"request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
}
}Error codes
Failures answer { success: false, error: { code, message, request_id } }. Each code has its own page.