byebouncer-sdk

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-sdk

Requires Python 3.9+.

The distribution is named byebouncer-sdk; the Python import remains byebouncer. To upgrade an existing installation, run pip install --upgrade byebouncer-sdk. The default API URL is https://api.byebouncer.com; each user supplies their own secret API key from the dashboard. Keep keys in environment variables on your server.

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 5.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

import httpx

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)
    response = httpx.get(download.url, timeout=30)
    response.raise_for_status()
    csv = response.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.

Production use

Clients use a 30-second network timeout by default, including CSV downloads. Configure timeout= for slower connections. When supplying your own httpx client, configure its timeout directly and close it yourself.

Bulk helpers raise bulk_not_completed for failed, cancelled or expired jobs and for completed jobs without downloadable results. Prefer webhooks for large jobs. Requests are not automatically retried: a timed-out verification may already have consumed credits. To retry bulk creation safely, reuse the same idempotency_key with bulk().

Support

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

License

MIT © ByeBouncer