check-if-email-exists

Check if an email address exists without sending any email.

👉 Live Demo: https://reacher.email

If you don't have time to waste configuring, hosting, debugging and maintaining your own email verifier, we offer a SaaS solution that has all of the capabilities check-if-email-exists provides, plus a lot more, and all that packaged in a nice friendly web interface. If you are interested, find out more at [email protected].

What Does This Tool Check?

🤔 Why?

Many online services (https://hunter.io, https://verify-email.org, https://email-checker.net) offer this service for a paid fee. Here is an open-source alternative to those tools.

Licensing

check-if-email-exists's source code is provided under a dual license model designed to meet the development and distribution needs of both commercial and open-source projects.

If you want to use this library to build closed-sourced commercial sites and applications, then you'll need to purchase a commercial license. This allows you to keep your software proprietary whilst still using check-if-email-exists. You can purchase a commercial license here. A commercial license grants you:

• On-premise running as well as running on public cloud providers for commercial purposes for proprietary systems.
• Ability to modify the source (forking) for your own purposes.

Not only does it grant you a license to run such a critical piece of infrastructure, but you are also supporting further innovation in this space and our ability to contribute to it!

If you are creating an open source application under a license compatible with the Affero GNU GPL license v3, you may use check-if-email-exists under the terms of the AGPLv3. You can read more about this license here.

Please read the LICENSE file for more information about the dual license.

Try It Yourself

There are 5 ways you can try check-if-email-exists.

1. Use the Hosted Version: https://reacher.email 🥇

Reacher is a simple SaaS using this library, also open-source!

If you would like a high free tier to test Reacher, consider sponsoring me! You'll get 8000 free email verifications every month, and a this contribution would mean A WHOLE LOT to me.

2. One-Click Deploy to Heroku

Reacher provides a fully-fledged REST backend at https://github.com/reacherhq/backend. It is the same backend running for our main product https://reacher.email.

The beckend is built using the fast web framework warp, and exposes an API endpoint for making email verifications.

For an one-click deploy to Heroku, click on the purple Heroku button at reacherhq/backend.

3. Use Docker

The Docker image is hosted on Docker Hub: https://hub.docker.com/r/reacherhq/check-if-email-exists.

To run it, run the following command:

docker run -p 3000:3000 reacherhq/check-if-email-exists

You can then send a POST request with the following body to http://localhost:3000 to test multiple emails at once:

{
	"to_emails": ["[email protected]"]
}

Here's the equivalent curl command:

curl -X POST -d'{"to_emails":["[email protected]"]}' http://localhost:3000

Optionally, you can also pass in from_email and hello_name fields into the JSON object, see the help message below to understand their meanings.

4. Download the Binary

Note: The binary doesn't connect to any backend, it checks the email directly from your computer.

Head to the releases page and download the binary for your platform. Make sure you have openssl installed on your local machine.

> $ check_if_email_exists --help
check_if_email_exists 0.8.19
Check if an email address exists without sending any email.

USAGE:
    check_if_email_exists [FLAGS] [OPTIONS] [TO_EMAIL]

FLAGS:
        --http       Runs a HTTP server.
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --from-email <FROM_EMAIL>          The email to use in the `MAIL FROM:` SMTP command. [default:
                                           [email protected]]
        --hello-name <HELLO_NAME>          The name to use in the `EHLO:` SMTP command. [default: localhost]
        --http-host <HOST>                 Sets the host IP address on which the HTTP server should bind. Only used when
                                           `--http` flag is on. [default: 127.0.0.1]
        --http-port <PORT>                 Sets the port on which the HTTP server should bind. Only used when `--http`
                                           flag is on. If not set, then it will use $PORT, or default to 3000.
        --proxy-host <PROXY_HOST>          Use the specified SOCKS5 proxy host to perform email verification.
        --proxy-port <PROXY_PORT>          Use the specified SOCKS5 proxy port to perform email verification. Only used
                                           when `--proxy-host` flag is set. [default: 1080]
        --yahoo-use-api <YAHOO_USE_API>    For Yahoo email addresses, use Yahoo's API instead of connecting directly to
                                           their SMTP servers. [default: true]

ARGS:
    <TO_EMAIL>    The email to check.

If you run with the --http flag, check-if-email-exists will serve a HTTP server on http://localhost:3000. You can then send a POST request with the following body to test multiple emails at once:

{
	"to_emails": ["[email protected]"]
}

Here's the equivalent curl command:

curl -X POST -d'{"to_emails":["[email protected]"]}' http://localhost:3000

Optionally, you can also pass in from_email and hello_name fields into the JSON object, see the help message above to understand their meanings.

💡 PRO TIP: To show debug logs when running the binary, run:

RUST_LOG=debug check_if_email_exists [FLAGS] [OPTIONS] [TO_EMAIL]

5. Usage as a Rust Library

In your own Rust project, you can add check-if-email-exists in your Cargo.toml:

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

And use it in your code as follows:

use check_if_email_exists::{check_email, CheckEmailInput};

async fn check() {
    // Let's say we want to test the deliverability of [email protected]
    let mut input = CheckEmailInput::new(vec!["[email protected]".into()]);

    // Optionally, we can also tweak the configuration parameters used in the
    // verification.
    input
        .from_email("[email protected]".into()) // Used in the `MAIL FROM:` command
        .hello_name("example.org".into()); // Used in the `EHLO` command

    // Verify this input, using async/await syntax.
    let result = check_email(&input).await;

    // `result` is a `Vec<CheckEmailOutput>`, where the CheckEmailOutput
    // struct contains all information about our email.
    println!("{:?}", result);
}

The reference docs are hosted on docs.rs.

✈️ JSON Output

The output will be a JSON with the below format, the fields should be self-explanatory. For [email protected] (note that it is disabled by Gmail), here's the exact output:

{
	"input": "[email protected]",
	"is_reachable": "invalid",
	"misc": {
		"is_disposable": false,
		"is_role_account": false
	},
	"mx": {
		"accepts_mail": true,
		"records": [
			"alt3.gmail-smtp-in.l.google.com.",
			"gmail-smtp-in.l.google.com.",
			"alt1.gmail-smtp-in.l.google.com.",
			"alt4.gmail-smtp-in.l.google.com.",
			"alt2.gmail-smtp-in.l.google.com."
		]
	},
	"smtp": {
		"can_connect_smtp": true,
		"has_full_inbox": false,
		"is_catch_all": false,
		"is_deliverable": false,
		"is_disabled": true
	},
	"syntax": {
		"domain": "gmail.com",
		"is_valid_syntax": true,
		"username": "someone"
	}
}

You can also take a look at the documentation of this JSON object.

❓ FAQ

What does is_reachable: "unknown" mean?

This means that the server does not allow real-time verification of an email right now. It may happen for multiple reasons: your IP is blacklisted, the SMTP port 25 is blocked, the email account is momentarily receiving too many emails (spam protection)... or the email provider simply does not allow real-time verification at all. The details of this "unknown" case can be found in the smtp.error and mx.error fields.

The library hangs/takes a long time/doesn't show anything after 1 minute.

Most ISPs block outgoing SMTP requests through port 25, to prevent spam. check-if-email-exists needs to have this port open to make a connection to the email's SMTP server, so won't work behind these ISPs, and will instead hang until it times out. There's unfortunately no easy workaround for this problem, see for example Deploy to Heroku section.

To see in details what the binary is doing behind the scenes, run it in verbose mode to see the logs.

I have another question

Feel free to check out Reacher's FAQ.

🔨 Build From Source

First, install Rust; you'll need Rust 1.37.0 or later. Then, run the following commands:

# Download the code
$ git clone https://github.com/reacherhq/check-if-email-exists
$ cd check-if-email-exists

# Build in release mode
$ cargo build --release

# Run the binary
$ ./target/release/check_if_email_exists --help

Legacy Bash Script

The 1st version of this tool was a simple bash script which made a telnet call. If you would like to use that simpler version, have a look at the legacy branch. The reasons for porting the bash script to the current codebase are explained in issue #4.