Guide · Open source

How to use check-if-email-exists: Docker, CLI and Rust guide

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

check-if-email-exists is an open-source tool, written in Rust, that tests whether an email address looks real and can receive mail, without sending a message to it. This guide shows you how to run it as a Docker HTTP backend, use the command-line tool, or call it from a Rust program, and how to read the JSON it returns. It is aimed at developers and teams who need to clean sign-up data or mailing lists.

Reacherreacherhq/check-if-email-exists · ★ 10.4k · MIT Install options & downloads

Quick start

1Install Docker. Make sure Docker is installed and that outbound port 25 is open on the host you plan to use.
2Start the backend. Run docker run -p 8080:8080 reacherhq/backend:latest to start the HTTP backend on port 8080.
3Build the request. Prepare a JSON body with a to_email field containing the address you want to check.
4Send a POST request. Send the body with POST to http://localhost:8080/v0/check_email.
5Read the result. Look at is_reachable first, then check the smtp, mx, misc and syntax fields for detail.
6Adjust for your volume. If you plan to check large volumes, read the proxy note in the README and consider SMTP proxy servers.

What does check-if-email-exists check?

The tool runs several checks on an address. It tests whether the syntax is valid, whether the domain has valid MX DNS records, and whether the domain's mail exchanger can be contacted over SMTP. It also looks at deliverability, whether the mailbox is disabled or full, and whether the domain is a catch-all.

It adds extra signals too: whether the address comes from a disposable email provider, whether it is a well-known role account, a Gravatar profile picture URL, and whether the email appears in Have I Been Pwned.

Email reachability: reported as safe, risky, invalid or unknown (field is_reachable)
Syntax validation (syntax.is_valid_syntax)
DNS records validation (mx.accepts_mail)
Disposable address check (misc.is_disposable)
SMTP server validation (smtp.can_connect_smtp)
Deliverability, disabled mailbox, full inbox and catch-all checks (smtp fields)
Role account check (misc.is_role_account)

Run the HTTP backend with Docker

This is the most common way to start. You need Docker installed. Run the backend on a cloud instance or your own server. The README notes that outbound port 25 must be open, so check this before you start.

Once the container is running on port 8080, send a POST request to the check_email endpoint with a JSON body containing to_email. The proxy object is optional and lets you route the verification through a SOCKS5 proxy.

Requires Docker and outbound port 25 open
The proxy field is optional; the default is empty
The README notes that large volumes need SMTP proxy servers, and points to proxy25.com

docker run -p 8080:8080 reacherhq/backend:latest

Send a check request to the backend

With the container running, send a POST request to http://localhost:8080/v0/check_email. The body is JSON with a to_email field. The example in the README uses someone@gmail.com.

Endpoint: POST /v0/check_email
Body field: to_email
Optional field: proxy with host, port, and optional username and password

{
    "to_email": "someone@gmail.com",
    "proxy": {
        "host": "my-proxy.io",
        "port": 1080,
        "username": "me",
        "password": "pass"
    }
}

Use the command-line tool

The CLI is a separate download. Go to the releases page on GitHub and download the binary for your platform. The CLI checks the email directly from your computer and does not connect to any backend.

Run the binary with --help to see its usage. The README points to a dedicated CLI README for all options and flags, so check that file for the full list.

Download the binary from the project's releases page
The CLI does not use the HTTP backend

check_if_email_exists --help

Use the Rust library in your own project

Add check-if-email-exists to the [dependencies] section of your Cargo.toml. Then create a CheckEmailInput from a list of addresses and pass it to check_email with await. The result is a Vec of CheckEmailOutput, which holds all the information about each address.

Reference documentation is hosted on docs.rs.

[dependencies]
check-if-email-exists = "0.9"

Read the JSON output

The output is a JSON object with input, is_reachable, misc, mx, smtp and syntax sections. The README shows a full example for someone@gmail.com. In that example the address is reported as invalid, because Gmail has disabled the mailbox, even though its MX records and SMTP server respond.

Treat is_reachable as a guide, not a final answer. Check the individual fields if your application needs to decide why an address failed.

is_reachable: safe, risky, invalid or unknown
smtp.is_deliverable and smtp.is_disabled show mailbox state
misc.is_disposable and misc.is_role_account flag special addresses

What people use it for

Validating email addresses on a sign-up form before creating an account
Cleaning a mailing list before sending a campaign
Running a self-hosted email verification service inside your own infrastructure
Adding an email check inside a Rust program with the library

Frequently asked questions

Does check-if-email-exists send an email to the address?

No. The project is designed to check whether an address exists without sending any email. It tests syntax, DNS MX records and the mail server's response instead.

How do I install check-if-email-exists?

The README's main method is Docker. Run docker run -p 8080:8080 reacherhq/backend:latest, which starts the HTTP backend on port 8080. You can also download the CLI binary from the releases page or add the crate to a Rust project.

What are the requirements?

The Docker backend needs Docker and outbound port 25 open, according to the README. The CLI checks the email directly from your computer, so it does not use the backend.

Is check-if-email-exists free and open source?

The project is released under the MIT licence, and its source code is on GitHub. The author also offers a separate paid SaaS product built on the same tool, which the README links to.

Why does it say an address is invalid when the mail server responds?

In the README example, someone@gmail.com has valid MX records and a reachable SMTP server, but the mailbox is disabled by Gmail, so is_reachable is invalid. Check smtp.is_disabled and smtp.is_deliverable to see the reason.

How does it compare with Truemail or Hunter Email Verifier?

The README does not compare it with other tools, so this guide cannot make a claim. Compare them on the checks each one runs, how it is deployed, and its licence, using each project's own documentation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use check-if-email-exists if you are a developer or team that wants a self-hosted, open-source email verification service, or a Rust library for checking addresses in your own program. Do not use it if a simple syntax check is enough, since a regex or basic library handles that, or if you need perfect results, because SMTP responses depend on each mail provider.

Install options & downloads