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)
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.
| 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_scoperesults 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.