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

# Validate an email address

> Looks up the domain's MX records and asks the highest-priority mail server whether it accepts mail for the address. Can take up to about 10 seconds when the recipient's mail server is slow. Counts against the plan's daily email check allowance, then welcome checks; checks that fail on our side (502, `fatal_exception`) don't count. The address is not stored.



## OpenAPI

````yaml /api-reference/openapi.yaml post /validate_email
openapi: 3.0.3
info:
  title: validate.al API
  description: >-
    Email validation, security scanning and account management, all at
    https://api.validate.al.
  version: '1.0'
servers:
  - url: https://api.validate.al/v1
security:
  - ApiKeyAuth: []
tags:
  - name: Email validation
  - name: Scanning
  - name: Account
  - name: Health
paths:
  /validate_email:
    post:
      tags:
        - Email validation
      summary: Validate an email address
      description: >-
        Looks up the domain's MX records and asks the highest-priority mail
        server whether it accepts mail for the address. Can take up to about 10
        seconds when the recipient's mail server is slow. Counts against the
        plan's daily email check allowance, then welcome checks; checks that
        fail on our side (502, `fatal_exception`) don't count. The address is
        not stored.
      operationId: validateEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  description: >-
                    The address to check. `Name <user@example.com>` is accepted
                    and reduced to the address.
                  example: someone@example.com
      responses:
        '200':
          description: >-
            The check ran. `status` holds the verdict, including when the
            address can't receive mail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
              examples:
                deliverable:
                  summary: Mail server accepts the address
                  value:
                    cached: false
                    email: someone@example.com
                    status: true
                refused:
                  summary: Mail server refuses the address
                  value:
                    cached: false
                    email: nobody@example.com
                    status: false
                noDomain:
                  summary: Domain does not exist
                  value:
                    cached: false
                    email: a@no-such-domain.example
                    status: domain_not_found
                badFormat:
                  summary: Not an email address
                  value:
                    email: not-an-email
                    status: invalid_format
        '400':
          description: >-
            Missing `email` field, body is not JSON, or the address can't be
            parsed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailError'
              example:
                detail:
                  error: Missing 'email' field in request body
        '401':
          description: Missing, wrong, replaced or deactivated API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailError'
              example:
                detail:
                  error: Invalid API key
        '429':
          $ref: '#/components/responses/LimitReached'
        '502':
          description: The validation service did not respond. Retry later.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: 'Upstream error: timed out'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    ValidationResult:
      type: object
      required:
        - email
        - status
      properties:
        email:
          type: string
          description: The address that was checked.
        status:
          description: >-
            `true` if the mail server accepts the address, `false` if it refuses
            it, or a string when no verdict could be reached.
          oneOf:
            - type: boolean
            - type: string
              enum:
                - invalid_format
                - domain_not_found
                - no_mx_records
                - smtp_connect_error
                - smtp_timeout
                - blocked_by_provider
                - fatal_exception
        cached:
          type: boolean
          description: >-
            True when served from a recent identical check. Absent when the
            format check failed.
    EmailError:
      description: Errors from the email validator.
      type: object
      properties:
        detail:
          type: object
          properties:
            error:
              type: string
    LimitError:
      type: object
      properties:
        detail:
          type: object
          properties:
            error:
              type: string
              example: Daily scan limit reached. It resets at 2026-10-05T00:00:00Z.
            limit:
              type: string
              enum:
                - scan
                - email check
            resets_at:
              type: string
              format: date-time
              example: '2026-10-05T00:00:00Z'
  responses:
    LimitReached:
      description: >-
        The plan's daily allowance (and any credits or welcome checks) is used
        up. Retry after `Retry-After` seconds, at `resets_at` (00:00 UTC).
      headers:
        Retry-After:
          description: Seconds until the allowance resets.
          schema:
            type: integer
            example: 3600
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LimitError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your validate.al API key, from the portal (Settings → API Key).
    BearerAuth:
      type: http
      scheme: bearer
      description: JWT from sign-in or registration.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.