Bulk Email Verification

Last Updated: August 15th, 2022.

The Bulk email verification API allows you to verify a list of emails in one go.
Bulk email verification is only available with self-hosting, i.e. for users under the Commercial License plan. To learn about self-hosting, read 🏠Self-Host Guide. Bulk email verification is not available on the 10K email SaaS plan.

Get Started

  • A PostgreSQL database, you can start for free with Heroku.
When running the Reacher backend, set the environment variable RCH_ENABLE_BULK=1, and set DATABASE_URL=<your_postgres_db>. For example, if running with docker, run
docker run \
	-e DATABASE_URL=<your_postgres_db> \
	-p 8080:8080 \
The DATABASE_URL value should look like postgres://<user>:<password>@<hostname>/<db_name>.
You should see the backend running with the following logs:
[2022-08-15T19:54:23Z INFO  reacher] Running Reacher v0.4.0
[2022-08-15T19:54:23Z INFO  reacher] Bulk endpoints enabled.
Server is listening on

How does Bulk email verification work?

Flow chart describing the bulk verification process.
Flow chart describing the bulk verification process.
Bulk email verification is done in 3 steps:

1. Submit a list of emails: POST /v0/bulk

The body of the request contains the list of emails, as well as a couple of configuration options.
    // Required fields:
    "input_type": "array",             // Must be "array". Future versions might allow CSV uploading.
    "input": [                         // Endpoint accepts a list of emails.

    // All fields below are optional:
    "proxy": {
        "host": "my.proxy.com",
        "port": "9080",
        "username": "user",           // Optional authentication for proxy.
        "password": "pass",
    "hello_name": "my.domain.com",    // The value to use in the EHLO handshake.
    "from_email": "me@my.domain.com", // The value to use in the MAIL FROM command.
    "smtp_ports": [25, 587]           // List of SMT ports to try for each email. Defaults to [25].
If successful, this endpoint will return a unique job ID, used to track the progress of the bulk verification job and fetch its results.
    "job_id": 150970

2. Verify the status of the job: GET /v0/bulk/{job_id}

If the list of emails is long, then the bulk verification job can take some time. Ping regularly on the endpoint above to see the status of the job.
When the job is still running, the job_status will be Running:
    "job_id": 150970,                            // From previous step.
    "created_at": "2017-04-15T20:00:06:00.000Z", // Start time of the job.
    "finished_at": null,                         // Stays `null` as long as job is still running.
    "total_records": 24606,
    "total_processed": 10,                       // Shows job progress.
    "summary": {                                 // Summary of the list's health.
        "total_safe": 5,
        "total_invalid": 2,
        "total_risky": 2,
        "total_unknown": 1
    "job_status": "Running"                      // Wait for "Completed".
And when the job is finished, we get job_status = Completed, and the finished_at field will be populated with the job’s end time.

3. Download the job results: GET /v0/bulk/{job_id}/results

Once the job_status field in from the previous step is Completed, this endpoint will show the results of all the emails in the list. The email’s result fields are documented in 📬Email Attributes inside JSON.
    "results": [
          "input": "someone@gmail.com",
          "is_reachable": "risky",
          // --snip: all fields--
      // --snip: other results--
💡 Pro Tip: You can also download the results as CSV, by passing the following query paramter: GET /v0/bulk/{job_id}/results?format=csv.

Questions ?

This Bulk email verification feature is still new, so feel free to send me an email ✉️ amaury@reacher.email for any questions.