bouncebuster

Verify and clean email lists from your terminal or AI agent. This package ships two things that share one API client:

• a CLI (bouncebuster) for verifying addresses and cleaning files, and
• an MCP server (bouncebuster mcp) that exposes email verification as tools for AI agents.

It talks to the Bouncebuster REST API. Get an API key at https://app.bouncebuster.io/api-keys.

Install

npm install -g bouncebuster
# or run without installing:
npx bouncebuster --help

Requires Node.js 18+.

Authenticate

Set your key once via an environment variable (or pass --api-key on any command):

export BOUNCEBUSTER_API_KEY=bb_live_your_key_here

CLI usage

# Verify one or more addresses (up to 100 per command)
bouncebuster verify [email protected]
bouncebuster verify [email protected] [email protected] --json

# Clean a file (.csv, .tsv, .txt): extracts + de-dupes addresses,
# verifies, and writes the deliverable (valid) list to --out
bouncebuster clean contacts.csv --out cleaned.csv

# Also write every category to a folder
bouncebuster clean contacts.csv --all ./results

# Show plan and remaining credits
bouncebuster account

Each address is classified as valid, invalid, catch-all, disposable, or unknown.

Global options

| Option | Description | | --- | --- | | -k, --api-key <key> | API key (overrides BOUNCEBUSTER_API_KEY) | | --api-url <url> | API base URL (overrides BOUNCEBUSTER_API_URL) | | --json | Machine-readable JSON output |

MCP server

Run the Model Context Protocol server over stdio:

bouncebuster mcp

Configure it in an MCP client's mcpServers block:

{
  "mcpServers": {
    "bouncebuster": {
      "command": "npx",
      "args": ["-y", "bouncebuster", "mcp"],
      "env": { "BOUNCEBUSTER_API_KEY": "bb_live_your_key_here" }
    }
  }
}

Tools: verify_email, verify_batch, submit_list, get_list, get_account.

License

See https://bouncebuster.io for terms.