Easy Email Verification Account API

openapi: 3.2.0
info:
  title: Easy Email Verification Account 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: Account
  description: Account information for the owner of the API key.
paths:
  /credits:
    get:
      tags:
      - Account
      operationId: getCredits
      summary: Remaining credits of the account
      description: Does not consume credits. With the sandbox key it returns fixed values.
      security:
      - xApiKey: []
      - apikeyQuery: []
      - authorizationHeader: []
      parameters:
      - 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: Remaining credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credits'
              example:
                success: true
                credits_remaining: 1250
                subscription_remaining: 250
                persistent_remaining: 1000
                subscription_credits: 500
        '400':
          description: No API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          description: Unknown API key, or a widget-only key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
components:
  schemas:
    SimpleError:
      type: object
      required:
      - success
      - message
      - http_code
      properties:
        success:
          type: boolean
          enum:
          - false
        message:
          type: string
        http_code:
          type: string
    Credits:
      type: object
      required:
      - success
      - credits_remaining
      - subscription_remaining
      - persistent_remaining
      - subscription_credits
      properties:
        success:
          type: boolean
        credits_remaining:
          type: integer
          format: int64
          description: Total verifications left (subscription + prepaid).
        subscription_remaining:
          type: integer
          format: int64
          description: Left in the current subscription period.
        persistent_remaining:
          type: integer
          format: int64
          description: Prepaid credits that do not expire with the period.
        subscription_credits:
          type: integer
          format: int64
          description: Credits granted per subscription period.
  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