Skip to content

Latest commit

 

History

37 Commits

Folders and files

Repository files navigation

BillionVerify Python SDK

Official Python SDK for the BillionVerify email verification API.

PyPI version Python Versions

PyPI: https://pypi.org/project/billionverify/ Documentation: https://billionverify.com/docs

Installation

pip install billionverify

Quick Start

from 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 False

Configuration

client = 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)
)

Single Email Verification

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 window

Bulk Email Verification (Synchronous)

Verify 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}")

File Upload (Async Verification)

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.

Free Disposable Check

client.check_disposable("someone@mailinator.com").is_disposable          # POST
client.check_disposable_via_query("someone@mailinator.com").is_disposable  # GET

Domain Search

Give 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 file

The async client has the same methods (await client.create_domain_search(...)).

Async Support

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

Health Check

Check API health status (no authentication required):

health = client.health_check()
print(health.status)   # 'ok'
print(health.version)  # API version

Credits

credits = 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 name

Webhooks

Webhooks 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.

Error Handling

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}")

Malformed or empty server responses

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,
        })
    raise

Context Manager

with BillionVerify(api_key="your-api-key") as client:
    result = client.verify("user@example.com")
    print(result.status)
# Connection is automatically closed

Type Hints

This 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")

Status Values

The verification status can be one of:

  • valid - Email is valid and deliverable
  • invalid - Email is invalid or does not exist
  • unknown - Could not determine status
  • risky - Email exists but may have delivery issues
  • disposable - Temporary/disposable email address
  • catchall - Domain accepts all emails (catch-all)
  • role - Role-based email (e.g., info@, support@)

License

MIT