Email Validation¶

2 endpoints for thorough email validation — beyond syntax checking to live MX resolution and SMTP mailbox probing.

Python SDK Examples¶

Validate a single address¶

validate runs the full pipeline: RFC 5322 syntax check → MX resolution → SMTP mailbox probe → disposable/free/role-account flags.

from toolkitapi import Email

with Email(api_key="tk_...") as email:
    result = email.validate("[email protected]")

    print(result["deliverability"])   # "deliverable" | "undeliverable" | "risky" | "unknown"
    print(result["confidence"])       # 0.0 – 1.0 confidence in the verdict
    print(result["syntax_valid"])     # True
    print(result["mx_found"])         # True
    print(result["mx_records"])       # ["mail.toolkitapi.io"]
    print(result["is_deliverable"])   # True (SMTP verdict)
    print(result["is_disposable"])    # False
    print(result["is_free"])          # False (gmail.com etc.)
    print(result["is_role_account"])  # False (support@, noreply@, etc.)
    print(result["smtp_code"])        # 250

Gate a sign-up form¶

from toolkitapi import Email

def is_acceptable_signup_email(address: str) -> tuple[bool, str]:
    """Return (ok, reason). Reject disposable and role accounts."""
    with Email(api_key="tk_...") as email:
        result = email.validate(address)

    if not result["syntax_valid"]:
        return False, "Invalid email address format."
    if not result["mx_found"]:
        return False, "Email domain does not appear to accept mail."
    if result["is_disposable"]:
        return False, "Disposable email addresses are not accepted."
    if result["is_role_account"]:
        return False, "Please use a personal email address, not a group inbox."
    if result["deliverability"] == "undeliverable":
        return False, "This email address does not appear to exist."
    return True, ""

ok, reason = is_acceptable_signup_email("[email protected]")
print(ok, reason)  # False  Disposable email addresses are not accepted.

Batch validation¶

validate_batch validates up to 50 addresses concurrently with controlled SMTP concurrency. Returns per-address results and a summary.

from toolkitapi import Email

addresses = [
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "totally-invalid",
]

with Email(api_key="tk_...") as email:
    response = email.validate_batch(addresses)

print(f"Deliverable:   {response['summary']['deliverable']}")
print(f"Undeliverable: {response['summary']['undeliverable']}")
print(f"Risky:         {response['summary']['risky']}")
print(f"Unknown:       {response['summary']['unknown']}")

for r in response["results"]:
    status = r["deliverability"].upper()
    disp = " [disposable]" if r["is_disposable"] else ""
    role = " [role]" if r["is_role_account"] else ""
    print(f"  {r['email']:30} → {status}{disp}{role}")

Clean a mailing list¶

import csv
from toolkitapi import Email

def clean_list(input_csv: str, output_csv: str) -> dict:
    """Remove undeliverable, disposable, and role addresses from a CSV list."""
    with open(input_csv, newline="") as f:
        rows = list(csv.DictReader(f))

    emails = [row["email"] for row in rows]
    kept, removed = [], []

    with Email(api_key="tk_...") as client:
        # Process in batches of 50
        results: list[dict] = []
        for i in range(0, len(emails), 50):
            resp = client.validate_batch(emails[i:i + 50])
            results.extend(resp["results"])

    for row, result in zip(rows, results):
        if result["deliverability"] in ("deliverable",) and \
           not result["is_disposable"] and \
           not result["is_role_account"]:
            kept.append(row)
        else:
            removed.append({**row, "reason": result["deliverability"]})

    fieldnames = list(rows[0].keys())
    with open(output_csv, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(kept)

    return {"kept": len(kept), "removed": len(removed)}

stats = clean_list("leads.csv", "clean_leads.csv")
print(stats)  # {"kept": 842, "removed": 158}

Segment results by deliverability¶

from toolkitapi import Email
from collections import defaultdict

addresses = [...]  # your list

buckets: dict[str, list[str]] = defaultdict(list)

with Email(api_key="tk_...") as client:
    for i in range(0, len(addresses), 50):
        resp = client.validate_batch(addresses[i:i + 50])
        for r in resp["results"]:
            buckets[r["deliverability"]].append(r["email"])

print("Deliverable:",   len(buckets["deliverable"]))
print("Undeliverable:", len(buckets["undeliverable"]))
print("Risky:",         len(buckets["risky"]))
print("Unknown:",       len(buckets["unknown"]))

Response Fields¶

validate and each record in validate-batch:

validate-batch summary: