API Reference

POST /v1/validate

Validate a single email address.

Request (application/json)

{ "email": "user@example.com", "timeout_ms": 4000, "deep": true }

Response (200)

deep (default true): enables SMTP-level verification in addition to syntax and MX checks. This confirms whether the mailbox can actually accept mail (no real email is sent).

Use deep: true for onboarding and database cleaning; omit or set to false for faster, MX-only validation.
timeout_ms (default 4000, range 500..10000): overall validation timeout.

smtp.checked shows if the SMTP probe ran; smtp.accepts_mail may be true, false, or null when probing is blocked. mx.records is an array and may be empty ([]).

POST /v1/bulk

Validate multiple addresses at once.

{ "emails": ["a@example.com", "b@test.com"], "parallel": 4, "timeout_ms": 4000, "deep": true }

Optional parallel parameter controls concurrency (1..16, default 4).

GET /v1/health

Health check endpoint to verify uptime.

{"status":"ok"}

Validation Errors

Example of a 422 response when input is invalid.

HTTP 422
{
  "detail": [
    { "loc": ["body", "email"], "msg": "value is not a valid email address", "type": "value_error.email" }
  ]
}