Best practices for using BounceBan with coding and AI agents

Coding and AI agents such as Claude Code, Codex and Cursor can verify emails for you and build BounceBan into your software. Because an agent acts on its own, small mistakes can repeat quickly. This guide shows you how to keep your API key safe, avoid wasted credits and get results you can rely on.

• Short index with key facts: https://bounceban.com/public/doc/llms.txt
• Full documentation in one file: https://bounceban.com/public/doc/llms-full.txt
• OpenAPI specification: https://bounceban.com/public/doc/api.yaml

• Name it after the agent or project, so you can see what it used on the API usage page.
• Set a daily or monthly quota. This is your best protection against a runaway loop. A request or bulk task that needs more than the key has left is rejected as a whole, and no credits are charged.
• Set an expiry date for short-term work.
• Disable the key if an agent misbehaves. This takes effect within seconds and doesn't affect your other keys.

• Store it in an environment variable, such as BOUNCEBAN_API_KEY. Don't paste it into a chat, and don't commit it to your repository.
• Ask your agent not to print the key, and to avoid verbose modes such as curl -v that show request headers.
• If a key may have been exposed, use Roll key in the key's Actions menu. The old value stops working right away.

• One email, or just a few: use the waterfall endpoint, GET https://api-waterfall.bounceban.com/v1/verify/single. It holds the connection until the result is ready, so this is the simplest option for an agent.
• More than a few emails: create a bulk task with POST /v1/verify/bulk, or POST /v1/verify/bulk/file for a CSV file. Don't verify a list by calling the single endpoint in a loop.
• Checking for free, disposable or role addresses only: use GET /v1/check. It doesn't run SMTP verification, so it can't tell you whether an email will bounce. It also uses separate Check credits.
• Checking your balance and limits: use GET /v1/account.

• The key goes in the Authorization header with no Bearer prefix. Agents often add one by mistake.
• --data-urlencode keeps characters such as + from being changed in the URL.
• The endpoint waits up to 80 seconds by default. Set your client's timeout longer than that. If your agent's tool has a shorter limit, lower the wait with the timeout parameter (30 to 300 seconds).

• Never resubmit an email while its status is verifying or queue. Every request to the standard /v1/verify/single endpoint costs 1 credit, even for the same email.
• Save the id from every response. You can look up the result for free with GET /v1/verify/single/status?id=... for 90 days.
• Poll within the limits. Send at most 10 status requests per id per 5 minutes, and use try_again_at when the response includes it. If there is still no result after 5 minutes, stop polling and start a new verification.
• Handle a waterfall 408 correctly. It means the request timed out, not that verification failed. Verification continues in the background. Send the same request again within 30 minutes at no charge, or use the returned id with the status endpoint. After 30 minutes, the same request starts a new, billed verification.
• Save the task id before you start waiting on a bulk task. If the agent restarts, it can resume from that id instead of creating a second task.

• 401 and 403: don't retry automatically. Stop and report the msg to you. A 401 means there is a problem with the key, IP whitelist or account. A 403 means there aren't enough credits, or the key has reached its quota. If the error is api_key_quota_exceeded, wait until quota_resets_at.
• 429: wait and retry with increasing delays. Limit how many requests run at once. Default limits are 25 per second for /verify/single, 3 per second for /verify/bulk and 5 per second for /account. You can get your current limits from GET /v1/account.
• 500: retry a few times with a delay, then report it. Check the status of anything you already submitted before you resubmit it.

• Start with a small sample. Run a few emails from the list to confirm the agent's workflow before it submits everything.
• Check progress at a sensible pace. Poll GET /v1/verify/bulk/status every 30 to 60 seconds. You can also set a url_finished webhook if you have a public endpoint.
• Get every page of results. GET /v1/verify/bulk/dump returns results in pages, so keep requesting with the new cursor until it is null.
• Check the CSV upload order. In /v1/verify/bulk/file, the file field must be the last field in the form. Set email_column too, so the task doesn't depend on auto-detection.
• Write large results to a file. Have the agent save them to disk and report totals, rather than reading thousands of rows into the conversation.
• Use webhooks carefully. A webhook set with url sends an event for each email, and its payload is a JSON array. Failed deliveries are retried only up to 2 more times, so use /v1/verify/bulk/dump to confirm you have every result.

• Starts a large bulk task. It should first compare the number of emails with available_credits from GET /v1/account.
• Stops a task with POST /v1/verify/bulk/stop. Emails without a result are refunded, but they aren't verified. Learn more: Stopping a Running Bulk Verification Task.
• Deletes a task with POST /v1/verify/bulk/destroy. This removes the task and its data immediately and can't be undone.

• Give the agent a file path rather than pasting a list into the chat.
• Treat export links as sensitive. The download_url from /v1/verify/bulk/export is a public link that works for 4 hours, so keep it out of logs, tickets and commits.
• Keep real contact lists out of your repository, including test files.

• deliverable: safe to send.
• undeliverable: will bounce. Don't send.
• risky: may bounce. Check score, where higher is better. Don't include or remove these automatically. The right cutoff depends on your email provider's bounce limit. Learn more: How do I choose the right emails to export.
• unknown: verification couldn't determine a result. Don't treat it as undeliverable.
• is_accept_all: true doesn't mean risky. BounceBan identifies which accept-all emails are actually deliverable, so use result to decide. Don't filter out emails based on this flag alone.

• mode=deepverify assumes the email's domain matches the owner's current company website, for example when the data comes from LinkedIn. Don't turn it on for every list. Learn more: What is DeepVerify?
• disable_catchall_verify=1 skips accept-all and SEG verification. Those emails return unknown with a score of -1 and cost 0 credits. Make sure your code handles a score of -1.

• Put all BounceBan calls in one small client, with timeouts, retry rules and concurrency limits in a single place.
• Save the verification id or task id with your own record, so a restart doesn't charge you again.
• Use mocked responses in unit tests and CI. Calls to the live API use real credits.
• Use a separate key with a low quota for any live testing. For test credits, contact [email protected].