Skip to main content

byebouncer-sdk

Official Python SDK for the ByeBouncer data validation 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.

Billable cache hits cost the same as fresh results: email 1 credit, public IP 1, valid local phone 1 or conclusive carrier-enriched phone 3. Before the first purchase, phone checks also use a shared 30-credit starter quota.

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.

Data validation (0.3.0)

Use the new methods in version 0.3.0 or later for independent observations without scores or an acceptance decision. These methods require a backend supporting validation-v1. Earlier SDK versions retain their existing methods and response format.

import os
from byebouncer import ByeBouncer
client = ByeBouncer(os.environ["BB_API_KEY"])
result = client.validate(email="person@example.com", phone="+12025550123", live=False)
print(result.results["email"]["deliverability"])
print(result.results["phone"]["checks"])
# Individual methods: validate_email, validate_phone, lookup_ip.
# Factual email CSV: client.bulk(emails, result_format="validation-v1").
# AsyncByeBouncer exposes the same methods with await.

Examples are illustrative. completed describes execution, not a favorable finding. unavailable does not mean invalid. Domain attributes, number format and network observations do not establish identity, ownership or commercial intent. Mobile network lookup is optional and has its own cost; it does not prove someone will answer.

Existing methods below keep the legacy contract for compatibility. Do not interpret legacy scores as fraud probabilities.

Legacy 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

Download URLs expire after 15 minutes (900 seconds); request a fresh one when needed. Result CSVs are retained for 7 days after the job reaches a terminal state.

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)

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.

Method Endpoint Description
verify(email) POST /verify Verify a single email
verify_ip(ip) POST /verify-ip Analyze a single IP
verify_phone(phone, ...) POST /verify-phone Validate and enrich a phone number
add_phone_blacklist(phone, ...) POST /phone/blacklist Add a number to your blacklist
remove_phone_blacklist(phone, ...) DELETE /phone/blacklist Remove a number from your blacklist
credits() GET /credits Get balance
bulk(emails, ...) POST /bulk Enqueue a bulk job
bulk_status(job_id) GET /bulk/{id} Fetch job
bulk_cancel(job_id) DELETE /bulk/{id} Cancel
bulk_download_url(job_id) GET /bulk/{id}/download Signed CSV URL
bulk_set_webhook(job_id, ...) POST /bulk/{id}/webhook Attach/rotate webhook
bulk_wait_for_completion(job_id, ...) polls Convenience helper
bulk_and_wait(emails, ...) create+poll+download Available in sync and async clients

The data-validation methods above support combined contact checks and optional HLR. Suggestions and domain lookups remain available through REST. bulk_ip() and bulk_phone() are retired and fail locally; bulk supports email only.

Use a live server key for credits, bulk and blacklist operations. Public keys can verify email, IP and phone with an allowed Origin and an explicit allocation. credits is spendable key balance; wallet_balance, when present, is the shared account total. Buying credits does not automatically increase key allocations.

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

License

MIT © ByeBouncer

Metadata

Release files for byebouncer-sdk 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for byebouncer-sdk 0.3.0
File Size Uploaded Provenance Actions
byebouncer_sdk-0.3.0.tar.gz 16.0 kB Without provenance Details for byebouncer_sdk-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for byebouncer-sdk 0.3.0
File Interpreter ABI Platform Actions
byebouncer_sdk-0.3.0-py3-none-any.whl Python 3 none any Details for byebouncer_sdk-0.3.0-py3-none-any.whl

Total release size: 30.1 kB

Release files / byebouncer_sdk-0.3.0.tar.gz

Download URL byebouncer_sdk-0.3.0.tar.gz
Size 16.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f9bc005f7c8dffb91319aaec29c900ea22ef9a7fa2786b1588c7bcda9980cf23
BLAKE2b-256 checksum
How to use checksums
edbed67157865171f9fdf16ecc8e9827ccaa979ad0851647114737a808467832
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / byebouncer_sdk-0.3.0-py3-none-any.whl

Download URL byebouncer_sdk-0.3.0-py3-none-any.whl
Size 14.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88e4a318ddf65143b54a0246355ad842be8de75fa786222350a8007249b3ca53
BLAKE2b-256 checksum
How to use checksums
d71c1b7903f02baaf54945884907c6128329446f1b0615938b8f0ca9e2f7396b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for byebouncer-sdk 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page