Skip to content

Latest commit

 

History

History
141 lines (114 loc) · 6.43 KB

README.md

File metadata and controls

141 lines (114 loc) · 6.43 KB
Raw



@reacherhq/api

Check if an email address exists without sending any email.

npm Github Actions Apache-2.0 david-dm Github Sponsor



What is it?

Check if an email address exists without sending any email.

@reacher/api is a thin TypeScript wrapper around the Reacher Email Verification API. Reacher is a 100% open-source SaaS, written in Rust. It's also free for personal use, and the API token in @reacherhq/api is optional, but without it the requests will be rate-limited to 50 per month.

Usage

Install the package:

yarn add @reacherhq/api # Or npm install @reacherhq/api

There are two ways to use the library: by sending single API requests, or by using batch verification.

1. Single Email Verification

import { checkSingle } from '@reacherhq/api';

checkSingle(
	{ to_email: '[email protected]' },
	{
		apiToken: '<YOUR_TOKEN>', // Optional, rate-limited if not provided.
	}
).then(console.log); // Output will be the JSON described in the "JSON Output" section below.

2. Batch Email Verification

import { batchQueue } from '@reacherhq/api';

// Create a queue for email verifications.
const q = batchQueue({
	// Optional, rate-limited if not provided.
	apiToken: '<YOUR_TOKEN>',
	// Optional, callback to call on each successful verification.
	onSuccessSingle: (result) => {
		console.log(
			`Verified email ${result.input}: the result is ${result.is_reachable}.`
		);
	},
});

// Push some data into the queue. The email verification will start as soon as
// it's in the queue. The queue has a default concurrency of 100.
q.push({ to_email: '[email protected]' });
q.push({ to_email: '[email protected]' }, { to_email: '[email protected]' });

// Perform some action when the queue is drained.
q.drain(() => {
	console.log('Finished processing all items.');
});

📚 See Full Documentation

What Does Reacher Check?

Included? Feature Description JSON field
✅ Email reachability How confident are we in sending an email to this address? Can be one of safe, risky, invalid or unknown. is_reachable
✅ Syntax validation Is the address syntactically valid? syntax.is_valid_syntax
✅ DNS records validation Does the domain of the email address have valid MX DNS records? mx.accepts_mail
✅ Disposable email address (DEA) validation Is the address provided by a known disposable email address provider? misc.is_disposable
✅ SMTP server validation Can the mail exchanger of the email address domain be contacted successfully? smtp.can_connect_smtp
✅ Email deliverability Is an email sent to this address deliverable? smtp.is_deliverable
✅ Mailbox disabled Has this email address been disabled by the email provider? smtp.is_disabled
✅ Full inbox Is the inbox of this mailbox full? smtp.has_full_inbox
✅ Catch-all address Is this email address a catch-all address? smtp.is_catch_all
✅ Role account validation Is the email address a well-known role account? misc.is_role_account

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 OpenAPI v3 specification of this JSON object.

License

The source code is available under the Apache-2.0 license. See the LICENSE file for more info.