Official Python SDK for the BillionVerify email verification API.
PyPI: https://pypi.org/project/billionverify/ Documentation: https://billionverify.com/docs
pip install billionverifyfrom billionverify import BillionVerify
client = BillionVerify(api_key="your-api-key")
# Verify a single email
result = client.verify("user@example.com")
print(result.status) # 'valid', 'invalid', 'unknown', 'risky', 'disposable', 'catchall', 'role'
print(result.is_deliverable) # True or Falseclient = BillionVerify(
api_key="your-api-key", # Required
base_url="https://api.billionverify.com/v1", # Optional
timeout=30.0, # Optional: Request timeout in seconds (default: 30)
retries=3, # Optional: Number of retries (default: 3)
)Uses the /verify/single endpoint:
result = client.verify(
email="user@example.com",
check_smtp=None, # Optional: force SMTP on/off; left out, the server default applies
force_refresh=False, # Optional: Bypass cache and force live verification (default: False)
include_domain_reputation=False, # Optional: Include domain reputation details (default: False)
)
# Flat response structure
print(result.email) # 'user@example.com'
print(result.status) # 'valid', 'invalid', 'unknown', 'risky', 'disposable', 'catchall', 'role'
print(result.score) # 0.95
print(result.is_deliverable) # True
print(result.is_disposable) # False
print(result.is_catchall) # False
print(result.is_role) # False
print(result.is_free) # True
print(result.domain) # 'example.com'
print(result.reason) # 'Valid email address'
print(result.check_smtp) # True (whether SMTP was performed)
print(result.domain_suggestion) # None or suggested domain correction
print(result.credits_used) # 1
# Response metadata for audit logs and throttled runners
print(result.response_metadata.request_id) # Server X-Request-ID
print(result.response_metadata.rate_limit_remaining) # Remaining requests in current windowVerify up to 50 emails synchronously using verify_bulk():
# Synchronous bulk verification (max 50 emails)
response = client.verify_bulk(
emails=["user1@example.com", "user2@example.com", "user3@example.com"],
check_smtp=True, # Optional
)
# Returns BulkVerifyResponse directly
print(f"Total: {response.total_emails}")
print(f"Credits used: {response.credits_used}")
for result in response.results:
print(f"{result.email}: {result.status}")
print(f" Deliverable: {result.is_deliverable}")
print(f" Disposable: {result.is_disposable}")
print(f" Catchall: {result.is_catchall}")
print(f" Role: {result.is_role}")For large lists, use upload_file() for asynchronous file verification:
# Upload a file for async verification
task = client.upload_file(
file_path="emails.csv",
email_column="email", # Column name for CSV files
preserve_original=True, # Optional; left out, the server default (True) applies
)
print(f"Task ID: {task.task_id}")
print(f"Status: {task.status}")
print(f"Estimated count: {task.estimated_count}")
# Get task status (with optional long-polling)
status = client.get_file_task_status(
task_id=task.task_id,
timeout=60, # Long-poll for up to 60 seconds (0-300)
)
print(f"Progress: {status.progress}%")
print(f"Processed: {status.processed_emails}/{status.total_emails}")
# Wait until the task stops moving on its own (polling). Returns on completed,
# completed_with_warning, failed, cancelled or paused.
completed = client.wait_for_file_task(
task_id=task.task_id,
poll_interval=5.0, # seconds
max_wait=600.0, # seconds
)
print(completed.deliverability_buckets.strict_deliverable)
# A paused task continues with:
client.resume_job(task.task_id)
# Download results as CSV with optional filters
output_file = client.download_file_results(
task_id=task.task_id,
output_path="results.csv",
valid=True, # Include valid emails
invalid=True, # Include invalid emails
unknown=True, # Include unknown emails
risky=True, # Include risky emails
disposable=True, # Include disposable emails
catchall=True, # Include catch-all emails
role=True, # Include role-based emails
)
print(f"Results saved to: {output_file}")get_file_job_status and wait_for_file_job are aliases of get_file_task_status and wait_for_file_task.
Result files are served from a pre-signed storage URL. The SDK follows that redirect itself and does not send your API key to the storage host.
client.check_disposable("someone@mailinator.com").is_disposable # POST
client.check_disposable_via_query("someone@mailinator.com").is_disposable # GETGive a domain, get the emails published on its site, each one verified. It runs asynchronously and costs 5 credits per returned email; max_emails (1-200) caps the bill.
search = client.create_domain_search("example.com", max_emails=20, include_role_based=False, max_pages=100)
done = client.wait_for_domain_search(search.search_id) # completed, completed_with_warning or failed
for item in done.result["emails"]:
print(item["email"])
# A CSV of domains
batch = client.create_domain_search_batch("domains.csv", max_emails=10, column_map={"domain": "Company Website"})
client.get_domain_search_batch(batch.batch_id).progress.processed
client.list_domain_search_batches(limit=20, status="completed").items
csv_text = client.download_domain_search_batch_results(batch.batch_id) # 409 until the batch has finished
client.download_domain_search_batch_results(batch.batch_id, "batch.csv") # or save to a fileThe async client has the same methods (await client.create_domain_search(...)).
import asyncio
from billionverify import AsyncBillionVerify
async def main():
async with AsyncBillionVerify(api_key="your-api-key") as client:
# Single verification
result = await client.verify("user@example.com")
print(result.status)
# Bulk verification
response = await client.verify_bulk([
"user1@example.com",
"user2@example.com"
])
for r in response.results:
print(f"{r.email}: {r.status}")
asyncio.run(main())Check API health status (no authentication required):
health = client.health_check()
print(health.status) # 'ok'
print(health.version) # API versioncredits = client.get_credits()
print(credits.credits_balance) # Available credits
print(credits.credits_consumed) # Credits used
print(credits.credits_added) # Total credits added
print(credits.api_key_name) # API key nameWebhooks support events: file.completed, file.failed
# Create a webhook
webhook = client.create_webhook(
url="https://your-app.com/webhooks/billionverify",
events=["file.completed", "file.failed"],
)
print(f"Webhook ID: {webhook.id}")
print(f"Secret: {webhook.secret}") # Save this for signature verification
# List webhooks
webhooks = client.list_webhooks()
for wh in webhooks:
print(f"{wh.id}: {wh.url}")
# Delete a webhook
client.delete_webhook(webhook.id)
# Verify a delivery
from billionverify import verify_webhook_delivery
is_valid = verify_webhook_delivery(
payload=raw_body, # exactly as received
signature=headers["X-Webhook-Signature"], # sha256=<hex>
timestamp=headers["X-Webhook-Timestamp"], # Unix seconds
secret="your-webhook-secret",
tolerance=300, # deliveries older (or newer) than this are rejected; 0 turns the check off
)The server signs "<timestamp>.<raw body>" with HMAC-SHA256. BillionVerify.verify_webhook_signature(payload, signature, secret), which checks the body alone, does not match a real delivery; use verify_webhook_delivery. A blank secret or a malformed timestamp always returns False.
from billionverify import (
BillionVerify,
BillionVerifyError,
AuthenticationError,
RateLimitError,
ValidationError,
InsufficientCreditsError,
NotFoundError,
TimeoutError,
)
try:
result = client.verify("user@example.com")
except AuthenticationError:
print("Invalid API key")
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after} seconds")
print(f"Request ID: {e.response_metadata.request_id}")
except ValidationError as e:
print(f"Invalid input: {e.message}")
except InsufficientCreditsError:
print("Not enough credits")
except NotFoundError:
print("Resource not found")
except TimeoutError:
print("Request timed out")
except BillionVerifyError as e:
# Catch-all for anything else, including the response-shape codes below.
print(f"{e.code}: {e.message}")The SDK never lets a malformed API reply leak out as a raw KeyError,
TypeError, or json.JSONDecodeError. Empty bodies, null payloads,
non-JSON content, and responses missing required fields are all surfaced
as a typed BillionVerifyError with response_metadata populated, so you
can recover and log the request ID:
error.code |
When it fires |
|---|---|
EMPTY_RESPONSE |
2xx with no body, or envelope {"data": null} |
INVALID_RESPONSE |
Non-JSON body, wrong top-level shape, or missing fields |
try:
result = client.verify("user@example.com")
except BillionVerifyError as e:
if e.code in ("EMPTY_RESPONSE", "INVALID_RESPONSE"):
log.error("bad upstream reply", extra={
"request_id": e.response_metadata.request_id,
"status": e.response_metadata.status_code,
"details": e.details,
})
raisewith BillionVerify(api_key="your-api-key") as client:
result = client.verify("user@example.com")
print(result.status)
# Connection is automatically closedThis SDK includes full type annotations for IDE support and type checking.
from billionverify import (
VerificationResult,
BulkVerifyResponse,
FileUploadResponse,
FileTaskStatus,
CreditsResponse,
DomainSearchStatus,
VerificationStatus,
)
def process_result(result: VerificationResult) -> None:
if result.status == "valid":
print(f"Email {result.email} is valid")
if result.is_deliverable and not result.is_disposable:
print("Safe to send to this email")The verification status can be one of:
valid- Email is valid and deliverableinvalid- Email is invalid or does not existunknown- Could not determine statusrisky- Email exists but may have delivery issuesdisposable- Temporary/disposable email addresscatchall- Domain accepts all emails (catch-all)role- Role-based email (e.g., info@, support@)
MIT