byebouncer-sdk

Official Python SDK for the ByeBouncer email verification API.

Sync and async clients for email, IP and phone verification, email-only bulk jobs (up to 5,000 unique emails per job), CSV downloads and 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
import os
from byebouncer import AsyncByeBouncer

async def main():
    async with AsyncByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
        result = await client.verify("user@gmail.com")
        print(result.status)

asyncio.run(main())

Bulk verification

with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
    created = client.bulk(
        emails=["a@gmail.com", "b@outlook.com"],  # up to 5,000 unique emails
        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

with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
    final = client.bulk_wait_for_completion(
        job.id,
        interval_seconds=3,
        timeout_seconds=120,
        on_progress=lambda j: print(f"{j.processed}/{j.total_emails}"),
    )
    if final.status != "completed" or not final.result_available:
        raise RuntimeError(f"Job finished without results: {final.status}")
    download = client.bulk_download_url(final.id)

response = httpx.get(download.url, timeout=30)
response.raise_for_status()
with open("results.csv", "w", encoding="utf-8") as output:
    output.write(response.text)

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:

with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
    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

Cancel a pending or processing job; a completed job can no longer be cancelled.

with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
    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.

import os
from byebouncer import InsufficientCreditsError, RateLimitError, ByeBouncer

with ByeBouncer(api_key=os.environ["BB_API_KEY"]) 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

The supported methods are listed below. Endpoints are relative to /api/v1; see the public API documentation for complete setup and REST examples. Async clients expose the same methods with await.

Combined lead verification, HLR (live: true), suggestions and domain lookups are available through REST. Version 0.2.3 has no dedicated SDK methods for them. bulk_ip() and bulk_phone() are retired and fail locally; bulk supports email only.

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. Avoid default Authorization headers on an injected client: it is also used for signed CSV downloads, which must not receive API credentials.

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().

bulk_and_wait() does not accept an idempotency key. If creation needs safe retries, use bulk() with a unique key per logical import and preserve that key and its request body across retries, then poll and download separately.

Charges and limits

• Email: 1 credit per verification, including cached answers.
• IP: 1 credit per public, routable IP; invalid_scope results are free.
• Phone: 1 credit for a valid local result or 3 for a billable enriched result. Inconclusive and blacklisted results are free; billable cached answers are charged.
• HLR is an optional REST operation costing 6 additional credits per conclusive lookup.
• Bulk: email only, up to 5,000 unique emails per job. Credits are reserved on creation. Cancellation refunds unprocessed items; failed jobs refund the full debit.

Support

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

License

MIT © ByeBouncer