REST API

The email verification API that stays out of your way.

One HTTPS call, one JSON answer. Check addresses at signup, clean lists before a send, or wire BounceHound into your CRM, with the same credits as the dashboard.

Get 250 free credits Read the reference

Verify a single address from your terminal.

terminal

curl -X POST https://bouncehound.com/api/v1/verify \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.com"}'

Built-in fetch, no SDK needed.

verify.mjs

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

const result = await res.json();
if (result.status === "valid") {
  // safe to send
}

Using requests.

verify.py

import os, requests

res = requests.post(
    "https://bouncehound.com/api/v1/verify",
    headers={"Authorization": f"Bearer {os.environ['BOUNCEHOUND_API_KEY']}"},
    json={"email": "jane@acme.com"},
    timeout=60,
)
result = res.json()
print(result["status"], result["didYouMean"])

Up to 10,000 emails per request.

terminal

curl -X POST https://bouncehound.com/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["jane@acme.com","bob@gmial.com","test@mailinator.com"]}'

Why BounceHound

Built for developers who ship

Real time
Verify at signup or checkout with one request. Most checks finish in a few seconds.
Bulk
Send up to 10,000 emails per request. Duplicates are removed before you're charged.
Pay only for answers
Unknown results, bad syntax, dead domains and known disposables are free.
More than valid/invalid
Catch-all, disposable, role and free-provider flags, plus typo fixes like gmial.com → gmail.com.

Reference

Endpoints

Authenticate with your API key as a Bearer token (or an X-API-Key header). All responses are JSON.

Base URLhttps://bouncehound.com/api/v1

POST/v1/verifyVerify one email. Body: { "email": "…" }.
GET/v1/verify?email=…Same check as a GET, handy for no-code tools and quick tests.
POST/v1/verify/bulkVerify up to 10,000 emails in one request. Body: { "emails": [ … ] }.
GET/v1/creditsYour remaining credit balance.

Response · /v1/verify

200 OK

{
  "email": "jane@acme.com",
  "status": "valid",
  "reason": "mailbox_ok",
  "role": false,
  "free": false,
  "disposable": false,
  "didYouMean": null,
  "domain": "acme.com",
  "mx": "aspmx.l.google.com",
  "source": "provider",
  "charged": true,
  "checkedAt": "2026-10-12T15:04:05.000Z"
}

Response · /v1/verify/bulk

200 OK

{
  "results": [ { "email": "jane@acme.com", "status": "valid", ... }, ... ],
  "summary": { "valid": 812, "invalid": 97, "risky": 64, "disposable": 18, "unknown": 9 },
  "creditsUsed": 973,
  "creditsRemaining": 49027
}

Errors

402 Payment Required

{ "error": { "code": "insufficient_credits", "message": "Insufficient credits. ..." } }

Response fields

Fields in a verification result
Field	Type	Meaning
status	string	valid, invalid, risky, disposable or unknown.
reason	string	Why, e.g. mailbox_ok, mailbox_not_found, no_mx, catch_all.
didYouMean	string \| null	Suggested fix for a likely typo.
role	boolean	Role address such as info@ or sales@.
free	boolean	Free provider such as Gmail or Outlook.
disposable	boolean	Throwaway inbox provider.
domain / mx	string	The domain and its mail server.
charged	boolean	Whether this check used a credit.

Statuses and billing

Verification statuses and whether they cost a credit
Status	Meaning	Charged
valid	Mailbox exists and accepts mail. Safe to send.	Yes
invalid	Will bounce: bad syntax, no mail server, or mailbox rejected.	Only if rejected by the mail server
risky	Catch-all domain: accepts everything, may still bounce.	Yes
disposable	Throwaway inbox (Mailinator, 10minutemail…).	No, when caught by our list
unknown	The mail server didn't answer in time. Retry later.	Never

Error codes

HTTP error codes
HTTP	error.code	Meaning
400	invalid_request / invalid_json	Missing or malformed body or parameters.
401	unauthorized	Missing or invalid API key.
402	insufficient_credits	Not enough credits for the request. Nothing was charged.
413	too_many_emails	More than 10,000 emails in one bulk request. Split into batches.
500	internal_error	Something broke on our side. Safe to retry.

Using an AI agent?

Skip the code. Connect our MCP server to Claude, Cursor or ChatGPT with the same API key.

Explore the MCP server

Put the hound on your list.

Get 250 free credits, verify your first list in minutes, and connect your AI agent whenever you're ready.

Get 250 free credits View pricing