revenuebase-sdk 0.1.0

Python SDK for the Revenuebase Email Verification and Company Resolver API.

Revenuebase Python SDK

Python SDK for the Revenuebase API — email validation and company resolution.

Requirements

• Python ≥ 3.8

Install

pip install revenuebase-sdk

Quickstart

from revenuebase_sdk import RevenuebaseClient

client = RevenuebaseClient(api_key="your-api-key")
# Or set REVENUEBASE_API_KEY in your environment and call RevenuebaseClient()

# Validate a single email
result = client.email_processing.validate_email(email="[e-mail]")
print(result.status)  # "Valid", "Invalid", or "Unknown"

# With full metadata
result = client.email_processing.validate_email(email="[e-mail]", metadata=True)
print(result.mx_record_present, result.email_provider)

# Check your credit balance
credits = client.user_operations.get_credits()
print(credits.credits)

Authentication

Pass your API key via the api_key parameter or the REVENUEBASE_API_KEY environment variable. The key is sent as the x-key header on every request.

export REVENUEBASE_API_KEY="your-api-key"

Resources

email_processing

Method	Description
validate_email(*, email, metadata=False)	Validate a single email. Returns Valid, Invalid, or Unknown.
batch_upload(*, file, filename, metadata=False)	Upload a .csv or .json file for async batch validation.
get_batch_status(*, process_id)	Poll the status of a batch job.
list_queued()	List all active (queued or processing) batch jobs.
cancel_batch(*, process_id)	Cancel a queued or in-progress batch job.
download_batch(*, process_id)	Download the results of a completed job as bytes.
batch_start(*, filename, metadata=False)	(Deprecated) Queue a pre-uploaded file. Use batch_upload instead.

user_operations

Method	Description
get_credits()	Get your remaining credit balance.
rotate_api_key()	Generate a new API key (invalidates the previous one immediately).

company_resolver

Method	Description
resolve(*, company_name, result_count=3, ...)	Match a company name to verified records using semantic search.
discover(*, keyword, result_count=1000, ...)	Discover companies matching a keyword or description.

Batch validation workflow

import time

# 1. Upload the file
with open("emails.csv", "rb") as f:
    job = client.email_processing.batch_upload(file=f, filename="emails.csv")

print(f"Job {job.process_id} queued")

# 2. Poll until complete
while True:
    status = client.email_processing.get_batch_status(process_id=job.process_id)
    print(status.current_status)
    if status.current_status in ("COMPLETED", "ERROR", "CANCELLED"):
        break
    time.sleep(5)

# 3. Download results
if status.current_status == "COMPLETED":
    data = client.email_processing.download_batch(process_id=job.process_id)
    with open("results.csv", "wb") as f:
        f.write(data)

Company resolution

# Match by name
result = client.company_resolver.resolve(
    company_name="Stripe",
    result_count=3,
    headquarters_country="US",
)
for company in result.companies:
    print(company.company_name, company.similar_score, company.headquarters_city)

# Discover by keyword
result = client.company_resolver.discover(
    keyword="enterprise cybersecurity SaaS",
    result_count=100,
    headquarters_country="US",
)

Async usage

import asyncio
from revenuebase_sdk import AsyncRevenuebaseClient

async def main():
    async with AsyncRevenuebaseClient(api_key="your-api-key") as client:
        result = await client.email_processing.validate_email(email="[e-mail]")
        print(result.status)

asyncio.run(main())

Error handling

from revenuebase_sdk import (
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    APIConnectionError,
)

try:
    result = client.email_processing.validate_email(email="[e-mail]")
except AuthenticationError:
    print("Invalid API key")
except BadRequestError as e:
    print(f"Bad request: {e.message}")
except RateLimitError:
    print("Rate limited — slow down requests")
except APIConnectionError as e:
    print(f"Network error: {e.message}")

Per-request options

# Override timeout for a single call
result = (
    client
    .with_options(timeout=5.0, max_retries=0)
    .email_processing.validate_email(email="[e-mail]")
)

Development

pip install -e ".[dev]"
pytest
mypy src
ruff check src