Easy Email Verification Bulk Verification API

openapi: 3.2.0
info:
  title: Easy Email Verification Bulk 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: Bulk Verification
  description: Upload a list, follow the job, and download the results.
paths:
  /bulk/upload:
    post:
      tags:
      - Bulk Verification
      operationId: uploadBulkFile
      summary: Upload a list for bulk verification
      description: 'Uploads a TXT or CSV file with one email address per line and starts an asynchronous

        verification job. Lines that contain `@` and are longer than 5 characters are counted.

        The account needs enough credits for every counted line. Maximum file size: 16 MB.

        Poll `GET /bulk/status/{id}` and download the result with `GET /bulk/download/{id}`.'
      security:
      - xApiKey: []
      - apikeyHeader: []
      - authorizationHeader: []
      parameters:
      - $ref: '#/components/parameters/ApikeyHeader'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: TXT or CSV file, one email address per line.
      responses:
        '200':
          description: File accepted and job created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUploadAccepted'
        '400':
          description: Missing API key, or the file has no valid email addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkError'
        '401':
          $ref: '#/components/responses/BulkUnauthorized'
        '402':
          description: Not enough credits for the number of addresses in the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkError'
              example:
                status: error
                message: You are running out of your credit limit.
        '500':
          description: The file could not be read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkError'
  /bulk/status:
    get:
      tags:
      - Bulk Verification
      operationId: listBulkJobs
      summary: List the bulk jobs of the account
      security:
      - xApiKey: []
      - apikeyHeader: []
      - authorizationHeader: []
      parameters:
      - $ref: '#/components/parameters/ApikeyHeader'
      responses:
        '200':
          description: Jobs of the account that owns the API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkJobList'
        '400':
          $ref: '#/components/responses/BulkMissingKey'
        '401':
          $ref: '#/components/responses/BulkUnauthorized'
  /bulk/status/{id}:
    get:
      tags:
      - Bulk Verification
      operationId: getBulkJob
      summary: Get the status of a bulk job
      security:
      - xApiKey: []
      - apikeyHeader: []
      - authorizationHeader: []
      parameters:
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/ApikeyHeader'
      responses:
        '200':
          description: Job status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkJobStatus'
        '400':
          $ref: '#/components/responses/BulkMissingKey'
        '401':
          $ref: '#/components/responses/BulkUnauthorized'
        '404':
          description: Job not found, or it belongs to another account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkError'
              example:
                status: error
                message: List not found
  /bulk/download/{id}:
    get:
      tags:
      - Bulk Verification
      operationId: downloadBulkResults
      summary: Download the results of a completed bulk job
      description: 'Returns the results as CSV with the header

        `Email,Result,Reason,Disposable,AcceptAll,Role,Free,User,Domain,MXRecord,DomainMX,IsSafeToSend,DidYouMean,Success,Message,HttpCode`.

        Jobs and their results are deleted automatically 30 days after upload.'
      security:
      - xApiKey: []
      - apikeyHeader: []
      - authorizationHeader: []
      parameters:
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/ApikeyHeader'
      responses:
        '200':
          description: 'CSV file (`Content-Disposition: attachment; filename=results.csv`).'
          content:
            text/plain:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BulkMissingKey'
        '401':
          $ref: '#/components/responses/BulkUnauthorized'
        '404':
          description: Job not found, not completed yet, or it belongs to another account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkError'
              example:
                status: error
                message: Processed file not found or not completed
  /bulk/{id}:
    delete:
      tags:
      - Bulk Verification
      operationId: deleteBulkJob
      summary: Delete a bulk job and its results
      security:
      - xApiKey: []
      - apikeyHeader: []
      - authorizationHeader: []
      parameters:
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/ApikeyHeader'
      responses:
        '200':
          description: Job deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleted'
        '400':
          $ref: '#/components/responses/BulkMissingKey'
        '401':
          $ref: '#/components/responses/BulkUnauthorized'
        '404':
          description: Job not found, or it belongs to another account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkError'
              example:
                status: error
                message: File not found
components:
  parameters:
    JobId:
      name: id
      in: path
      required: true
      description: Job id (`list_id`) returned by `POST /bulk/upload`.
      schema:
        type: string
      example: 1ec74e7f-77d4-4d21-ab4b-7256b2d2c943
    ApikeyHeader:
      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
  responses:
    BulkMissingKey:
      description: No API key, or the sandbox key (not supported on bulk endpoints).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BulkError'
          example:
            status: error
            message: Missing authentication header
    BulkUnauthorized:
      description: Unknown API key, or a widget-only key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BulkError'
          example:
            status: error
            message: Invalid or missing API key
  schemas:
    BulkJobList:
      type: object
      required:
      - status
      - total_lists
      - lists
      properties:
        status:
          type: string
          enum:
          - ok
        total_lists:
          type: integer
        lists:
          type: array
          items:
            type: object
            required:
            - list_id
            - filename
            - status
            properties:
              list_id:
                type: string
              filename:
                type: string
              status:
                $ref: '#/components/schemas/BulkJobStatusValue'
              uploaded_at:
                type:
                - string
                - 'null'
                format: date-time
              completed_at:
                type:
                - string
                - 'null'
                format: date-time
              emails_total:
                type: integer
                format: int64
              emails_valid:
                type: integer
                format: int64
              emails_invalid:
                type: integer
                format: int64
    BulkUploadAccepted:
      type: object
      required:
      - status
      - list_id
      - filename
      - uploaded
      - message
      properties:
        status:
          type: string
          enum:
          - accepted
        list_id:
          type: string
          description: Job id used by the other bulk endpoints.
          example: 1ec74e7f-77d4-4d21-ab4b-7256b2d2c943
        filename:
          type: string
          example: leads.csv
        uploaded:
          type: integer
          format: int64
          description: Number of addresses counted in the file.
          example: 1200
        message:
          type: string
          example: File accepted for processing
    BulkJobStatus:
      type: object
      required:
      - list_id
      - status
      - progress
      properties:
        list_id:
          type: string
        status:
          $ref: '#/components/schemas/BulkJobStatusValue'
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Percentage processed.
        started_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Upload time.
        estimated_finish:
          type:
          - string
          - 'null'
          format: date-time
          description: Completion time once the job is completed; null before that.
        totals:
          type:
          - object
          - 'null'
          description: Counters; null before processing starts.
          properties:
            total:
              type: integer
              format: int64
            processed:
              type: integer
              format: int64
            valid:
              type: integer
              format: int64
            invalid:
              type: integer
              format: int64
            unknown:
              type: integer
              format: int64
    BulkError:
      type: object
      required:
      - status
      - message
      properties:
        status:
          type: string
          enum:
          - error
        message:
          type: string
    BulkDeleted:
      type: object
      required:
      - status
      - list_id
      - message
      properties:
        status:
          type: string
          enum:
          - deleted
        list_id:
          type: string
        message:
          type: string
          example: File permanently removed
    BulkJobStatusValue:
      type: string
      enum:
      - queued
      - processing
      - completed
      - failed
      - deleted
      - not_enough_credits
      - unknown
      description: '`not_enough_credits`: processing stopped because the account ran out of credits.

        '
  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