emailverifier-dev Domains API

openapi: 3.2.0
info:
  title: emailverifier.dev Domains API
  version: 1.6.0
  description: Verify email address quality with a technical status, recommended action, and the signals behind the result. Authenticated verification consumes one project credit.
servers:
- url: https://emailverifier.dev
tags:
- name: Domains
  description: Classify email domains.
paths:
  /api/v1/domains/{domain}:
    get:
      tags:
      - Domains
      operationId: classifyEmailDomain
      summary: Classify one email domain
      description: Returns the provider classification, risk level, and whether the domain appears able to receive email. Every authenticated domain check consumes one project credit, regardless of classification. Without a key, the public demo allows 10 requests per hour. It does not confirm a specific mailbox or message delivery.
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      - {}
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
          example: mailinator.com
      responses:
        '200':
          description: Domain classification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainClassification'
          headers:
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: ISO timestamp when the current window resets.
              schema:
                type: string
                format: date-time
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyAuthError'
        '402':
          description: Project has no credits remaining
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalanceExceeded'
        '404':
          description: Invalid domain path
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidDomainPathError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceeded'
          headers:
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: ISO timestamp when the current window resets.
              schema:
                type: string
                format: date-time
components:
  schemas:
    CreditBalanceExceeded:
      type: object
      required:
      - statusCode
      - statusMessage
      - data
      properties:
        statusCode:
          type: integer
          example: 402
        statusMessage:
          type: string
          example: Project has no credits remaining.
        data:
          type: object
          required:
          - remaining
          properties:
            remaining:
              type: integer
              example: 0
    ApiKeyAuthError:
      type: object
      required:
      - statusCode
      - statusMessage
      properties:
        statusCode:
          type: integer
          example: 401
        statusMessage:
          type: string
          example: Invalid API key.
    DomainClassification:
      type: object
      required:
      - domain
      - classification
      - risk
      - mail_routing
      additionalProperties: false
      properties:
        domain:
          type: string
          example: mailinator.com
        classification:
          type: string
          enum:
          - disposable
          - free_provider
          - unknown
        risk:
          type: string
          enum:
          - high
          - medium
          - unknown
        mail_routing:
          type: string
          enum:
          - available
          - unavailable
          - unknown
          description: Whether the domain appears able to receive email. This does not confirm a specific mailbox.
    RateLimitExceeded:
      type: object
      required:
      - statusCode
      - statusMessage
      - data
      properties:
        statusCode:
          type: integer
          example: 429
        statusMessage:
          type: string
          example: Rate limit exceeded.
        data:
          type: object
          required:
          - limit
          - resetAt
          properties:
            limit:
              type: integer
              example: 10
            resetAt:
              type: string
              format: date-time
    InvalidDomainPathError:
      type: object
      required:
      - statusCode
      - statusMessage
      properties:
        statusCode:
          type: integer
          example: 404
        statusMessage:
          type: string
          example: Invalid domain path
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer