Verify an email list before you send to it

Verify an email list before you send to it

Cleans an email list, verifies every address with Bouncer, and splits it into send, review and remove lists with a reason for each.

Set up the tools below, then run the steps in order for the user, carrying each step's results into the next. The run is done when the user has the outcome below.

Outcome

• A send list of the deliverable addresses, with the columns the list came with, ready to import into your sending tool.
• A review list of the risky and unknown addresses, each with Bouncer's reason and flags.
• A remove list of the undeliverable addresses and the malformed rows, each with the reason it was dropped.
• A summary of how many addresses landed in each list and the credits the run used.

Inputs

Ask the user for these before you start.

• email_list: the list to verify, as a CSV or pasted rows, and the column that holds the email address, e.g. q4-webinar-leads.csv, column Email
• max_credits: the most credits this run may spend, e.g. 5000
• keep_catch_all: whether risky addresses on catch-all domains go to the send list instead of review, e.g. no

Set up

Bouncer (tool:bouncer/create-verification-batch, tool:bouncer/check-batch-status, tool:bouncer/get-batch-results, tool:bouncer/verify-email)

Use the first option your agent supports.

Notes:

• Create a verification batch: Send [{"email": "…"}]. Batches of 1,000 to 10,000 are recommended, and an account's batches run one after another. Returns 402 when credits run short. Poll the batch's status, then download its results.
• Check a verification batch's status: Poll about every 10 seconds until status is completed. credits is filled in only once the batch completes.
• Download a verification batch's results: Wait until the batch's status is completed. download is all, deliverable, risky, undeliverable or unknown. Returns JSON, or CSV with Accept: text/csv.
• Verify an email address: Costs 1 credit; unknown results are free. Answers within 10 seconds by default (timeout raises it, up to 30). A greylisted address returns retryAfter: verify it again after that time. Limited to 1,000 requests a minute.

MCP (official, remote)

Add this server to your agent's MCP settings, then sign in when asked.

{ "mcpServers": { "bouncer": { "url": "https://api.usebouncer.com/mcp" } } }

• Create a verification batch: call the MCP tool create_batch
• Check a verification batch's status: call the MCP tool check_batch_status
• Download a verification batch's results: call the MCP tool get_batch_results
• Verify an email address: call the MCP tool verify_email

API (official)

• Base URL: https://api.usebouncer.com
• Create a verification batch: POST /v1.1/email/verify/batch
• Check a verification batch's status: GET /v1.1/email/verify/batch/{batchId}
• Download a verification batch's results: GET /v1.1/email/verify/batch/{batchId}/download
• Verify an email address: GET /v1.1/email/verify
• Auth: send the header x-api-key: $BOUNCER_API_KEY
• Get a key: https://app.usebouncer.com

Note: Create the key in the app's API section. Batch jobs run one after another per account, so a 100,000-address batch delays the next one.

Before step 1, confirm access with the cheapest read-only call, like a list or a search. Never send or change anything to test access.

Steps

1. Clean the list yourself. Read email_list, trim spaces, lowercase each address and drop exact duplicates, keeping the first row of each. Move rows with no address or no @ and domain straight to the remove list with the reason malformed. Tell the user how many unique addresses remain and that verifying them costs up to that many credits; stop if it is more than max_credits. Keep the unique addresses and each one's original row.
2. Submit the batch with Create a verification batch (Bouncer). After the user approves the cost, send the unique addresses as one batch, or as batches of 10,000 when there are more than that. Keep each batchId.
3. Wait for it to finish with Check a verification batch's status (Bouncer). Check each batch about every 10 seconds, with with-stats=true, until its status is completed. Keep each batch's stats and credits.
4. Download the results with Download a verification batch's results (Bouncer). Download every batch with download set to all. Keep each address's status, reason, score, toxicity, any retryAfter, and the domain.acceptAll, domain.disposable, account.role and account.fullMailbox flags (each yes, no or unknown).
5. Retry the greylisted ones with Verify an email address (Bouncer). For each unknown address that came back with a retryAfter, wait until that time and verify it once more; skip this step when none did. Keep the new result in place of the old one.
6. Sort the list yourself. Put deliverable addresses on the send list. Put risky and unknown addresses on the review list, except that risky addresses with domain.acceptAll yes, and neither account.fullMailbox nor domain.disposable yes, go on the send list when keep_catch_all is yes. Put undeliverable addresses on the remove list. Join each address back to its original row and add columns for status, reason, score and the four flags.
7. Hand over the lists yourself. Give the user the send, review and remove lists as CSV files, and a table of how many addresses are in each, the most common reasons on the review and remove lists, and the credits all batches used.

Notes

Bouncer charges 1 credit per address and nothing for duplicates within a batch or for unknown results, so the cost in step 1 is an upper bound.

Bouncer marks an address risky when its domain accepts all mail (catch-all), its mailbox is full or it is disposable. keep_catch_all lets catch-all addresses through while full and disposable ones wait for review. Role accounts such as info@ stay on the send list when deliverable; filter on the account.role column if your sending tool or policy excludes them.

The lists are only as clean as the day they were checked. Verify again before a send to a list that is more than a few months old.

Rules

• Use only the services set up above. The read-only calls they need, like listing ids or polling for results, are fine.
• Ask the user before anything that sends messages, costs money, or changes data, and say how many records it touches. One approval covers a batch the user has seen.
• Never print API keys.