Bouncerly
Log inGet started

Documentation

Introduction

Bouncerly tells you whether an email address can receive mail, before you send to it. This guide gets you from zero to your first verified address in a couple of minutes.

1. Get an API key

Create an account, then open API keys in the dashboard and click Create API key. Keys look like bn_… and are shown once, so store yours in an environment variable straight away.

2. Verify an address

Send a POST to /v1/verify with your key as a bearer token. The base URL for every request is https://api.bouncerly.com.

const res = await fetch("https://api.bouncerly.com/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOUNCERLY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "jane@acme.com" }),
});

const { status, reason, did_you_mean } = await res.json();

3. Read the result

Every response has a status you can act on and a reason that explains it. Here's a mailbox that exists:

Response
{
  "email": "jane@acme.com",
  "status": "deliverable",
  "reason": "accepted",
  "domain": "acme.com",
  "disposable": false,
  "role_account": false,
  "free_provider": false,
  "accept_all": false,
  "mx_found": true,
  "mx_host": "acme-com.mail.protection.outlook.com",
  "smtp": { "code": 250, "enhanced": "2.1.5", "message": "Recipient OK" },
  "smtp_checked": true,
  "checked_at": "2026-10-28T10:03:42Z",
  "duration_ms": 1840,
  "cached": false
}

At signup, reject undeliverable, offer did_you_mean as a fix, optionally block disposable, and let everything else through. See Understanding results for the full list of reasons.

Fail open. An uncached check usually takes 1 to 3 seconds and can take longer for slow mail servers. Call the API with a client timeout of a few seconds, and if it times out or errors, let the user through. A slow mail server should never block a real signup.

Next steps