POST/tools/validate-emails
Batch email validation (up to 100 addresses). Same modes and credit rules as POST /tools/validate-email.
Rate class: validate_emails_batch (default 10/min). Optional Idempotency-Key (max 128).
Credits
Per-item rules match single validate. Top-level creditsCharged is the sum. Duplicate emails in one request may only bill once (workspace cache). Items that need ZeroBounce when the workspace is out of credits return per-item insufficient_credits; later free items (format, MX, cache) still run. The HTTP status stays 200.
Request
POST /tools/validate-emails
X-API-Key: sk_live_...
Content-Type: application/json
Idempotency-Key: demo-validate-batch-1
{
"emails": ["a@acme.com", "b@acme.com"],
"mode": "full"
}
| Field | Required | Notes |
|---|---|---|
emails | Yes | 1–100 strings. Oversized or non-string → 400. Bad format soft-fails as verdict: block per item |
mode | No | full (default) or mx — applies to every item |
Response
{
"results": [
{
"index": 0,
"email": "a@acme.com",
"status": "ok",
"creditsCharged": 1,
"verdict": "allow",
"format": { "ok": true },
"disposable": { "ok": true },
"mx": { "status": "valid", "domain": "acme.com" },
"zeroBounce": { "status": "valid", "subStatus": "", "source": "api" }
}
],
"summary": {
"total": 1,
"ok": 1,
"insufficient_credits": 0,
"failed": 0
},
"creditsCharged": 1
}
Per-item status: ok | insufficient_credits | failed.
Errors
| Error code | When |
|---|---|
validation_error | Empty list, over 100, unknown keys, or bad Idempotency-Key |
conflict | Idempotency mismatch or in progress |
rate_limited | validate_emails_batch RPM exceeded |
Unlike single validate, mid-batch credit exhaustion is HTTP 200 with per-item insufficient_credits (not envelope 403).
MCP
Tool: validate_emails.
Related
- Single: POST /tools/validate-email
- Limits: Credits & rate limits