emailverifier-dev Verification API

openapi: 3.2.0
info:
  title: emailverifier.dev Verification 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: Verification
  description: Verify complete email addresses.
paths:
  /api/v1/verify:
    post:
      tags:
      - Verification
      operationId: verifyEmailAddress
      summary: Verify one email address
      description: Send only an email address. With a project API key, one successful call consumes one project credit. Without a key, the public demo allows 10 requests per hour. Project IDs are resolved from API keys and are never accepted from clients.
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              additionalProperties: false
              properties:
                email:
                  type: string
                  maxLength: 254
                  example: hello@example.com
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
          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
        '400':
          description: Invalid request body or email field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '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'
        '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:
    VerificationResult:
      type: object
      example:
        email: hello@example.com
        status: undeliverable
        action: block
        flagged: true
        signals:
        - no_mail_server
        suggestion: null
      required:
      - email
      - status
      - action
      - flagged
      - signals
      - suggestion
      additionalProperties: false
      properties:
        email:
          type: string
          example: hello@example.com
        status:
          type: string
          enum:
          - deliverable
          - risky
          - undeliverable
          - unknown
          description: Deliverable means the server accepted the recipient, not guaranteed delivery or proof the mailbox exists. Catch-all acceptance remains deliverable/review with the catch_all_domain signal. Risky includes disposable addresses. Unknown means evidence is incomplete or conflicting.
        action:
          type: string
          enum:
          - block
          - allow
          - review
          description: Recommended default handling. Allow can accompany an unknown status when the available evidence supports accepting the address; it does not confirm current delivery or ownership. Review preserves uncertain addresses such as catch-all domains without blocking them.
        flagged:
          type: boolean
          example: false
          description: True when the recommended action is block; false when it is allow or review.
        signals:
          type: array
          description: 'invalid_syntax: The address format is invalid.


            invalid_domain: The domain format is invalid.


            no_mail_server: The domain has no usable mail routing.


            disposable_address: This domain provides disposable email addresses.


            free_provider: This is a personal email provider.


            role_address: This is a shared role address, such as support or sales.


            mailbox_accepts_mail: The mail server accepted this recipient during the check. Delivery is not guaranteed.


            mailbox_rejected: The mail server explicitly rejected this recipient as nonexistent.


            catch_all_domain: The server also accepted a random address. This mailbox could not be confirmed.


            possible_typo: The domain may contain a typo. Check the suggested address.


            verification_inconclusive: The available evidence could not confirm or reject this mailbox.


            catch_all_check_inconclusive: The server accepted the recipient, but the catch-all check could not finish conclusively.


            dns_unavailable: The mail-routing DNS lookup could not finish. Try again later.


            smtp_timeout: The mail server did not respond in time. Try again later.


            smtp_connection_failed: The connection to the mail server could not finish. Try again later.


            smtp_temporary_failure: The mail server temporarily deferred the check. Try again later.


            smtp_policy_block: The mail server restricted the check. This does not mean the address is invalid.


            smtp_cannot_verify: The mail server could not confirm this recipient.


            smtp_conflict: The mail servers returned conflicting evidence. This mailbox could not be confirmed.


            verification_unavailable: Mailbox verification is temporarily unavailable. Try again later.'
          items:
            type: string
            enum:
            - invalid_syntax
            - invalid_domain
            - no_mail_server
            - disposable_address
            - free_provider
            - role_address
            - mailbox_accepts_mail
            - mailbox_rejected
            - catch_all_domain
            - possible_typo
            - verification_inconclusive
            - catch_all_check_inconclusive
            - dns_unavailable
            - smtp_timeout
            - smtp_connection_failed
            - smtp_temporary_failure
            - smtp_policy_block
            - smtp_cannot_verify
            - smtp_conflict
            - verification_unavailable
        suggestion:
          type:
          - string
          - 'null'
          example: null
          description: Corrected address for a recognized provider typo.
    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.
    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
    ValidationError:
      type: object
      required:
      - statusCode
      - statusMessage
      - data
      properties:
        statusCode:
          type: integer
          example: 400
        statusMessage:
          type: string
          example: Email is required.
        data:
          type: object
          required:
          - field
          properties:
            field:
              type: string
              example: email
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer