openapi: 3.1.0
info:
  title: emailvalidation
  version: "1"
  summary: Real-time email address validation and verification.
  description: >-
    emailvalidation checks whether an email address is deliverable, returning
    syntax, MX, SMTP, disposable, role, free-provider and quality signals. All
    endpoints are served over HTTPS and return JSON. Authenticate every request
    with your API key, either as the `apikey` query parameter or the `apikey`
    request header.


    This document is generated from the emailvalidation service implementation
    and is the machine-readable source of truth for the v1 REST API. A
    human-readable version is available at https://emailvalidation.io/docs.
  contact:
    name: emailvalidation support
    email: support@emailvalidation.io
  x-logo:
    url: https://emailvalidation.io/emailvalidation_logo.svg
servers:
  - url: https://api.emailvalidation.io
    description: Production
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
tags:
  - name: Validation
    description: Email address validation.
  - name: Metadata
    description: Account status.
paths:
  /v1/info:
    get:
      tags:
        - Validation
      summary: Validate an email address
      operationId: getInfo
      description: >-
        Validates a single email address and returns deliverability signals
        including syntax, MX, SMTP check, disposable/role/free classification, a
        quality score and an overall state.
      parameters:
        - name: email
          in: query
          required: true
          description: The email address to validate.
          schema:
            type: string
            format: email
          example: "support@emailvalidation.io"
        - name: catch_all
          in: query
          required: false
          description: >-
            When `1`, performs a catch-all check on the domain and populates the
            `catch_all` field (otherwise `catch_all` is `null`).
          schema:
            type: boolean
      responses:
        '200':
          description: Validation result.
          headers:
            X-RateLimit-Limit-Quota-Month:
              $ref: '#/components/headers/RateLimitLimitQuotaMonth'
            X-RateLimit-Remaining-Quota-Month:
              $ref: '#/components/headers/RateLimitRemainingQuotaMonth'
            X-Cost:
              $ref: '#/components/headers/Cost'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidationResult'
              example:
                email: "support@emailvalidation.io"
                user: "support"
                tag: ""
                domain: "emailvalidation.io"
                smtp_check: true
                mx_found: true
                did_you_mean: ""
                role: true
                disposable: false
                score: 0.64
                state: "deliverable"
                reason: "valid_mailbox"
                free: false
                format_valid: true
                catch_all: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/status:
    get:
      tags:
        - Metadata
      summary: Account quota status
      operationId: getStatus
      description: >-
        Returns your current monthly and grace quota usage. Requests to this
        endpoint do not count against your quota or rate limit.
      responses:
        '200':
          description: Current quota usage for the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                account_id: 313373133731337
                quotas:
                  month: { total: 300, used: 72, remaining: 228 }
                  grace: { total: 0, used: 0, remaining: 0 }
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key passed as the `apikey` query parameter.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: >-
        API key passed as the `apikey` request header. Recommended, as it keeps
        the key out of URLs and access logs.
  headers:
    RateLimitLimitQuotaMonth:
      description: Your monthly request quota.
      schema: { type: integer }
      example: 300
    RateLimitRemainingQuotaMonth:
      description: Remaining requests in your monthly quota.
      schema: { type: integer }
      example: 228
    Cost:
      description: Requests this call counted against your quota.
      schema: { type: integer }
      example: 1
  responses:
    Unauthorized:
      description: An API key was supplied but is invalid.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example:
            message: "If you specify an apikey it has to be a valid one."
    ValidationError:
      description: One or more request parameters failed validation.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ValidationError' }
          example:
            message: "Validation error"
            errors:
              email:
                - "The email must be a valid email address."
            info: "For more information, see documentation: https://emailvalidation.io/docs/status-codes#_422"
    RateLimited:
      description: You have exceeded your monthly quota or minute rate limit.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example:
            message: "You have reached your monthly limit, please upgrade your plan"
  schemas:
    EmailValidationResult:
      type: object
      properties:
        email:
          type: string
          description: The email address that was validated.
          example: "support@emailvalidation.io"
        user:
          type: string
          description: The local part before the @ (excluding any +tag).
          example: "support"
        tag:
          type: string
          description: The +tag portion of the local part, if any.
          example: ""
        domain:
          type: string
          example: "emailvalidation.io"
        smtp_check:
          type: boolean
          description: Whether the mailbox accepted the SMTP check.
        mx_found:
          type: boolean
          description: Whether MX records were found for the domain.
        did_you_mean:
          type: string
          description: A suggested correction for likely typos; empty when none.
          example: ""
        role:
          type: boolean
          description: Whether this is a role address (e.g. support@, info@).
        disposable:
          type: boolean
          description: Whether the domain is a known disposable email provider.
        score:
          type: number
          description: Overall quality/confidence score between 0 and 1.
          example: 0.64
        state:
          type: string
          description: Overall deliverability state.
          enum: [deliverable, undeliverable, risky, unknown]
        reason:
          type: string
          description: The reason behind the state.
          enum:
            - valid_mailbox
            - invalid_mailbox
            - invalid_mx
            - invalid_format
            - invalid_smtp
            - low_quality
            - low_deliverability
            - unavailable_smtp
            - timeout
            - unexpected_error
            - no_connect
        free:
          type: boolean
          description: Whether the domain is a free email provider.
        format_valid:
          type: boolean
          description: Whether the address is syntactically valid.
        catch_all:
          type: [boolean, "null"]
          description: >-
            Catch-all result for the domain. `null` unless `catch_all=1` was
            requested.
      required:
        - email
        - user
        - tag
        - domain
        - smtp_check
        - mx_found
        - did_you_mean
        - role
        - disposable
        - score
        - state
        - reason
        - free
        - format_valid
        - catch_all
    StatusResponse:
      type: object
      properties:
        account_id:
          type: integer
          example: 313373133731337
        quotas:
          type: object
          properties:
            month: { $ref: '#/components/schemas/QuotaBucket' }
            grace: { $ref: '#/components/schemas/QuotaBucket' }
          required: [month]
      required: [quotas]
    QuotaBucket:
      type: object
      properties:
        total: { type: integer, example: 300 }
        used: { type: integer, example: 72 }
        remaining: { type: integer, example: 228 }
    Error:
      type: object
      properties:
        message: { type: string }
        info: { type: string }
      required: [message]
    ValidationError:
      type: object
      properties:
        message: { type: string, example: "Validation error" }
        errors:
          type: object
          additionalProperties:
            type: array
            items: { type: string }
        info: { type: string }
      required: [message, errors]
