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.

Installbash
pip install tooltrace

2. Quickstart

Set TOOLTRACE_KEY in your environment, then verify a single address.

Verify a single addresspython
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.

Bulk verify a CSVpython
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.

Async with retries and idempotencypython
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

External links