Skip to main content

ValidKit Python SDK

Async Python SDK for ValidKit Email Verification API - Built for AI Agents and high-volume applications.

Features

  • 🚀 Fully Async: Built on aiohttp for maximum performance
  • 🤖 AI-Agent Optimized: Token-efficient responses and agent-friendly formats
  • 📦 Batch Processing: Verify up to 10,000 emails in a single request
  • 🔄 Smart Retries: Automatic retry logic with exponential backoff
  • 🌊 Connection Pooling: Efficient connection reuse for high throughput
  • 📊 Progress Tracking: Real-time progress updates for large batches
  • 🪝 Webhook Support: Async webhook handling for batch results
  • 🔍 Type Safety: Full type hints and Pydantic models

Installation

pip install validkit

Quick Start

import asyncio
from validkit import AsyncValidKit

async def main():
    # Initialize the client
    async with AsyncValidKit(api_key="your_api_key") as client:
        # Single email verification
        result = await client.verify_email("user@example.com")
        print(f"Valid: {result.valid}")
        
        # Batch verification
        emails = ["user1@example.com", "user2@example.com", "user3@example.com"]
        results = await client.verify_batch(emails)
        
        for email, result in results.items():
            print(f"{email}: {result.valid}")

asyncio.run(main())

Advanced Usage

Batch Processing with Progress

async def verify_large_batch():
    async with AsyncValidKit(api_key="your_api_key") as client:
        emails = ["email{}@example.com".format(i) for i in range(10000)]
        
        # Process with progress callback
        async def progress_callback(processed, total):
            print(f"Progress: {processed}/{total} ({processed/total*100:.1f}%)")
        
        results = await client.verify_batch(
            emails,
            chunk_size=1000,
            progress_callback=progress_callback
        )
        
        valid_count = sum(1 for r in results.values() if r.valid)
        print(f"Valid emails: {valid_count}/{len(emails)}")

Webhook Support

# Start async batch job with webhook
job = await client.verify_batch_async(
    emails=large_email_list,
    webhook_url="https://your-app.com/webhook/validkit",
    webhook_headers={"Authorization": "Bearer your_token"}
)

print(f"Batch job started: {job.id}")
print(f"Check status at: {job.status_url}")

Custom Configuration

from validkit import AsyncValidKit, ValidKitConfig

config = ValidKitConfig(
    api_key="your_api_key",
    base_url="https://api.validkit.com",
    timeout=30,
    max_retries=3,
    max_connections=100,
    rate_limit=10000  # requests per minute
)

async with AsyncValidKit(config=config) as client:
    # Your code here
    pass

Response Format

Single Email Response

{
    "valid": true,
    "email": "user@example.com",
    "format": {"valid": true},
    "disposable": {"valid": true, "value": false},
    "mx": {"valid": true, "records": ["mx1.example.com"]},
    "smtp": {"valid": true}
}

Batch Response (Compact Format)

{
    "user1@example.com": {"v": true, "d": false},
    "user2@example.com": {"v": false, "r": "invalid_format"},
    "user3@example.com": {"v": true, "d": true}
}

Where:

  • v: valid (boolean)
  • d: disposable (boolean)
  • r: reason (string, only if invalid)

Agent-Optimized Features

Token-Efficient Mode

# Get compact responses (80% smaller)
result = await client.verify_email(
    "user@example.com",
    format="compact"
)

Multi-Agent Tracing

# Include trace headers for multi-agent debugging
result = await client.verify_email(
    "user@example.com",
    trace_id="agent_123_task_456"
)

Error Handling

from validkit.exceptions import (
    ValidKitAPIError,
    RateLimitError,
    InvalidAPIKeyError,
    BatchSizeError
)

try:
    result = await client.verify_email("invalid-email")
except ValidKitAPIError as e:
    print(f"API Error: {e.message}")
    print(f"Error Code: {e.code}")
    print(f"Status Code: {e.status_code}")

Rate Limiting

The SDK automatically handles rate limiting with smart backoff:

# SDK will automatically retry with exponential backoff
results = await client.verify_batch(
    large_email_list,
    auto_retry=True  # Default: True
)

Examples

Check the examples/ directory for more detailed examples:

  • basic_usage.py - Simple verification examples
  • batch_processing.py - Large batch processing patterns
  • webhook_handler.py - Webhook endpoint implementation
  • agent_integration.py - AI agent integration patterns
  • error_handling.py - Comprehensive error handling

Requirements

  • Python 3.8+
  • aiohttp
  • pydantic

License

MIT License - see LICENSE file for details.

Support

Metadata

Release files for validkit 1.1.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 validkit 1.1.0
File Size Uploaded Provenance Actions
validkit-1.1.0.tar.gz 12.9 kB Without provenance Details for validkit-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for validkit 1.1.0
File Interpreter ABI Platform Actions
validkit-1.1.0-py3-none-any.whl Python 3 none any Details for validkit-1.1.0-py3-none-any.whl

Total release size: 24.6 kB

Release files / validkit-1.1.0.tar.gz

Download URL validkit-1.1.0.tar.gz
Size 12.9 kB
Tags Source
SHA-256 checksum
How to use checksums
90a574e35a5318d5c8fe8fbb119fd70d677392871c2795a9ee21882a8012faae
BLAKE2b-256 checksum
How to use checksums
6bbb9f3a12d8b025a3c5bd36ea7424215e773263de490f687934d8746c74616d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.8.0 pkginfo/1.10.0 readme-renderer/44.0 requests/2.32.3 requests-toolbelt/1.0.0 urllib3/2.2.3 tqdm/4.66.5 importlib-metadata/8.7.0 keyring/24.3.1 rfc3986/2.0.0 colorama/0.4.6 CPython/3.12.7

Release files / validkit-1.1.0-py3-none-any.whl

Download URL validkit-1.1.0-py3-none-any.whl
Size 11.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
03f0d0b8ee8c29a0a2415955ddd8d3ecc578eba18830e5d3dafe9ccd59fcef37
BLAKE2b-256 checksum
How to use checksums
0b4d05488ce0ff8550ff182b577661b894c9acc7a0534f59c8755593a1b3a47b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.8.0 pkginfo/1.10.0 readme-renderer/44.0 requests/2.32.3 requests-toolbelt/1.0.0 urllib3/2.2.3 tqdm/4.66.5 importlib-metadata/8.7.0 keyring/24.3.1 rfc3986/2.0.0 colorama/0.4.6 CPython/3.12.7

Security for validkit 1.1.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