Two Ways to Use BounceZero

Batch Mode — List Cleaners

Run manually or schedule via cron

Each list cleaner connects directly to your ESP/CRM, pulls all contacts, sends them to BounceZero for bulk verification, then automatically removes or flags the bad ones.

Connects via platform API (no webhooks needed)

Concurrent verification — thousands/min

--dry-run flag — preview before taking action

Exports CSV/JSON report of every result

pip install httpx python-dotenv
BZ_API_KEY=bz_live_... python bz_mailchimp_cleaner.py --dry-run

Real-time Mode — Webhooks

Docker Compose, always-on

Each ESP sends a webhook event when a new subscriber is added. The webhook handler immediately verifies the email and removes or flags it before your first send.

21 webhook handlers (one per platform)

HMAC signature verification on every request

FastAPI + uvicorn, runs behind Nginx

One docker compose up starts all 21 handlers

cp .env.example .env && nano .env
docker compose up -d

Universal Flags (all list cleaners)

--dry-run

Preview mode — fetch and verify but take no action in the platform

--days N

Only process contacts added in the last N days (e.g. --days 30)

--min-score N

Score threshold below which a contact is considered invalid (default: 50)

--action X

What to do with invalid contacts (unsubscribe / delete / both / etc.)

--output FILE

Save results to a CSV or JSON file (e.g. --output results.csv)

--concurrency N

How many emails to verify in parallel (default: 10)

Email Service Providers

Mailchimp

Auth: API Key

⚡ webhook .zip

Fetches all list members, bulk-verifies them, then unsubscribes or deletes contacts with bad email addresses.

Environment Variables

MC_API_KEY

Mailchimp API key

MC_LIST_ID

Audience list ID (e.g. abc123)

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set status to unsubscribed (default)

delete

Permanently remove member

both

Unsubscribe + delete

CLI Flags

--mc-key --list-id --action --tag --min-score --days --dry-run --output

Klaviyo

Auth: API Key

⚡ webhook .zip

Pulls all profiles from a Klaviyo list, verifies addresses, then suppresses or deletes invalid profiles.

Environment Variables

KLAVIYO_API_KEY

Klaviyo private API key

KLAVIYO_LIST_ID

List ID (e.g. XXXXXX)

BZ_API_KEY

BounceZero API key

Available Actions

suppress

Add to global suppression list (default)

delete

Hard-delete the profile

both

Suppress + delete

CLI Flags

--klaviyo-key --list-id --action --min-score --days --dry-run --output

ActiveCampaign

Auth: API Key + URL

⚡ webhook .zip

Fetches all contacts from ActiveCampaign, verifies them, then unsubscribes or deletes invalid contacts.

Environment Variables

AC_API_URL

Your account URL (e.g. https://youracccount.api-us1.com)

AC_API_KEY

ActiveCampaign API key

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set contact status to unsubscribed (default)

delete

Permanently delete contact

both

Unsubscribe + delete

CLI Flags

--ac-url --ac-key --action --min-score --days --dry-run --output

Brevo

Auth: API Key

⚡ webhook .zip

Fetches all contacts from Brevo (formerly Sendinblue), verifies them, and blacklists or deletes bad addresses.

Environment Variables

BREVO_API_KEY

Brevo API key

BZ_API_KEY

BounceZero API key

Available Actions

blacklist

Add to Brevo blocklist (default)

delete

Permanently delete contact

both

Blacklist + delete

CLI Flags

--brevo-key --action --min-score --days --dry-run --output

SendGrid

Auth: API Key

⚡ webhook .zip

Iterates over all SendGrid contacts, verifies each email, and adds invalid ones to the global suppression (unsubscribe) list.

Environment Variables

SENDGRID_API_KEY

SendGrid API key (Full Access)

BZ_API_KEY

BounceZero API key

Available Actions

suppress

Add to global unsubscribe list (default)

delete

Delete from all lists + account

CLI Flags

--sg-key --action --min-score --days --dry-run --output

Constant Contact

Auth: OAuth 2.0 Access Token

⚡ webhook .zip

Fetches contacts from Constant Contact, verifies them, and unsubscribes or removes bad email addresses.

Environment Variables

CC_ACCESS_TOKEN

OAuth access token

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set status to OPTOUT (default)

delete

Hard-delete contact

CLI Flags

--cc-token --action --min-score --days --dry-run --output

ConvertKit

Auth: API Key + Secret

⚡ webhook .zip

Fetches all subscribers from ConvertKit, verifies them, then unsubscribes or removes contacts with bad addresses.

Environment Variables

CK_API_KEY

ConvertKit API key

CK_API_SECRET

ConvertKit API secret

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Unsubscribe from all sequences/forms (default)

delete

Permanently delete subscriber

CLI Flags

--ck-key --ck-secret --action --min-score --days --dry-run --output

GetResponse

Auth: API Key

⚡ webhook .zip

Fetches all contacts from GetResponse, verifies them, then marks invalid contacts as spam or deletes them.

Environment Variables

GR_API_KEY

GetResponse API key

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Mark as unsubscribed (default)

delete

Delete contact from account

CLI Flags

--gr-key --action --min-score --days --dry-run --output

AWeber

Auth: OAuth 2.0

⚡ webhook .zip

Fetches subscribers from an AWeber list, verifies them, and unsubscribes or deletes invalid contacts via OAuth.

Environment Variables

AWEBER_CLIENT_ID

OAuth client ID

AWEBER_CLIENT_SECRET

OAuth client secret

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set subscriber status to unsubscribed (default)

delete

Remove from list entirely

CLI Flags

--client-id --client-secret --list-id --action --min-score --days --dry-run --output

Campaign Monitor

Auth: API Key

⚡ webhook .zip

Pulls all subscribers from a Campaign Monitor list, verifies them, and unsubscribes or removes bad addresses.

Environment Variables

CM_API_KEY

Campaign Monitor API key

CM_LIST_ID

Subscriber list ID

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Unsubscribe (keeps record, default)

delete

Permanently delete subscriber

CLI Flags

--cm-key --list-id --action --min-score --days --dry-run --output

Omnisend

Auth: API Key

⚡ webhook .zip

Fetches all contacts from Omnisend, verifies their email addresses, and unsubscribes or deletes invalid contacts.

Environment Variables

OMNISEND_API_KEY

Omnisend API key

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set contact status to nonSubscribed (default)

delete

Hard-delete contact

CLI Flags

--omnisend-key --action --min-score --days --dry-run --output

MailerLite

Auth: API Key

⚡ webhook .zip

Fetches all subscribers from MailerLite, verifies them, and unsubscribes or deletes contacts with bad addresses.

Environment Variables

MAILERLITE_API_KEY

MailerLite API key (v3)

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set status to unsubscribed (default)

delete

Permanently delete subscriber

CLI Flags

--ml-key --group-id --action --min-score --days --dry-run --output

Drip

Auth: API Key + Account ID

⚡ webhook .zip

Fetches all subscribers from a Drip account, verifies them, and unsubscribes or deletes invalid contacts.

Environment Variables

DRIP_API_KEY

Drip API key

DRIP_ACCOUNT_ID

Drip account ID (numeric)

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set subscriber status to unsubscribed (default)

delete

Hard-delete subscriber

CLI Flags

--drip-key --account-id --action --min-score --days --dry-run --output

Moosend

Auth: API Key

⚡ webhook .zip

Fetches all subscribers from a Moosend mailing list, verifies them, and unsubscribes or removes invalid addresses.

Environment Variables

MOOSEND_API_KEY

Moosend API key

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Unsubscribe from mailing list (default)

delete

Remove subscriber permanently

CLI Flags

--moosend-key --list-id --action --min-score --days --dry-run --output

Iterable

Auth: API Key

⚡ webhook .zip

Exports all users from Iterable via NDJSON streaming, verifies them, then disables or deletes invalid users.

Environment Variables

IT_API_KEY

Iterable API key

BZ_API_KEY

BounceZero API key

Available Actions

disable

Disable user (opt out of all lists, default)

delete

Permanently delete user

CLI Flags

--it-key --action --min-score --days --dry-run --output

CRM & Lifecycle

HubSpot

Auth: Private App Token

⚡ webhook .zip

Fetches all contacts from HubSpot CRM, verifies their email, and unsubscribes or deletes invalid contacts via Private App token.

Environment Variables

HUBSPOT_TOKEN

HubSpot private app access token

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set hs_email_optout = true (default)

delete

Permanently delete CRM contact

both

Unsubscribe + delete

CLI Flags

--hs-token --action --min-score --days --dry-run --output

Intercom

Auth: Access Token

⚡ webhook .zip

Fetches all contacts from Intercom (v2.10), verifies them, and archives or tags contacts with bad email addresses.

Environment Variables

IC_ACCESS_TOKEN

Intercom access token (Settings → Integrations → API keys)

BZ_API_KEY

BounceZero API key

Available Actions

archive

Soft-delete contact (reversible, default)

tag

Apply a tag to the contact

both

Tag + archive

CLI Flags

--ic-token --action --tag --min-score --days --dry-run --output

Customer.io

Auth: App API Key

⚡ webhook .zip

Fetches all people from Customer.io, verifies their email, and suppresses or deletes invalid contacts.

Environment Variables

CIO_APP_API_KEY

Customer.io App API key (Settings → API Credentials → App API Keys)

BZ_API_KEY

BounceZero API key

Available Actions

suppress

Mark as unsubscribed via suppress endpoint (default)

delete

Permanently delete person

both

Suppress + delete

CLI Flags

--cio-key --action --min-score --days --dry-run --output

Loops

Auth: API Key

⚡ webhook .zip

Fetches all contacts from Loops (loops.so), verifies them, and unsubscribes or deletes invalid contacts.

Environment Variables

LOOPS_API_KEY

Loops API key (Settings → API)

BZ_API_KEY

BounceZero API key

Available Actions

unsubscribe

Set mailingLists to unsubscribed (default)

delete

Permanently delete contact

both

Unsubscribe + delete

CLI Flags

--loops-key --action --min-score --days --dry-run --output

Newsletter Platforms

Beehiiv

Auth: API Key + Publication ID

.zip

Fetches all subscribers from a Beehiiv publication, verifies their email, then archives or deletes invalid subscribers.

Environment Variables

BH_API_KEY

Beehiiv API key (Settings → API)

BH_PUB_ID

Publication ID (e.g. pub_xxxxxxxx)

BZ_API_KEY

BounceZero API key

Available Actions

archive

Move to archived state (default)

delete

Permanently delete subscriber

both

Archive + delete

CLI Flags

--bh-key --pub-id --action --min-score --days --dry-run --output

Ghost

Auth: Admin API Key (JWT, auto-generated)

.zip

Fetches all newsletter members from a self-hosted or Ghost.io site, verifies them, then deletes or labels invalid members. Uses JWT auth generated automatically from the Admin API key.

Environment Variables

GHOST_URL

Ghost Admin API base URL (e.g. https://yoursite.ghost.io)

GHOST_ADMIN_KEY

Admin API key in format key_id:secret

BZ_API_KEY

BounceZero API key

Available Actions

delete

Delete member (default — Ghost has no unsubscribe concept)

tag

Apply a label to mark member invalid

CLI Flags

--ghost-url --ghost-key --action --min-score --days --dry-run --output

Automation & No-Code

Zapier

Auth: BounceZero API Key (via Zapier auth)

.zip

A full Zapier Platform CLI app with 4 triggers/actions. Push to your Zapier account and connect BounceZero to 6,000+ apps.

npm install && zapier push

Auth Setup

Credentials are configured inside the platform after installation — no environment variables needed on your server.

Available Actions

Verify Email

Verify a single email address, returns score + status

Check Domain

Check MX records and domain health

Bulk Verify

Submit up to 500 emails at once

Find Verification

Look up a previous verification result by email

n8n

Auth: BounceZero API Key (n8n credential)

.zip

An n8n community node that adds BounceZero as a native node in your n8n workflows. Supports single verify, bulk verify, and domain checks.

npm install && n8n start

Auth Setup

Credentials are configured inside the platform after installation — no environment variables needed on your server.

Available Actions

verifyEmail

Verify a single email address

bulkVerify

Verify a batch of emails from previous nodes

checkDomain

Check domain MX / health

Make.com

Auth: BounceZero API Key (Make connection)

.zip

A Make.com custom app (app.json) that adds BounceZero as a module in your Make scenarios. Import once, use in any scenario.

Import app.json in Make.com → Custom Apps

Auth Setup

Credentials are configured inside the platform after installation — no environment variables needed on your server.

Available Actions

Verify Email

Verify one email, returns full result

Bulk Verify

Send multiple emails, get results in one call

Check Domain

Domain MX + deliverability check

CMS & eCommerce

WordPress & WooCommerce

Auth: BounceZero API Key (set in WP Admin → Settings → BounceZero)

.zip

PHP plugin that validates emails in real time at WordPress user registration, WooCommerce checkout, and contact forms. Invalid emails are blocked before they enter your database.

Upload plugin folder → WP Admin → Plugins → Activate

Environment Variables

BZ_API_KEY

Set via WP Admin settings panel, or define in wp-config.php

Available Actions

block

Reject form submission with error message (default)

warn

Show warning but allow submission

Shopify

Auth: BounceZero API Key (set in app settings after install)

.zip

A Remix-based Shopify app with a checkout UI extension that validates customer email addresses before the order completes.

shopify app deploy → install from Partner Dashboard

Environment Variables

BZ_API_KEY

Set in Shopify app settings panel after installation

SHOPIFY_API_KEY

Generated during app setup

Available Actions

block

Show validation error on the checkout page (default)

PrestaShop

Auth: BounceZero API Key (set in module configuration)

.zip

PHP module that validates customer emails at account creation and checkout in real time. Drop into /modules/ and activate from the PrestaShop back office.

Copy module folder to /modules/ → Back Office → Activate

Environment Variables

BZ_API_KEY

Set in PrestaShop back office → Modules → BounceZero → Configure

Available Actions

block

Prevent order/registration with invalid email (default)

Ready to clean your list?

Download the integration for your platform, add your API keys, and run with --dry-run first.

Download integrations Get API key →

How Every Integration Works

Mailchimp

Klaviyo

ActiveCampaign

Brevo

SendGrid

Constant Contact

ConvertKit

GetResponse

AWeber

Campaign Monitor

Omnisend

MailerLite

Drip

Moosend

Iterable

HubSpot

Intercom

Customer.io

Loops

Beehiiv

Ghost

Zapier

n8n

Make.com

WordPress & WooCommerce

Shopify

PrestaShop

Ready to clean your list?