Skip to main content

byebouncer-sdk

Local IP checks (requires the updated server)

result = client.lookup_ip("8.8.8.8", checks=["network_data", "tor", "geolocation"])

The same checks option is available on the async client. Combined validation accepts ip_checks in validate(...). Omit the option to keep the existing default. Local checks do not call DNS/rDNS/DNSBL during IP validation. Catalogs must be installed on the server; absent or expired evidence is unavailable. no_match does not prove the absence of a VPN or proxy. Public IP pricing is unchanged.

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.

Independent validation services (0.4.0)

Choose an explicit service to control the information returned and its cost. The 0.4.0 methods use the factual validation-v1 contract: independent checks and attributes without scores or a contact acceptance decision. Existing methods and routes remain available for compatibility.

import os
from byebouncer import ByeBouncer
client = ByeBouncer(os.environ["BB_API_KEY"])
result = client.validate(email="person@example.com", phone="+12025550123", phone_mode="local", live=False)
print(result.results["email"]["deliverability"])
print(result.results["phone"]["checks"])

# One service at a time (0.4.0+):
client.validate_email("person@example.com")      # POST /verify-email · 1 credit
client.lookup_ip("8.8.8.8")                       # POST /verify-ip · 1 credit
client.validate_phone_local("+12025550123")       # POST /verify-phone/local · 1 credit
client.lookup_phone_carrier("+12025550123")        # POST /verify-phone/carrier · 3 credits
client.lookup_phone_network("+12025550123")        # POST /verify-phone/live · 6 credits
# In client.validate(...), pass phone_mode="local" | "carrier" to choose the phone service.
# 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.

Three phone validation levels

Level Information Credits per billable request
1 · Local Numbering-plan format, normalization, country and estimated type; no remote provider call 1
2 · Carrier Format validation and available carrier data; no extra format charge 3 total
3 · Mobile network Last network observation and timestamp; no call or message sent 6

The levels are independent. Network status needs no prior carrier lookup. Local plus network costs up to 7 credits; carrier plus network, up to 9. A valid format does not prove a live line; network registration does not guarantee an answered call. unknown can be a billable network answer, while provider errors and inapplicable lookups are not charged. Billable cache hits retain the same price.

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 score-free data-validation methods (return validation-v1) let you pick one service at a time:

Method Endpoint Credits
validate(...) POST /lead/verify per channel; phone_mode="local" | "carrier" picks the phone service
validate_email(email) POST /verify-email 1
lookup_ip(ip, ...) POST /verify-ip 1
validate_phone_local(phone, ...) POST /verify-phone/local 1
lookup_phone_carrier(phone, ...) POST /verify-phone/carrier 3
lookup_phone_network(phone, ...) POST /verify-phone/live 6

validate_phone(phone, ...) keeps the legacy behavior: carrier when configured, otherwise local. 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.4.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.4.0
File Size Uploaded Provenance Actions
byebouncer_sdk-0.4.0.tar.gz 18.0 kB Without provenance Details for byebouncer_sdk-0.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 33.2 kB

Release files / byebouncer_sdk-0.4.0.tar.gz

Download URL byebouncer_sdk-0.4.0.tar.gz
Size 18.0 kB
Tags Source
SHA-256 checksum
How to use checksums
cb4bcfb3e6c741366cb006cf9ff54302c038e69312d149981474c450c7987624
BLAKE2b-256 checksum
How to use checksums
0e31781cfd8c88a5c828e76a294061b7c9cb151d416f75f72a8ddef542593bbd
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.4.0-py3-none-any.whl

Download URL byebouncer_sdk-0.4.0-py3-none-any.whl
Size 15.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b787492fa5d3e96d6139f0b1e14ade91823fad496ddc6481e18e65a4ce8f4b79
BLAKE2b-256 checksum
How to use checksums
01d799ba9f3144e758a260517097c4de99d22500db1fd1bac044c6f7a49d8cbf
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.4.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