Easy Email Verification Single Verification API

openapi: 3.2.0
info:
  title: Easy Email Verification Single Verification API
  version: 1.2.0
  description: 'REST API to verify email addresses one at a time, in small batches, or as bulk lists.


    ## Authentication


    Every request needs an API key, created in the dashboard under

    API Settings.


    **Recommended:** send the key in the `X-API-Key` header.


    **Also supported** (all endpoints keep accepting them):


    - `apikey` query parameter (`GET /verify`, `GET /credits`)

    - `apikey` header (`POST /verify` and `/bulk/*`)

    - `Authorization` header, as `Authorization: ` or `Authorization: token `


    If a request carries more than one of them, `apikey` wins over `X-API-Key`, which wins

    over `Authorization`.


    Keys created for the JavaScript widget (keys with an authorized domain) are rejected

    by these endpoints with `401`.


    Keep API keys on a trusted server. Do not use them in browser or mobile code.


    ## Sandbox


    Use the public key `eev_sandbox_key` to test an integration without an account and

    without spending credits. It works on `GET /verify`, `POST /verify` and `GET /credits`,

    only accepts addresses at `sandbox.easyemailverification.com` (plus `typo@gmial.com`),

    and answers with fixed results chosen by the local part:


    | Address | Answer |

    | --- | --- |

    | `valid@sandbox.easyemailverification.com` | `valid`, `accepted_email` |

    | `invalid@sandbox.easyemailverification.com` | `invalid`, `rejected_email` |

    | `unknown@sandbox.easyemailverification.com` | `unknown`, `timeout` |

    | `disposable@sandbox.easyemailverification.com` | `valid`, `disposable: true` |

    | `catchall@sandbox.easyemailverification.com` | `valid`, `accept_all: true` |

    | `role@sandbox.easyemailverification.com` | `valid`, `role: true` |

    | `typo@gmial.com` | `invalid`, `did_you_mean: typo@gmail.com` |

    | `quota@sandbox.easyemailverification.com` | `402` (no credits) |

    | `ratelimit@sandbox.easyemailverification.com` | `429` (simulated) |


    Any other sandbox address returns `invalid`. Sandbox responses carry the header

    `X-EEV-Sandbox: true` and are limited to 60 requests per minute per IP.'
  contact:
    email: info@easyemailverification.com
  license:
    name: Easy Email Verification
    url: https://www.easyemailverification.com/
servers:
- url: https://api.easyemailverification.com/v1
tags:
- name: Single Verification
  description: Verify one address, or a batch of up to 50, synchronously.
paths:
  /verify:
    get:
      tags:
      - Single Verification
      operationId: verify
      summary: Verify a single email address
      description: 'Verifies one email address. Each verification consumes one credit, except when the

        receiving server could not be reached (`reason: no_connect`).


        `success: true` means the request was processed; it does not mean the address is

        deliverable. Use `result`, `reason` and `safe_to_send`. Do not treat `unknown` as `valid`.'
      security:
      - xApiKey: []
      - apikeyQuery: []
      - authorizationHeader: []
      parameters:
      - name: email
        in: query
        required: true
        description: Email address to verify. URL-encode it (for example `+` as `%2B`).
        schema:
          type: string
        example: john@gmail.com
      - name: apikey
        in: query
        required: false
        description: API key. Optional when the key is sent in a header (`X-API-Key` recommended).
        schema:
          type: string
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
              example:
                email: john@gmail.com
                result: invalid
                reason: rejected_email
                disposable: false
                accept_all: false
                role: false
                free: true
                user: john
                domain: gmail.com
                mx_record: gmail-smtp-in.l.google.com
                mx_domain: google.com
                safe_to_send: false
                did_you_mean: ''
                success: true
                message: 'Processing time: 812 ms'
                http_code: '200'
        '400':
          description: 'Missing API key (`message: "Apikey is null"`), empty `email`, or (sandbox key) an address

            outside the sandbox domain. When the `email` parameter is absent, the framework returns

            its default error body.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationError'
              examples:
                apikeyIsNull:
                  $ref: '#/components/examples/ApikeyIsNull'
        '401':
          description: Unknown API key, or a widget-only key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationError'
              examples:
                invalidKey:
                  $ref: '#/components/examples/InvalidKey'
                widgetKey:
                  $ref: '#/components/examples/WidgetKey'
        '402':
          description: The account has no credits left.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationError'
              examples:
                noCredits:
                  $ref: '#/components/examples/NoCredits'
        '429':
          description: Sandbox key only (sandbox rate limit or the simulated `ratelimit@` address).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationError'
    post:
      tags:
      - Single Verification
      operationId: verifyBatch
      summary: Verify a small batch of email addresses
      description: 'Verifies up to 50 email addresses in one request and returns one result per address.

        Each address consumes one credit, except `reason: no_connect`.

        For larger lists use the bulk endpoints.'
      security:
      - xApiKey: []
      - apikeyHeader: []
      - authorizationHeader: []
      parameters:
      - name: apikey
        in: header
        required: false
        description: API key. Optional when the key is sent in `X-API-Key` (recommended) or `Authorization`.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            example:
              emails:
              - john@gmail.com
              - mary@example.com
      responses:
        '200':
          description: One result per address, in the same shape as `GET /verify`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VerificationResult'
        '400':
          description: No API key, or (sandbox key) an address outside the sandbox domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationErrorList'
        '401':
          description: Unknown API key, or a widget-only key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationErrorList'
        '402':
          description: The account has no credits left.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationErrorList'
        '429':
          description: Too many addresses in one request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationErrorList'
              example:
              - email: null
                result: null
                reason: null
                disposable: false
                accept_all: false
                role: false
                free: false
                user: null
                domain: null
                mx_record: null
                mx_domain: null
                safe_to_send: false
                did_you_mean: ''
                success: false
                message: Too many requests. Rate limit exceeded. Max=50.
                http_code: '429'
components:
  schemas:
    BatchRequest:
      type: object
      required:
      - emails
      properties:
        emails:
          type: array
          maxItems: 50
          items:
            type: string
          description: Addresses to verify (maximum 50).
    VerificationResult:
      type: object
      description: Result of one verification. All fields are always present.
      required:
      - email
      - result
      - reason
      - disposable
      - accept_all
      - role
      - free
      - user
      - domain
      - mx_record
      - mx_domain
      - safe_to_send
      - did_you_mean
      - success
      - message
      - http_code
      properties:
        email:
          type:
          - string
          - 'null'
          description: Address that was verified, normalized to lowercase.
        result:
          type:
          - string
          - 'null'
          enum:
          - valid
          - invalid
          - unknown
          - null
          description: Overall result. Check `reason` for details.
        reason:
          type:
          - string
          - 'null'
          description: 'Detail of the result. Known values:

            `accepted_email` (SMTP server accepted the address),

            `rejected_email` (mailbox does not exist),

            `invalid_email` (invalid syntax),

            `invalid_domain` (domain does not exist),

            `no_mx_record` (domain has no MX record),

            `invalid_mx_record`,

            `no_connect` (could not connect to the receiving server; no credit is consumed),

            `timeout`, `unavailable_smtp`, `unexpected_error`,

            `temporarily_blocked` (greylisted), `exceeded_storage` (mailbox full).

            New values may be added; treat unknown values as inconclusive.

            '
          example: accepted_email
        disposable:
          type: boolean
          description: Known temporary/disposable address.
        accept_all:
          type: boolean
          description: Catch-all domain; it accepts any mailbox, so the address cannot be confirmed.
        role:
          type: boolean
          description: Role address such as support@ or postmaster@.
        free:
          type: boolean
          description: Address from a popular free provider (Gmail, Outlook, Yahoo...).
        user:
          type:
          - string
          - 'null'
          description: Local part of the address.
        domain:
          type:
          - string
          - 'null'
          description: Domain part of the address.
        mx_record:
          type:
          - string
          - 'null'
          description: MX host that receives mail for the domain.
        mx_domain:
          type:
          - string
          - 'null'
          description: Domain of the MX host.
        safe_to_send:
          type: boolean
          description: Whether the address is considered safe for sending.
        did_you_mean:
          type: string
          description: Suggested correction when a typo is detected; empty string otherwise.
        success:
          type: boolean
          description: Whether the request was processed. It does not mean the address is deliverable.
        message:
          type:
          - string
          - 'null'
          description: Error description, or processing information on success.
        http_code:
          type:
          - string
          - 'null'
          description: HTTP status code repeated in the body, as a string.
          example: '200'
    VerificationErrorList:
      description: 'Error response of `POST /verify`: a list with one error item.'
      type: array
      minItems: 1
      maxItems: 1
      items:
        $ref: '#/components/schemas/VerificationResult'
    VerificationError:
      description: 'Error response of `GET /verify`. Same shape as a result, with `success: false`.'
      allOf:
      - $ref: '#/components/schemas/VerificationResult'
  examples:
    InvalidKey:
      value:
        email: null
        result: null
        reason: null
        disposable: false
        accept_all: false
        role: false
        free: false
        user: null
        domain: null
        mx_record: null
        mx_domain: null
        safe_to_send: false
        did_you_mean: ''
        success: false
        message: Server can not verify your authentication to use API. Please check whether API key is proper or not.
        http_code: '401'
    NoCredits:
      value:
        email: null
        result: null
        reason: null
        disposable: false
        accept_all: false
        role: false
        free: false
        user: null
        domain: null
        mx_record: null
        mx_domain: null
        safe_to_send: false
        did_you_mean: ''
        success: false
        message: You are running out of your credit limit.
        http_code: '402'
    ApikeyIsNull:
      value:
        email: null
        result: null
        reason: null
        disposable: false
        accept_all: false
        role: false
        free: false
        user: null
        domain: null
        mx_record: null
        mx_domain: null
        safe_to_send: false
        did_you_mean: ''
        success: false
        message: Apikey is null
        http_code: '400'
    WidgetKey:
      value:
        email: null
        result: null
        reason: null
        disposable: false
        accept_all: false
        role: false
        free: false
        user: null
        domain: null
        mx_record: null
        mx_domain: null
        safe_to_send: false
        did_you_mean: ''
        success: false
        message: API key allowed only for form integration (Widget Javascript).
        http_code: '401'
  securitySchemes:
    xApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Recommended.
    apikeyQuery:
      type: apiKey
      in: query
      name: apikey
    apikeyHeader:
      type: apiKey
      in: header
      name: apikey
    authorizationHeader:
      type: apiKey
      in: header
      name: Authorization
      description: '`Authorization: <key>` or `Authorization: token <key>`.'
externalDocs:
  description: API reference
  url: https://www.easyemailverification.com/en-US/api/reference