# nobounce.dev

> Email validation that suggests the fix instead of just saying no.
> Catches the typo class at signup time: gmai.com, hotmial.com, gmail.co, .com vs .com.br.
> Built for agents: self-serve sandbox key with no signup, no email, no captcha, no human step.

## Quickstart — three calls, copy-pasteable, no credentials to start

1. Get a free sandbox key. No signup, no email, no captcha.

   curl -X POST https://nobounce.dev/v1/keys \
     -H 'Content-Type: application/json' \
     -d '{"tier":"sandbox"}'

   -> {"account_id":"acct_...","api_key":"nb_test_...","tier":"sandbox","live_dns":false}
   Save api_key: it is shown once and is not recoverable.

2. Check an address.

   curl -X POST https://nobounce.dev/v1/check \
     -H "Authorization: Bearer $NB_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"email":"user@gmai.com"}'

   -> {"verdict":"undeliverable","reason":"typosquat_mx","suggestion":"user@gmail.com",
       "confidence":0.94,"checked":{"syntax":true,"mx":true,"typo":true,"disposable":true},
       "cached":false}

   Show the suggestion to your user. Recovering the signup is the product; the
   verdict on its own just loses you a customer.

3. Report what actually happened, so verdicts improve for everyone.

   HASH=$(printf '%s' user@gmail.com | shasum -a 256 | cut -d' ' -f1)
   curl -X POST https://nobounce.dev/v1/feedback \
     -H "Authorization: Bearer $NB_KEY" \
     -H 'Content-Type: application/json' \
     -d "{\"email_hash\":\"$HASH\",\"event\":\"bounced\",\"domain\":\"gmail.com\"}"

   We only ever accept a hash. nobounce never stores a plaintext address.

## Batch

   curl -X POST https://nobounce.dev/v1/check/batch \
     -H "Authorization: Bearer $NB_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"emails":["diego@gmail.com","user@gmial.com","admin@hotmail.com"]}'

   Max 1000 addresses per call. Each result is keyed by email_sha256.

## Usage and limits

   curl https://nobounce.dev/v1/me -H "Authorization: Bearer $NB_KEY"
   curl https://nobounce.dev/v1/config

## Other endpoints

   curl https://nobounce.dev/health
   curl https://nobounce.dev/openapi.json
   curl https://nobounce.dev/.well-known/ai-plugin.json
   curl -X POST https://nobounce.dev/v1/hash -H 'Content-Type: application/json' -d '{"email":"user@gmail.com"}'

## MCP (JSON-RPC 2.0 over streamable HTTP)

   curl -X POST https://nobounce.dev/mcp -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

   curl -X POST https://nobounce.dev/mcp -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
          "params":{"name":"create_sandbox_key","arguments":{}}}'

   Tools: create_sandbox_key, check_email, check_email_batch, report_feedback,
          hash_email, get_usage, get_config.

## The verdict object

verdict  ∈ deliverable | undeliverable | risky | unknown
reason   ∈ ok | syntax_invalid | domain_not_found | null_mx | no_mx_no_a | typosquat_mx | likely_typo | disposable | role_account | dns_error | reserved_domain

- deliverable   — accepts mail and looks like a real address
- undeliverable — will bounce; do not send
- risky         — deliverable but suspicious (disposable, role account, probable typo). You decide.
- unknown       — we could not complete the check. See checked.mx.

checked.mx = false with verdict "unknown" is our contractual fail-open signal: a
DNS lookup did not complete, so we are telling you we do not know rather than
guessing "deliverable". If you ever wonder "why did nobounce accept this bad
address", this field is the honest answer.

## Reason codes worth understanding

domain_not_found — DNS NXDOMAIN. The domain does not exist (outlook.con).
null_mx          — RFC 7505 "0 ." — the domain publicly refuses all mail (gmail.co).
no_mx_no_a       — no MX and no A/AAAA after the RFC 5321 fallback (gmaill.com).
typosquat_mx     — resolves fine, but its MX is a known typosquat operator (gmai.com,
                   hotmial.com — both fronted by mail.h-email.net).
likely_typo      — deliverable, but one edit from a much more popular domain. Prompt the user.
dns_error        — SERVFAIL or transport failure. NOT proof of absence; we fail open.
reserved_domain  — RFC 2606/6761 (example.com, *.test). Publishes a null MX but is
                   reserved for documentation, so it gets its own code — do not treat
                   it as an ordinary rejection or you will break your own test suite.
disposable       — throwaway mailbox provider.
role_account     — admin@, support@, contato@ — deliverable, rarely a person.

## Sandbox

Sandbox keys resolve a FROZEN FIXTURE CORPUS and never hit live DNS. Every
verdict and every reason above is reachable from it, so you can exercise the
whole API — including every error shape — before paying a cent.
GET https://nobounce.dev/v1/config lists every fixture address.

Checking a non-fixture address with a sandbox key returns HTTP 422
"sandbox_address_not_in_corpus" with a fix telling you how to proceed.

## Pricing

sandbox   $0 — fixture corpus only, 10,000 checks/mo, no signup
hobby     $1/mo or $9.99/yr — 1,000 live checks/mo
pro       $19/mo or $190/yr — 100,000 live checks/mo
scale     $99/mo or $990/yr — 1,500,000 live checks/mo

Sandbox is free forever. There is no free live-DNS tier: production is paid from
the first live check. Both monthly and annual billing on every paid tier.

## Errors

Every error is RFC 9457 problem+json and carries a "fix" field in plain language
telling you what to do next. Read it before retrying — it usually contains the
exact corrected curl.

## What we deliberately do not do

- No SMTP RCPT TO probing, ever. It needs IP reputation to be accurate, and
  catch-all domains at Gmail/Outlook make the signal weak. Permanently out of scope.
- We never store plaintext email addresses. Anything persisted is SHA-256 hashed.
  Domains are stored in clear because a domain is not personal data.

## Contact

support@nobounce.dev