Email Verifier API Verification API

openapi: 3.1.0
info:
  title: Email Verifier Verification API
  version: '2.0'
  description: 'Real-time email verification API offering a 16-point verification engine that combines

    syntax checking, MX record lookup, SMTP handshake, mailbox existence probing, catch-all

    detection, greylisting handling, disposable address detection, role-account flagging,

    spam-trap detection, gibberish detection, and B2B / B2C classification. The service is

    designed to eliminate hard bounces, protect sender reputation, and improve deliverability

    for marketing, transactional, and lead-generation email programs.


    The API is delivered as a single endpoint at `https://emailverifierapi.com/v2/`. The

    endpoint accepts both GET and POST requests and returns either JSON (default) or XML

    (when `xml=true` is passed). Authentication is performed by sending the customer''s

    `apiKey` as a query parameter.


    Verification is metered against a credit balance. Credits are consumed only for

    "Paid" events (mailbox-level results that required SMTP probing). Lightweight,

    deterministic events such as syntax errors or DNS misses are returned for free and

    do not consume credits. Each successful response includes a `remaining` field with

    the up-to-date credit balance and an `execution` field with the wall-clock cost of

    the verification.'
  contact:
    name: Email Verifier API Support
    email: support@emailverifierapi.com
    url: https://emailverifierapi.com/
  termsOfService: https://emailverifierapi.com/terms-of-service/
  license:
    name: Proprietary
    url: https://emailverifierapi.com/terms-of-service/
servers:
- url: https://emailverifierapi.com/v2
  description: Production
security:
- apiKeyQuery: []
tags:
- name: Verification
  description: Real-time email-address verification operations.
paths:
  /:
    get:
      tags:
      - Verification
      operationId: verifyEmailGet
      summary: Verify Email Address
      description: 'Run the 16-point verification engine against a single email address and return a

        deliverability verdict (`status`), a granular event code (`event`), a human-readable

        explanation (`details`), and a set of intelligence flags (disposable, role account,

        free service, spam-trap, gibberish, offensive). When the input domain is misspelled

        a corrected suggestion is returned in `emailSuggested`.


        The GET form is convenient for ad-hoc validation, link-time integrations, and

        spreadsheets / no-code tools. Use POST for higher-volume server-to-server traffic

        where the email payload should not appear in URL strings or access logs.'
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/Email'
      - $ref: '#/components/parameters/Xml'
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
              examples:
                mailboxExists:
                  $ref: '#/components/examples/MailboxExists'
                mailboxDoesNotExist:
                  $ref: '#/components/examples/MailboxDoesNotExist'
                isDisposable:
                  $ref: '#/components/examples/IsDisposable'
            application/xml:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Verification
      operationId: verifyEmailPost
      summary: Verify Email Address (POST)
      description: 'Same as the GET form but accepts the email address either as a query parameter or

        as a form-encoded body. Recommended for production server-to-server usage so that

        addresses do not leak into proxy access logs.'
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/Xml'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to verify.
                  example: john.doe@example.com
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
            application/xml:
              schema:
                $ref: '#/components/schemas/VerificationResult'
components:
  parameters:
    Email:
      name: email
      in: query
      required: true
      description: Email address to verify.
      schema:
        type: string
        format: email
        example: john.doe@example.com
    Xml:
      name: xml
      in: query
      required: false
      description: Set to `true` to receive an XML response payload instead of JSON.
      schema:
        type: boolean
        default: false
    ApiKey:
      name: apiKey
      in: query
      required: true
      description: Customer API key.
      schema:
        type: string
  schemas:
    VerificationResult:
      type: object
      description: Outcome of a single email-address verification.
      properties:
        status:
          type: string
          description: "Top-level deliverability verdict.\n  * `passed` - mailbox accepts mail and is safe to send to.\n  * `failed` - mailbox / domain / mx is invalid; do not send.\n  * `unknown` - server is catch-all or greylisting; result is indeterminate.\n  * `transient` - temporary failure; retry later."
          enum:
          - passed
          - failed
          - unknown
          - transient
        event:
          type: string
          description: "Fine-grained event code describing the verification outcome.\n  * `mailboxExists` - mailbox confirmed (paid).\n  * `mailboxDoesNotExist` - mailbox does not exist (paid).\n  * `mailboxIsFull` - mailbox is over quota (paid).\n  * `domainDoesNotExist` - domain has no DNS record (free).\n  * `mxServerDoesNotExist` - domain has no MX server (free).\n  * `invalidSyntax` - address is malformed (free).\n  * `isCatchall` - server accepts all addresses (free).\n  * `isGreylisting` - server is greylisting; retry later (free).\n  * `transientError` - temporary error during verification (free)."
          enum:
          - mailboxExists
          - mailboxDoesNotExist
          - mailboxIsFull
          - domainDoesNotExist
          - mxServerDoesNotExist
          - invalidSyntax
          - isCatchall
          - isGreylisting
          - transientError
        details:
          type: string
          description: Human-readable explanation of the event.
          example: The mailbox exists.
        email:
          type: string
          format: email
          description: Email address that was verified.
          example: john.doe@example.com
        emailSuggested:
          type: string
          description: Corrected address when a domain typo is detected.
          nullable: true
          example: john.doe@gmail.com
        mailbox:
          type: string
          description: Local part of the address.
          example: john.doe
        domain:
          type: string
          description: Domain part of the address.
          example: example.com
        mxIp:
          type: string
          description: IPv4 address of the resolved mail exchange server.
          example: 142.250.190.27
        mxLocation:
          type: string
          description: ISO 3166-1 alpha-2 country code where the MX server is hosted.
          example: US
        possibleSpamtrap:
          type: boolean
          description: Address matches known spam-trap or honeypot patterns.
        isComplainer:
          type: boolean
          description: Address belongs to a user who frequently marks mail as spam.
        isDisposable:
          type: boolean
          description: Address belongs to a known disposable / burner provider.
        isFreeService:
          type: boolean
          description: Address is hosted on a free consumer mailbox provider (Gmail, Yahoo, etc.).
        isOffensive:
          type: boolean
          description: Address local-part contains profanity or offensive language.
        isRoleAccount:
          type: boolean
          description: Address is a role / departmental alias such as `info@`, `sales@`, or `support@`.
        isGibberish:
          type: boolean
          description: Address local-part appears to be machine-generated (keyboard smash).
        remaining:
          type: string
          description: Customer credit balance remaining after this request.
          example: '9942'
        execution:
          type: number
          format: float
          description: Wall-clock execution time of the verification, in seconds.
          example: 0.368
      required:
      - status
      - event
      - details
      - email
      - mailbox
      - domain
      - remaining
      - execution
    Error:
      type: object
      description: Error envelope returned for non-2xx responses.
      properties:
        status:
          type: string
          example: failed
        event:
          type: string
          example: invalidApiKey
        details:
          type: string
          example: The supplied API key is invalid or has no remaining credits.
  examples:
    IsDisposable:
      summary: Disposable address detected (free event)
      value:
        status: failed
        event: mailboxDoesNotExist
        details: The mailbox does not exist.
        email: throwaway@mailinator.com
        emailSuggested: null
        mailbox: throwaway
        domain: mailinator.com
        mxIp: 198.51.100.10
        mxLocation: US
        possibleSpamtrap: false
        isComplainer: false
        isDisposable: true
        isFreeService: false
        isOffensive: false
        isRoleAccount: false
        isGibberish: false
        remaining: '9940'
        execution: 0.221
    MailboxExists:
      summary: Mailbox confirmed (paid event)
      value:
        status: passed
        event: mailboxExists
        details: The mailbox exists.
        email: john.doe@gmail.com
        emailSuggested: null
        mailbox: john.doe
        domain: gmail.com
        mxIp: 142.250.190.27
        mxLocation: US
        possibleSpamtrap: false
        isComplainer: false
        isDisposable: false
        isFreeService: true
        isOffensive: false
        isRoleAccount: false
        isGibberish: false
        remaining: '9942'
        execution: 0.368
    MailboxDoesNotExist:
      summary: Mailbox does not exist (paid event)
      value:
        status: failed
        event: mailboxDoesNotExist
        details: The mailbox does not exist.
        email: not.a.real.user@gmail.com
        emailSuggested: null
        mailbox: not.a.real.user
        domain: gmail.com
        mxIp: 142.250.190.27
        mxLocation: US
        possibleSpamtrap: false
        isComplainer: false
        isDisposable: false
        isFreeService: true
        isOffensive: false
        isRoleAccount: false
        isGibberish: false
        remaining: '9941'
        execution: 0.412
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
      description: 'API key issued at signup. Pass as the `apiKey` query string parameter on every

        request. Treat the key as a credential and rotate from the customer dashboard

        if exposed.'