byebouncer

Official Python SDK for the ByeBouncer email verification API.

Sync and async clients, real-time single-email verification, bulk CSV verification (up to 50k emails per job), HMAC-signed webhooks.

Install

pip install byebouncer

Requires Python 3.9+.

Quickstart

import os
from byebouncer import ByeBouncer

with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
    result = client.verify("user@gmail.com")
    print(result.status)             # "deliverable" | "undeliverable" | "risky" | "unknown"
    print(result.action)             # "allow" | "review" | "block"
    print(result.signals)            # ["valid_syntax", "mx_found", ...]
    print(result.credits_remaining)

Get your BB_API_KEY from https://byebouncer.com/dashboard (format bb_live_...).

Async

import asyncio
from byebouncer import AsyncByeBouncer

async def main():
    async with AsyncByeBouncer(api_key="bb_live_...") as client:
        result = await client.verify("user@gmail.com")
        print(result.status)

asyncio.run(main())

Bulk verification

created = client.bulk(
    emails=["a@gmail.com", "b@outlook.com"],  # up to 50.000
    filename="my_list.csv",
    webhook_url="https://api.myapp.com/hooks/byebouncer",  # optional
)
job = created.job
print(f"Job {job.id}, {job.total_emails} emails")
print(f"Estimated duration: {created.estimated_seconds}s")

# Present when webhook_url is supplied (generated or supplied).
# Store it now: it is never returned by later job reads.
webhook_secret = created.webhook_secret

Polling for completion

final = client.bulk_wait_for_completion(
    job.id,
    interval_seconds=3,
    on_progress=lambda j: print(f"{j.processed}/{j.total_emails}"),
)

if final.status == "completed":
    download = client.bulk_download_url(final.id)
    csv = httpx.get(download.url).text
    open("results.csv", "w").write(csv)

Webhooks (recommended for large jobs)

Prefer webhooks over polling. On completion ByeBouncer POSTs to your URL with:

X-ByeBouncer-Event: bulk.completed
X-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>

Attach or rotate the webhook after creating the job:

result = client.bulk_set_webhook(
    job.id,
    webhook_url="https://api.myapp.com/hooks/byebouncer",
)
webhook_secret = result.webhook_secret  # store it NOW, returned only once

Cancel

cancelled = client.bulk_cancel(job.id)
print(f"Refunded {cancelled.credits_refunded} credits")

Error handling

Non-2xx responses raise ByeBouncerError or a subclass with code, status, detail.

from byebouncer import InsufficientCreditsError, RateLimitError, ByeBouncer

with ByeBouncer(api_key="bb_live_...") as client:
    try:
        client.verify("user@gmail.com")
    except InsufficientCreditsError as e:
        print(f"Out of credits (remaining: {e.credits_remaining})")
    except RateLimitError as e:
        print(f"Rate limited, retry after {e.retry_after_seconds}s")

API reference

Every method mirrors the OpenAPI spec.

Support

• Docs: https://byebouncer.com/docs
• Email: hello@byebouncer.com
• Issues: https://github.com/fidelp27/byebouncer/issues

License

MIT © ByeBouncer