POST/tools/validate-email
Validate one email address with layered deliverability checks (format, disposable domain, DNS MX, optional ZeroBounce). Campaign-agnostic — no lead or campaign id required.
Rate class: validate_email (default 60/min). Optional Idempotency-Key (max 128). A replay is stored only for HTTP 200. A 403 insufficient_credits does not stick to the key.
Credits
| Mode | Credits |
|---|---|
mx | Always 0 (format → disposable → DNS MX) |
full (default) | 1 only when the ZeroBounce HTTP API returns a usable status. Cache hits, disabled vendor, errors, and earlier short-circuits → 0 |
Insufficient balance when a ZeroBounce call is required → 403 insufficient_credits (never HTTP 402), before the vendor call.
Request
POST /tools/validate-email
X-API-Key: sk_live_...
Content-Type: application/json
Idempotency-Key: demo-validate-1
{ "email": "info@acme.com", "mode": "full" }
| Field | Required | Notes |
|---|---|---|
email | Yes | Max 254 |
mode | No | full (default) or mx |
Unknown body keys → 400 validation_error.
Response
{
"email": "info@acme.com",
"mode": "full",
"verdict": "allow",
"format": { "ok": true },
"disposable": { "ok": true },
"mx": { "status": "valid", "domain": "acme.com" },
"zeroBounce": { "status": "valid", "subStatus": "", "source": "api" },
"creditsCharged": 1
}
| Field | Notes |
|---|---|
verdict | allow | block | unknown |
zeroBounce.source | api | cache | disabled | error | skipped |
mx.status | valid | invalid | transient | skipped |
creditsCharged | 0 or 1 |
Errors
| Error code | When |
|---|---|
validation_error | Bad body, unknown keys, or invalid Idempotency-Key |
insufficient_credits | mode=full needs a ZeroBounce call and balance is below 1 |
conflict | Idempotency mismatch or in progress |
rate_limited | validate_email RPM exceeded |
MCP
Tool: validate_email.
Related
- Batch: POST /tools/validate-emails
- Website context: POST /tools/enrich-website
- Limits: Credits & rate limits