validkit 1.2.0

Python SDK for ValidKit Email Verification API - Built for AI Agents

ValidKit Python SDK

Email validation for signup flows -- block junk without blocking [e-mail]. Sync and async clients, batch support up to 10K emails, automatic retries, and Pydantic models.

Installation

pip install validkit

Requires Python 3.8+.

Quick Start

from validkit import ValidKit

client = ValidKit("your_api_key")
result = client.verify("[e-mail]")
print(result.v)  # True or False
client.close()

Or with a context manager:

from validkit import ValidKit

with ValidKit("your_api_key") as client:
    # Single email
    result = client.verify("[e-mail]")
    print(result.v)

    # Batch -- compact format by default
    results = client.verify_batch([
        "[e-mail]",
        "[e-mail]",
        "not-an-email",
    ])
    for email, r in results.items():
        print(f"{email}: valid={r.v}, disposable={r.d}")

Async usage

For high-throughput applications, use AsyncValidKit directly:

import asyncio
from validkit import AsyncValidKit

async def main():
    async with AsyncValidKit(api_key="your_api_key") as client:
        result = await client.verify_email("[e-mail]")
        print(result.valid)

asyncio.run(main())

Features

• Sync and async -- ValidKit for scripts, AsyncValidKit for high-throughput
• Batch verification -- up to 10,000 emails per call, chunked automatically
• Developer Pattern Intelligence -- understands test@, +addressing, disposable domains
• Compact format -- token-efficient responses (v, d, r fields) enabled by default
• Streaming -- async for results as they complete
• Webhook delivery -- fire-and-forget async batch jobs with callback
• Automatic retries -- exponential backoff, 3 retries default
• Type-safe -- Pydantic v2 models with full type hints

Advanced Usage

Custom configuration

from validkit import AsyncValidKit, ValidKitConfig

config = ValidKitConfig(
    api_key="your_api_key",
    timeout=30,           # seconds
    max_retries=3,        # retry count
    max_connections=100,   # connection pool size
    rate_limit=10000,     # requests/min (None = unlimited)
    compact_format=True,  # smaller payloads
)

async with AsyncValidKit(config=config) as client:
    result = await client.verify_email("[e-mail]")

Batch with progress tracking

def on_progress(processed, total):
    print(f"{processed}/{total} ({processed / total * 100:.1f}%)")

results = await client.verify_batch(
    emails,
    chunk_size=1000,
    progress_callback=on_progress,
)

Async batch with webhook

job = await client.verify_batch_async(
    emails=large_list,
    webhook_url="https://your-app.com/webhooks/validkit",
    webhook_headers={"Authorization": "Bearer token"},
)

# Poll until complete, or wait for webhook
job = await client.get_batch_status(job.id)
results = await client.get_batch_results(job.id)

# Cancel if needed
await client.cancel_batch(job.id)

Streaming

async for email, result in client.stream_verify(emails, batch_size=100):
    print(f"{email}: valid={result.v}")

Trace IDs

Attach a trace ID for cross-service debugging:

result = await client.verify_email("[e-mail]", trace_id="req_abc123")

Error Handling

from validkit.exceptions import (
    ValidKitError,       # base -- catches everything
    ValidKitAPIError,    # API errors (4xx, 5xx)
    InvalidAPIKeyError,  # 401
    RateLimitError,      # 429, includes retry_after
    BatchSizeError,      # batch exceeds 10K
    TimeoutError,        # request timeout (inherits ValidKitError, not API)
    ConnectionError,     # network failure (inherits ValidKitError, not API)
)

try:
    result = await client.verify_email("[e-mail]")
except RateLimitError as e:
    print(e.retry_after)  # seconds until retry
except InvalidAPIKeyError:
    print("Check your API key")
except ValidKitAPIError as e:
    print(e.message, e.status_code, e.code)
except ValidKitError as e:
    # Catches TimeoutError, ConnectionError, and any other non-API errors
    print(f"SDK error: {e}")

The SDK retries automatically on rate limits and transient errors (up to max_retries). Catch exceptions only if you need custom handling.

Compact Response Format

Default format. Smaller payloads, same information:

Field	Type	Meaning
v	bool	Email is valid
d	bool | None	Domain is disposable (None if not checked)
r	str | None	Reason (present only when invalid)

# Compact (default)
r = await client.verify_email("[e-mail]")
print(r.v, r.d, r.r)  # False, False, "invalid_format"

# Full format -- use when you need MX records, SMTP details
from validkit.models import ResponseFormat
full = await client.verify_email("[e-mail]", format=ResponseFormat.FULL)
if full.mx:
    print(full.mx.records)  # ["mx1.example.com"]

Examples

See examples/:

• basic_usage.py -- single verification, batch, streaming, configuration
• batch_processing.py -- large batches, CSV processing, webhook jobs, domain analysis

Contributing

See CONTRIBUTING.md.

Support

Docs -- GitHub Issues -- [e-mail]

License

MIT -- see LICENSE.