Bulk Email Verification

Last Updated: Dec 22nd, 2023.

The Bulk email verification API allows you to verify a list of emails in one go.

This document refers to the new /v1/bulk endpoints, which are available on Reacher backends v0.6.*. To check the old /v0/bulk documentation for Reacher backends v0.5.*, please refer to:

🥑/v0/bulk Email Verification

❗

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.

Installation

Prerequesites:

A self-hosted Reacher setup, see 🏠Self-Host Guide.

Run a RabbitMQ instance

Reacher uses the battle-tested RabbitMQ implementation of message queues to handle bulk email verification.

We recommend running RabbitMQ on a separate server than the one you run Reacher on. In general, the server on which Reacher is running should have a dedicated IP address, so that you can have control over its IP reputation. The server on which you install RabbitMQ does not have this requirement, and can be installed on a VPS for example.

However, for the sake of this tutorial, we will install RabbitMQ on the same server as Reacher, for a quicker setup.

Run the following Docker command in a terminal:

docker run -it -d --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3.12-management

After this step, your server will expose two ports:

5672: This is AMQP port, the protocol used by RabbitMQ to send/receive messages.

15672: This is a web server showing a management UI to monitor the RabbitMQ instance.

Optional step: Using the UI, you add users and passwords to protect your RabbitMQ instance from the outside world.

Run Reacher and connect it to RabbitMQ

When running the Reacher backend, set the environment variable RCH_AMQP_ADD to the RabbitMQ’s AMQP address. Assuming that RabbitMQ is run on the same server as Reacher (as assumed in this tutorial), that address is amqp://localhost.

Note: if you added users and password, then they should go into this environment variable too, like amqp://<user>:<pass>@localhost:5672.

docker run \
	-e RUST_LOG=info
	-e RCH_BACKEND_NAME=mybackend \
	-e RCH_AMQP_ADDR=<your_rabbitmq_addr> \
	-e RCH_WORKER_CONCURRENCY=10 \
	--name reacher_backend
	-p 8080:8080 \
	reacherhq/backend

You should see the backend running with the following logs:

INFO reacher: Running Reacher version="0.5.0"
INFO reacher: Connected to AMQP broker backend="mybackend" state=Connected concurrency=10
INFO reacher: Server is listening host=127.0.0.1 port=8080
INFO Server::run{addr=127.0.0.1:8080}: warp::server: listening on http://127.0.0.1:8080
INFO reacher: Worker will start consuming messages queue="check_email.Smtp"

The logs show that Reacher is running a background worker that will listen to all new emails to verify in a RabbitMQ queue called check_email.Smtp. The concurrency is 10, and is tweakable depending on the server capabilities and IP health maintenance scheme you have.

Bulk verify a list of emails

1. Submit a list of emails: `POST /v1/bulk`

The body of the request contains the list of emails, as well as a couple of configuration options.

{
    // Required fields:
    "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.
}

And the response will be, if successful:

{"message": "Successfully added 2 emails to the queue"}

2. Check the results of the email verifications

By default, the results of the email verifications are only shown in logs. See them by running:

docker logs -f reacher_backend

You’ll see the result like this:

INFO reacher: Worker will start consuming messages queue="check_email.Smtp"
INFO reacher: 127.0.0.1:57462 "POST /v1/bulk HTTP/1.1" 200 "-" "PostmanRuntime/7.36.0" 8.629041ms    
INFO reacher: New job email="amaury@reacher.email"
INFO reacher: New job email="support@reacher.email"
INFO reacher: Done check email="support@reacher.email" is_reachable=Safe
INFO reacher: Done check email="amaury@reacher.email" is_reachable=Safe

Of course, most people want to download the results at once. For this, Reacher’s bulk endpoints offer webhooks.

Save results using Webhooks

Reacher is agnostic on how you wish to save the email verification results. By default, it only prints the results in the terminal console.

Save results to a Postgres Database

If you pass the DATABASE_URL environment variable to Docker, pointing to a PostgreSQL database, then Reacher will save each email verification result into that database, in the email_results table. The columns of this tables can be seen here.

Save results via a Webhook

If you wish to save the email verification results somewhere else, you can pass a webhook URL to the bulk endpoint which points to your own server:

{
    // Required fields:
    "input": [                          // Endpoint accepts a list of emails.
        "support@reacher.email",
        "invalid@reacher.email"
    ],

    // Optional:
    "webhook": {
        "url": "my.server.com/webhook",
        "extra": {
						"foo": "bar"
				}
    },
}

Reacher will send one POST request to webhook.url per successful verification, containing the following payload:

{
		"output": {
				"is_reachable": "safe",
				//<--snip-->             // For all the other fields here, see https://help.reacher.email/email-attributes-inside-json
		},
		"extra": {                   // This will be the exact copy of what was given in the request
				"foo": "bar"
		}

The extra field can be left empty, or contain anything you want: a unique job ID, the user who initiated the bulk verification etc.

Then, on your own implementation of my.server.com/webhook, you can do the following:

save results in a Postgres DB

save results in a MongoDB

create a new MailChimp list with clean emails only

etc.

Reacher has an open-source code for the first case in Javascript on reacherhq/webapp, saving all results into a Postgres DB hosted on Supabase. If you need help on how to save results in another DB, feel free to contact me, see below for contact information.

Advanced: Multiple workers

The big advantage of using RabbitMQ is that one can easily scale horizontally the number of workers. The architecture looks like this:

In this case, each rectangle represents a separate server. On the bottom, you can add as many Reacher backends as you wish, simply by pointing them to the same RCH_AMQP_ADDR.

Questions ?

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