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 examplesbatch_processing.py- Large batch processing patternswebhook_handler.py- Webhook endpoint implementationagent_integration.py- AI agent integration patternserror_handling.py- Comprehensive error handling
Requirements
- Python 3.8+
- aiohttp
- pydantic
License
MIT License - see LICENSE file for details.
Support
- Documentation: https://docs.validkit.com
- API Reference: https://docs.validkit.com/api
- Issues: https://github.com/validkit/python-sdk/issues
- Email: support@validkit.com
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.