SDK QUICKSTART
Verify emails from Python.
Async httpx client, typed with Pydantic, works on 3.9+.
1. Install
Grab a free API key at tooltrace.io/signup. The free plan includes 1,000 verifications per month.
pip install tooltrace 2. Quickstart
Set TOOLTRACE_KEY in your environment, then verify a single address.
import os
from tooltrace import ToolTrace
client = ToolTrace(api_key=os.environ["TOOLTRACE_KEY"])
result = client.verify_email(email="[email protected]")
print(result.status) # 'valid'
print(result.score) # 97
print(result.checks.mx) # True
print(result.reasons) # ['mailbox_confirmed', 'mx_present']
if result.status == "valid" and result.score >= 80:
accept_lead(result.email)
else:
flag_for_review(result) 3. Bulk verify
Submit up to 50,000 addresses in one job. Duplicates on the normalised form are deduped server-side and never charged. A signed webhook fires on completion.
job = client.bulk_verify(
emails=load_csv("leads.csv"), # up to 50,000 addresses
webhook_url="https://your.app/hooks/tooltrace",
)
print(job.job_id) # 'job_01HM8K2TGQX5RTF9W6'
print(job.unique_count) # dedupe-free billing: unique probes only
print(job.estimated_credits)
# Poll if you prefer; otherwise your webhook fires on completion.
while True:
status = client.get_job(job.job_id)
if status.state in ("completed", "failed"):
break
time.sleep(10)
for row in client.job_results(job.job_id):
writer.writerow([row.email, row.status, row.score, row.reasons]) 4. Advanced
Patterns for production use: idempotency, retries, and typed errors.
import asyncio
from tooltrace import AsyncToolTrace, RateLimitError
client = AsyncToolTrace(
api_key=os.environ["TOOLTRACE_KEY"],
max_retries=3, # retries respect Retry-After automatically
timeout=15,
)
async def verify(email: str, request_id: str):
try:
return await client.verify_email(
email=email,
idempotency_key=request_id, # safe to retry within 24h
)
except RateLimitError as e:
await asyncio.sleep(e.retry_after)
return await verify(email, request_id)
results = await asyncio.gather(*[verify(e, rid) for e, rid in batch]) What you get
- Sync + async clients
- Pydantic-typed responses so your IDE autocompletes every field
- Idempotency-Key header on single verify, bulk-job dedupe server-side
- Automatic Retry-After handling on 429
- Works on Python 3.9+ with no C extensions