openapi: 3.0.3
info:
  title: Data Checks Email Validation API
  version: "1.0"
  description: |
    This API validates and assesses email addresses in real time to ensure high data
    quality across online forms, CRMs, and internal workflows. It operates across multiple
    verification tiers, performing rapid syntax and domain checks (MX records),
    identifying disposable domains and role-based accounts (e.g., info@, sales@). For
    ultimate accuracy, the API conducts a live SMTP RCPT check to confirm the specific
    inbox exists and is actively receiving mail, allowing systems to instantly eliminate
    bounced emails, optimize user signups and maintain a clean contact database.

servers:
  - url: https://api.data-checks.com

security:
  - bearerAuth: []

paths:
  /v1/email:
    post:
      operationId: validateEmail
      summary: Validate an email address
      tags:
        - Email validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailValidationRequest"
            examples:
              mailbox:
                summary: Mailbox depth
                value:
                  email: Test@Example.com
                  level: mailbox
                  allow_role_address: false
              domain:
                summary: Domain depth (default)
                value:
                  email: user@example.com
                  level: domain
      responses:
        "200":
          description: Validation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailValidationResponse"
              example:
                input: Test@Example.com
                normalized: test@example.com
                is_valid: true
                reason: mailbox_found
                remaining_credits: 99
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                missing:
                  value:
                    error: missing_api_key
                invalid:
                  value:
                    error: invalid_api_key
        "402":
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: insufficient_credits
        "403":
          description: Key restriction or browser key mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                ip:
                  value:
                    error: ip_not_allowed
                browserKey:
                  value:
                    error: browser_side_key_required
                originRequired:
                  value:
                    error: origin_required
                originNotAllowed:
                  value:
                    error: origin_not_allowed
        "422":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              example:
                error: validation_failed
        "429":
          description: Rate or daily limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                rate:
                  value:
                    error: rate_limit_exceeded
                daily:
                  value:
                    error: daily_limit_exceeded
        "503":
          description: Service unavailable (empty body)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from the dashboard (API Keys). Prefix with `Bearer `.

  schemas:
    EmailValidationRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          maxLength: 255
          description: Address to validate.
        level:
          type: string
          enum:
            - domain
            - mailbox
          default: domain
          description: Validation depth.
        allow_role_address:
          type: boolean
          default: false
          description: Allow shared inboxes such as info@ or sales@.

    EmailValidationResponse:
      type: object
      required:
        - input
        - normalized
        - is_valid
        - reason
        - remaining_credits
      properties:
        input:
          type: string
          description: Original submitted value.
        normalized:
          type: string
          nullable: true
          description: Lower-case trimmed email.
        is_valid:
          type: boolean
        reason:
          type: string
          enum:
            - syntax
            - is_disposable
            - is_role
            - domain_found
            - domain_not_found
            - mailbox_found
            - domain_accepts_all
            - mailbox_not_found
        remaining_credits:
          type: integer
          description: Email credits remaining after this validation.

    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
