Realtime verification

​

Overview

​

POST /api/v1/verify

​

Request

• Content-Type: application/json
• X-Request-ID: <string> (optional): request identifier for attribution/tracing.

• email (string, required): email address to verify.

curl -X POST \
  'https://api.boltroute.ai/api/v1/verify' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com"}'

​

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
}

• 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.

• 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.

• 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.