Skip to content
Truval Docs

Email verify

Endpoint

Section titled “Endpoint”
POST https://api.truval.dev/v1/email/verify

Request

Section titled “Request”

Headers

Section titled “Headers”
HeaderValue
AuthorizationBearer sk_live_...
Content-Typeapplication/json

Body

Section titled “Body”
FieldTypeRequiredDescription
emailstringYesThe email address to verify

Example

Section titled “Example”
Terminal window
curl https://api.truval.dev/v1/email/verify \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

Response

Section titled “Response”

Fields

Section titled “Fields”
FieldTypeDescription
emailstringThe email address that was verified
validbooleantrue if the address passed all checks
statusstringSee status values below
confidencefloat0–1 score of deliverability confidence
failed_checkstring|nullWhich layer failed: syntax · disposable · no_mx · smtp
disposablebooleanMatched against 50k+ throwaway domain blocklist
rolebooleanRole address — admin@, info@, noreply@ etc
free_providerbooleanGmail, Yahoo, Hotmail etc
catch_allbooleanServer accepts all addresses regardless of mailbox
smtp_blockedbooleanProvider blocks SMTP probing — Gmail, Outlook, Yahoo
mx_foundbooleanMX records exist for the domain
mx_hoststring|nullPrimary MX hostname
suggestionstring|nullTypo correction e.g. "gmail.com" when input was "gnail.com"
latency_msnumberEnd-to-end processing time in milliseconds

Status values

Section titled “Status values”
ValueMeaning
deliverableSMTP probe returned 250 — mailbox exists
undeliverableSMTP probe returned 550 — mailbox does not exist
unknownCould not confirm — server timed out, greylisted, or smtp_blocked is true
catch_allServer accepts all addresses — mailbox existence unconfirmable
invalidFailed syntax, disposable, or MX check

Example response

Section titled “Example response”
{
  "email": "user@example.com",
  "valid": true,
  "status": "deliverable",
  "confidence": 0.97,
  "failed_check": null,
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "smtp_blocked": false,
  "mx_found": true,
  "mx_host": "mail.example.com",
  "suggestion": null,
  "latency_ms": 187
}

Error responses

Section titled “Error responses”
StatusErrorMeaning
401Missing API keyNo Authorization header
401Invalid API keyKey not found or revoked
400Invalid requestRequest body is missing or malformed
429—Rate limit exceeded

Verification layers

Section titled “Verification layers”

Each request runs through five layers in order. The first failure exits immediately — no wasted compute.

  1. Syntax — regex + RFC 5321 checks (local part length, consecutive dots, etc). Returns in 0ms.
  2. Disposable — KV lookup against 50k+ throwaway domains. Returns in under 1ms.
  3. MX lookup — DNS-over-HTTPS query for MX records, cached 6 hours. Returns in 20–80ms.
  4. SMTP probe — TCP connection to the mail server, RCPT TO check without sending email. 1500ms timeout.
  5. Signals — role detection, free provider flag, typo suggestion. 0ms, pure local logic.

A note on Gmail and major providers

Section titled “A note on Gmail and major providers”

Gmail, Outlook, Yahoo, and iCloud block SMTP probing from all third-party services. This is not a Truval limitation — it affects every email verification provider.

For these domains, Truval verifies the MX records and domain authenticity (layers 1–3), then returns:

{
  "valid": false,
  "status": "unknown",
  "confidence": 0.75,
  "smtp_blocked": true
}

A confidence of 0.75 means: the domain is real, not disposable, has valid MX records, but we cannot confirm the specific mailbox. This is the most honest answer possible.