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

# Verify Single Email

> Verify a single email address in real-time. Returns status, substatus, and enrichment data immediately. Costs 0.2 credits.

Use this endpoint to verify a single email address in real-time. OrbiSearch checks DNS records, MX records, and the target mail server to determine whether the mailbox exists and is accepting mail. The response includes a `status`, a detailed `substatus`, a plain-English `explanation`, domain-level signals (`mx_record`, `is_domain_catch_all`, `is_secure_email_gateway`), and enrichment flags such as `is_disposable` and `is_role_account`.

See the [response schema](/docs/api-reference/response-schema) for the meaning of each `status` and `substatus` value.

## Rate limits

This endpoint is rate-limited to **20 requests per second** per API key. Exceeding this limit returns a `429 Too Many Requests` response. See [errors](/docs/api-reference/errors) for how to handle rate limit responses.


## OpenAPI

````yaml GET /v1/verify
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)


    **Rate limiting:** requests are limited per API key (20 requests per second
    by default). Every response includes `X-RateLimit-Limit`,
    `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describing the
    current per-key window so clients can self-throttle; `429` responses also
    include a `Retry-After` header with the suggested backoff in seconds.
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/verify:
    get:
      tags:
        - Public API v1
      summary: Verify Single Email
      description: >-
        Verify a single email address in real-time by probing DNS, MX, and the

        target mail server. Returns `status`, `substatus`, a plain-English

        `explanation`, the detected `email_provider`, and enrichment flags

        (`is_disposable`, `is_role_account`, `is_free`).


        Costs 0.2 credits per verification. Results are cached for 24 hours —

        identical queries within that window are returned from cache at no
        credit

        cost. On timeout you receive a `status=unknown` / `substatus=timeout`

        result (HTTP 200), so automated workflows can continue without branching
        on

        status codes. Credits are refunded only when the verification service is

        unavailable (HTTP 502).


        Rate limit: 20 requests per second per API key. For larger workloads
        prefer

        the asynchronous `/v1/bulk` endpoint.
      operationId: verify_single_email_v1_verify_get
      parameters:
        - name: email
          in: query
          required: true
          schema:
            type: string
            minLength: 3
            maxLength: 320
            description: Email address to verify.
            examples:
              - jane.doe@acme.com
            title: Email
          description: Email address to verify.
        - name: timeout
          in: query
          required: false
          schema:
            type: integer
            maximum: 97
            minimum: 3
            description: Timeout in seconds (3-97).
            examples:
              - 70
            default: 97
            title: Timeout
          description: Timeout in seconds (3-97).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailVerificationResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example:
                detail: API key required in X-API-Key header
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Insufficient credits
          content:
            application/json:
              example:
                detail: Insufficient credits. You have 0.15 credits but need 0.2.
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '422':
          description: Invalid request parameters
          content:
            application/json:
              example:
                detail: 'Missing required query parameter: email.'
                errors:
                  - loc: query.email
                    msg: 'Missing required query parameter: email.'
                    type: missing
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: >-
                Seconds the client should wait before retrying. Computed from
                the remaining rate-limit window (typically 1 for the per-second
                limit, longer when the limit is exceeded by 3x or more); for
                endpoints with a daily quota, seconds until the quota resets.
              schema:
                type: integer
                examples:
                  - 1
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
          content:
            application/json:
              example:
                detail: >-
                  Rate limit exceeded. Maximum 20 requests per second per API
                  key. Contact us to discuss higher limits.
                code: rate_limited
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EmailVerificationResponse:
      properties:
        email:
          type: string
          title: Email
          description: The email address that was verified.
          examples:
            - jane.doe@acme.com
        status:
          type: string
          enum:
            - safe
            - risky
            - invalid
            - unknown
          pattern: ^(safe|risky|invalid|unknown)$
          title: Status
          description: >-
            Overall verification status: safe (deliverable), risky (uncertain),
            invalid (undeliverable), unknown (verification failed).
          examples:
            - safe
        substatus:
          anyOf:
            - type: string
            - type: 'null'
          title: Substatus
          description: >-
            Specific reason for the status (e.g., deliverable, catch_all,
            policy_blocked, mailbox_not_found, invalid_syntax, greylisted,
            timeout).
          examples:
            - deliverable
        explanation:
          type: string
          title: Explanation
          description: Plain-English explanation of the verification result.
          examples:
            - Safe to email. The mailbox exists and is deliverable.
        email_provider:
          type: string
          title: Email Provider
          description: >-
            Email service provider (Google Workspace, Gmail, Microsoft Outlook,
            etc.).
          examples:
            - Google Workspace
        mx_record:
          anyOf:
            - type: string
            - type: 'null'
          title: Mx Record
          description: >-
            The main mail server the domain uses to receive email. Null if the
            domain has no mail server configured — when that happens,
            `substatus` will be `no_mx_records`.
          examples:
            - aspmx.l.google.com
        is_domain_catch_all:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Domain Catch All
          description: >-
            True if the domain accepts mail for any username (catch-all). Null
            if we could not determine whether the domain is catch-all.
          examples:
            - false
        is_secure_email_gateway:
          type: boolean
          title: Is Secure Email Gateway
          description: >-
            True if the domain is protected by a secure email gateway —
            Proofpoint, Mimecast, Barracuda, or Trend Micro.
          default: false
          examples:
            - false
        is_disposable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Disposable
          description: >-
            True if this is a temporary/disposable email service, false if not,
            null if unknown.
          examples:
            - false
        is_role_account:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Role Account
          description: >-
            True if this is a generic role-based email (info@, support@, etc.),
            false if not, null if unknown.
          examples:
            - false
        is_free:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Free
          description: >-
            True if this is from a free email provider (gmail.com, yahoo.com,
            etc.), false if not, null if unknown.
          examples:
            - false
        confidence:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Confidence
          description: >-
            How certain we are in the verdict on a 0–100 scale. Filter on this
            orthogonally to status. For safe results: 99 = high confidence
            deliverable; 98 = same, but the domain is fronted by a Secure Email
            Gateway (Mimecast/Proofpoint/Barracuda/TrendMicro) which may filter
            post-acceptance; 97 = directory hit without app reachability signal
            — the address exists but carries post-acceptance bounce risk. risky
            / invalid = 99 (certain in the negative verdict). unknown = 0 (we
            genuinely don't know). null when the score is unattributable (e.g.
            no tracked winning method on a safe verdict — defensive).
          examples:
            - 99
      type: object
      required:
        - email
        - status
        - explanation
        - email_provider
      title: EmailVerificationResponse
      description: Verification result for a single email address.
      example:
        confidence: 99
        email: jane.doe@acme.com
        email_provider: Google Workspace
        explanation: Safe to email. The mailbox exists and is deliverable.
        is_disposable: false
        is_domain_catch_all: false
        is_free: false
        is_role_account: false
        is_secure_email_gateway: false
        mx_record: aspmx.l.google.com
        status: safe
        substatus: deliverable
    ApiErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable description of what went wrong.
          examples:
            - API key required in X-API-Key header
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Stable machine-readable error code, present on conditions a client
            may want to branch on (for example `rate_limited` for the per-second
            limit versus `daily_quota_exceeded` for the daily cap). Absent on
            errors that need no further disambiguation.
          examples:
            - daily_quota_exceeded
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/ValidationErrorDetail'
              type: array
            - type: 'null'
          title: Errors
          description: >-
            Individual validation failures, one entry per invalid parameter or
            field. Present only on 422 responses; when the request has a single
            problem, `detail` carries the same message. Absent on all other
            error codes.
      type: object
      required:
        - detail
      title: ApiErrorResponse
      description: Error response body.
    ValidationErrorDetail:
      properties:
        loc:
          type: string
          title: Loc
          description: >-
            Where in the request the problem is, as a dot-separated path (e.g.
            `query.email`, `body.0`).
          examples:
            - query.email
        msg:
          type: string
          title: Msg
          description: Human-readable description of this validation error.
          examples:
            - 'Missing required query parameter: email.'
        type:
          type: string
          title: Type
          description: >-
            Machine-readable error category (e.g. `missing`, `less_than_equal`,
            `string_too_long`).
          examples:
            - missing
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationErrorDetail
      description: One request-validation failure.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key for authentication
      in: header
      name: X-API-Key

````