Reacher Help CenterReacher Help Center/💪Bulk Email Verification/
🥑/v0/bulk Email Verification
Search
🥑

/v0/bulk Email Verification

Last Updated: October 11th, 2023.
 
The Bulk email verification API allows you to verify a list of emails in one go. This document refers to the older /v0/bulk endpoints, which are available on Reacher backends v0.5.*.
 
❗
Bulk email verification is only available with the Commercial License Plan. To learn more, see 🎓Reacher Licenses. Bulk email verification is not available on the 10K email SaaS plan.

Get Started

Prerequesites:
  • A PostgreSQL database, you can start for free with Supabase.
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 RCH_ENABLE_BULK=1 \
	-e DATABASE_URL=<your_postgres_db> \
	-p 8080:8080 \
	reacherhq/backend
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 0.0.0.0:8080.

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.
        "support@reacher.email",
        "invalid@reacher.email"
    ],

    // 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, in given order. 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--
    ]
}
To avoid returning a huge JSON payload, the results array by default only returns the first 50 email results. We recommend using pagination on the client side, using the 2 following query parameters:
  • ?offset=<n>: The offset from which we return the results, which is equivalent to the number of elements in the array to skip. Defaults to 0.
  • ?limit=<n>: The number of results to return. Defaults to 50.
For example, if your initial input has 100 emails to verify, and you want the results for emails #61-#70, you should add the query parameters: GET /v0/bulk/{job_id}/results?offset=60&limit=10.
 
💡 Pro Tip: You can also download the results as CSV, by passing the ?format=csv 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.