> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boltroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime verification

> Reference documentation for realtime verification.

## 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:

```bash theme={null}
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:

```json theme={null}
{
  "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.