API Reference · v1

BounceZip API

Verify one email in real time, deep-check catch-all addresses, or clean a whole list with a bulk job. It's a plain REST API over HTTPS that returns JSON.

https://api.bouncezip.com/v1

Real-time API

One address, answer in ~1 second. Built for signup forms.

Catch-All API

Score and recommendation for accept-all domains.

Bulk API

Upload a CSV or spreadsheet, download clean results.

All endpoints

Method	Endpoint	What it does	Key param
GET	`/v1/verify`	Verify one email in real time	`api`
GET	`/v1/catchall`	Deep-check one catch-all email	`api`
POST	`/v1/upload`	Upload a file for bulk verification	`key`
GET	`/v1/fileinfo`	Check job status, progress and counts	`key`
GET	`/v1/download`	Download all or filtered results	`key`
GET	`/v1/stop`	Stop a running bulk job	`key`
GET	`/v1/credits`	Check your credit balance	`api`

All requests must use HTTPS, and every response is JSON. Credit costs per verification are set by your account and may change. Your current costs are shown on your dashboard.

Authentication

Every request is authenticated with your API key, sent as a query parameter. Create and manage keys under API → API keys in the dashboard.

API	Query parameter	Example
Real-time API	`api`	`?api=YOUR_API_KEY`
Catch-All API	`api`	`?api=YOUR_API_KEY`
Credits API	`api`	`?api=YOUR_API_KEY`
Bulk API	`key`	`?key=YOUR_API_KEY`

Test key

Create a sandbox key under Dashboard → API for development. Sandbox keys start with bz_test_.

Keep API keys secure. Never put a key in frontend code, browser JavaScript, public repositories or client-side environment variables. In production, send requests through your backend so the key stays private.

Real-time API

1 credit

Verifies a single email and returns the result right away. Perfect for checking signups the moment they arrive. Results come back in about a second.

GEThttps://api.bouncezip.com/v1/verify

Query parameters

Parameter	Type	Description
`api`required	string	Your API key.
`email`required	string	The email address to verify. URL-encode special characters.
`timeout`optional	integer	Optional, 2–60 seconds. Default `20`. Use a low value on signup forms.

Request

Response

Response fields

Field	Type	Meaning
`email`	string	The address you sent, in lower case.
`quality`	string	`good`, `risky` or `bad`. A one-word summary, handy for filters.
`result`	string	The main verdict: `ok`, `catch_all`, `unknown`, `disposable` or `invalid`.
`result_code`	integer	The verdict as a number. See result values.
`sub_result`	string	The reason behind the verdict, for example `deliverable`, `accept_all`, `bad_domain` or `bad_syntax`.
`free`	boolean	The address is on a free provider such as Gmail, Outlook or Yahoo.
`role`	boolean	A shared mailbox such as info@, sales@ or support@.
`did_you_mean`	string	A corrected address when we spot a domain typo. Empty otherwise.
`credits`	integer	Your credit balance after this call.
`execution_time`	integer	How long the check took, in seconds.
`error`	string	Empty on success, otherwise a short message.

Result values

Code	result	Meaning	What to do
1	ok	Valid, deliverable mailbox.	Send
2	catch_all	The domain accepts all mail, so deliverability is uncertain.	Deep-check with the Catch-All API
3	unknown	The server didn't respond in time.	Retry later
4	disposable	A temporary, throwaway address.	Remove
6	invalid	The mailbox or domain doesn't exist.	Remove

Catch-All API

5 credits

Deep-checks one catch-all or uncertain address. It returns deliverability, a 0–100 score, a confidence level and a clear recommendation, plus the supporting checks. Use it when the Real-time API returns catch_all.

GEThttps://api.bouncezip.com/v1/catchall

Query parameters

Parameter	Type	Description
`api`required	string	Your API key.
`email`required	string	The email address to deep-check. URL-encode special characters.
`timeout`optional	integer	Optional, 2–60 seconds. Default `20`.

Request

Response

Response fields

Field	Type	Meaning
`email`	string	The address you sent.
`status`	string	BounceZip status: `valid`, `catchall`, `unknown` or `invalid`.
`result` · `result_code`	string · integer	API result value, the same values as the Real-time API, for example `catch_all` / `2`.
`quality`	string	`good`, `risky` or `bad`.
`deliverability`	string	`deliverable`, `undeliverable` or `uncertain`.
`score`	integer	Deliverability score from 0 to 100, when available. Higher is safer.
`recommendation`	string	What to do next. See below.
`confidence` · `risk_level`	string	How confident the check is, and how risky the address is.
`mx` · `smtp` · `checks`	object	Extra details from the verification engine.
`credits`	integer	Credits remaining after this call.
`execution_time` · `error`	number · string	Time taken, and an error message if the check could not finish.

Recommendation values

recommendation	What to do
send	Safe to treat as valid.
send_with_caution	Send, but in a slower, smaller sequence.
retry_or_verify_later	Not enough signal right now. Check again later.
do_not_send	Remove from your list.

Bulk API

key = your API key

Verify whole lists: upload a file, check progress, then download the results. Ideal for cleaning large databases. Every Bulk API call takes your API key as key, not api.

Upload a file

Send a CSV or spreadsheet and get a file_id.

Check progress

Poll the file status until it's finished.

Download results

Export all rows or a filtered set.

Stop a job

Stop a running job you no longer need.

Endpoints

Method	Endpoint	What it does
POST	`/v1/upload`	Upload a file for standard or catch-all bulk verification.
GET	`/v1/fileinfo`	Check job status, progress and summary counts.
GET	`/v1/download`	Download all or filtered results.
GET	`/v1/stop`	Stop a running bulk job.

1Upload a file

POSThttps://api.bouncezip.com/v1/upload

Parameter	Type	Description
`key`required	query	Your API key.
`file_contents`required	file	The CSV or spreadsheet, sent as `multipart/form-data`.
`verification_type`	form field	`email` for standard verification (also `standard` or `normal`), or `catchall` for bulk catch-all checks (also `catch_all` or `catch-all`).

Bulk catch-all checks. Send verification_type=catchall to the same /v1/upload endpoint.

2Check progress

GEThttps://api.bouncezip.com/v1/fileinfo

Pass key and file_id. Poll every few seconds until status is finished.

3Download results

GEThttps://api.bouncezip.com/v1/download

Pass key, file_id and a filter to get exactly the rows you need.

filter	Rows included
`all`	All verification results.
`ok`	Only ok valid, deliverable emails.
`ok_and_catch_all`	Valid emails plus catch_all results.
`unknown`	Emails that couldn't be confirmed.
`invalid`	Invalid or undeliverable emails.

4Stop a running job

GEThttps://api.bouncezip.com/v1/stop

Emails that were already verified stay downloadable, and unused credits are never spent.

Credits API

Free

Check your balance in code, for example before uploading a large list. The response shows your available credits, bulk credits and current plan.

GEThttps://api.bouncezip.com/v1/credits

Model Context Protocol

BounceZip MCP Server

Give Claude, Cursor, Windsurf or any MCP-ready AI agent email verification. Ask in plain English ("verify this email", "clean this CSV") and the agent calls BounceZip for you. You don't need to write any code.

npx -y @bouncezip/mcp

Preview documentation. The @bouncezip/mcp package is not publicly available yet. Use the live REST API until the MCP package is released.

How it works

You ask"Verify these 50 leads"

prompt

AI agentClaude, Cursor…

tool call

MCP serverRuns on your machine

HTTPS

BounceZip APISame checks & credits

Package@bouncezip/mcp on npm

Transportstdio (runs locally via npx)

RequiresNode.js 18+ and an API key

Toolsverify_email · verify_list · get_job · get_credits

Install & connect

~1 minute

1Get an API key

Create a key under API → API keys in the dashboard. While you set things up, use a sandbox key (bz_test_) from Dashboard → API. Replace YOUR_API_KEY in the snippet with your key.

2Add BounceZip to your agent

Where to find the config in Claude Desktop: Settings → Developer → Edit Config.

3Restart and try it

Restart the agent. The four BounceZip tools appear in its tool list. Try asking:

"How many BounceZip credits do I have?" If it answers with your balance, you're connected.

Environment variables

Variable	Required	What it does
`BOUNCEZIP_API_KEY`	Yes	Your `bz_live_` or `bz_test_` API key.

Tools

Each tool maps to one API endpoint, so the agent gets exactly the same results as the dashboard and the REST API.

verify_email

1 credit

Verifies one address in real time. Returns the same 11 fields as GET /v1/verify.

Input	Type	Description
`email`required	string	The address to verify.
`timeout`optional	integer	Seconds to wait, 2–60.

verify_catchall

5 credits

Deep-checks one catch-all address and returns a score and recommendation. Same as GET /v1/catchall. Agents usually call it after verify_email returns catch_all.

verify_list

Bulk

Uploads a CSV or spreadsheet the agent can read and starts a bulk job. Returns a file_id. Same as POST /v1/upload.

Input	Type	Description
`file`required	string	Local path to the CSV or spreadsheet.
`verification_type`optional	string	`email` (default) or `catchall`.

get_job

Free

Returns progress and summary counts for a bulk job. Same as GET /v1/fileinfo. Once it's finished, the agent can fetch results with a filter: ok, ok_and_catch_all, unknown, invalid or all.

get_credits

Free

Returns your credit balance and plan. Same as GET /v1/credits.

Example prompts

Talk to the agent normally. It picks the right tool and explains the result.

Verify [email protected] before I add her to the sequence.

Uses verify_email → verify_catchall

Check every email in leads.csv and tell me how many are safe to send.

Uses verify_list → get_job

Is the job I started this morning done? Give me the valid-only file.

Uses get_job

Which of these 20 signups look fake or disposable?

Uses verify_email × 20

Do I have enough credits to clean a 50,000-row list?

Uses get_credits

Fix the typos in this list of emails from our event.

Uses verify_email → did_you_mean

Credits & limits

Same credits as the API. Each check uses the same credits as the dashboard and API, at your account's credit costs.
Free tools. get_job and get_credits never use credits.
Use bulk for lists. For more than a few dozen emails, ask the agent to use verify_list instead of many single checks.
Every call is logged. MCP calls show in your dashboard like any other API request.

Security

Your key stays local. It lives in the MCP config on your machine. The agent never sees it in the chat, and it's only ever sent to the BounceZip API.
One key per agent. Give each agent its own key so you can track its usage and revoke it on its own under API → API keys.
Read-only by design. The server only verifies. It never sends email to the addresses it checks.
Same data rules. Lists sent through MCP are encrypted and deleted 30 days after the job, like any upload.

Troubleshooting

Problem	Fix
BounceZip tools don't appear	Fully restart the agent after saving the config, and check the JSON is valid (no trailing commas).
`npx: command not found`	Install Node.js 18 or newer, then restart the agent.
Invalid API key error	The key is missing or wrong. Copy it again from API → API keys and restart the agent.
Not enough credits	Top up your credits, or use a sandbox `bz_test_` key while testing.
Slow or failing checks on a big list	The agent is making single calls one by one. Ask it to use `verify_list`.