Skip to main content

​
Overview

Verify a single email address in real time and return deliverability signals such as syntax, domain, SMTP, and inbox checks.

​
POST /api/v1/verify

Purpose: perform realtime verification of a single email address (syntax, domain, SMTP, inbox checks).

​
Request

Headers:
  • Content-Type: application/json
  • X-Request-ID: <string> (optional): request identifier for attribution/tracing.
Body:
  • email (string, required): email address to verify.
Example request: 
curl -X POST \
  'https://api.boltroute.ai/api/v1/verify' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com"}'

​
Response

Status: 200 OK (or 408 Request Timeout with partial results) Example response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "status": "valid",
  "is_role_based": false,
  "is_disposable": false,
  "has_mx_records": true,
  "has_reverse_dns": true,
  "domain_name": "example.com",
  "host_name": "mx1.example.com",
  "server_type": "smtp",
  "is_catchall": false,
  "validated_at": "2025-01-01T12:00:00Z",
  "unknown_reason": null,
  "needs_physical_verify": false
}
Response fields:
  • id: UUID of the stored verification record when available.
  • email: the verified email address.
  • status: overall verification result. Values: valid, invalid, catchall, invalid_syntax, disposable_domain, unknown.
  • is_role_based: true if the local part is a role account (e.g., support@).
  • is_disposable: true if domain is known disposable.
  • has_mx_records: true if the domain has MX records.
  • has_reverse_dns: true if reverse DNS records exist for the mail host.
  • domain_name: resolved domain name.
  • host_name: mail host (MX) used for SMTP.
  • server_type: mail server type reported by verifier.
  • is_catchall: true if domain accepts any address.
  • validated_at: RFC3339 timestamp of verification completion.
  • unknown_reason: reason when status is unknown.
  • needs_physical_verify: true when inbox check requires manual/physical verification.
Notes:
  • Credits: deducts 1 credit when the resulting status is not unknown and the request is not inside the same-user/same-email free-repeat window.
  • unknown results are free.
  • Same user + same canonical email (trimmed/lowercased) within 24 hours is free-repeat (no additional deduction), including cached responses.
  • Cached responses are billed only when outside the free-repeat window.
  • X-Request-ID is optional and used for attribution; charge idempotency is enforced by a server-generated deterministic key per user/email in 5-minute UTC windows.
Errors:
  • 400 invalid body or email syntax.
  • 401 unauthorized (missing/invalid auth).
  • 402 insufficient credit balance.
  • 408 verification timed out.
  • 429 rate limited.
  • 500 internal error.