VerifyAnyEmail — Python SDK

Official Python SDK for the VerifyAnyEmail API — real-time and bulk email verification.

• Zero third-party runtime dependencies — stdlib only (urllib, json, hmac, hashlib).
• Python 3.8+.
• Typed results (VerificationResult, Checks) with the raw JSON always available on .raw.
• Built-in webhook signature verification (constant-time).

Server-side use only. Your API key can spend credits and read your account data — keep it secret. Never embed it in browser/mobile/client code. Load it from an environment variable or secrets manager.

Install

pip install verifyanyemail

Quickstart

Verify a single address

from verifyanyemail import VerifyAnyEmail

client = VerifyAnyEmail(api_key="vae_...")

result = client.verify("name@example.com")

print(result.status)        # deliverable | undeliverable | risky | unknown
print(result.score)         # 0..100
print(result.safe_to_send)  # bool
print(result.suggestion)    # "did you mean" correction, or None
print(result.checks.mailbox_exists)

# The full JSON payload is always available:
print(result.raw)

Options (both default to the server default of True):

# DNS-only (skip the live SMTP probe), and skip catch-all detection:
result = client.verify(
    "name@example.com",
    smtp_probe=False,
    catch_all_detection=False,
)

Test mode (free)

Any address at @test.verifyany.email returns a deterministic result without charging a credit or probing a real mailbox:

client.verify("deliverable@test.verifyany.email")   # -> deliverable
client.verify("undeliverable@test.verifyany.email") # -> undeliverable
client.verify("risky@test.verifyany.email")         # -> risky
client.verify("unknown@test.verifyany.email")       # -> unknown

Batch: submit and poll

import time
from verifyanyemail import VerifyAnyEmail

client = VerifyAnyEmail(api_key="vae_...")

submitted = client.verify_batch(
    emails=["a@example.com", "b@example.com"],
    name="newsletter-2026-07",
    webhook_url="https://your-app.example.com/webhooks/vae",  # optional
)
batch_id = submitted["batch"]["id"]

# Poll until finished
while True:
    status = client.get_batch(batch_id)["batch"]
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(5)

# Page through results
page = 1
while True:
    resp = client.get_batch_results(batch_id, page=page, page_size=100)
    for row in resp["results"]:
        print(row["email"], row["status"], row["score"])
    if page * resp["pageSize"] >= resp["total"]:
        break
    page += 1

Verify a webhook

When a batch completes, VerifyAnyEmail POSTs a signed batch.completed event to your webhookUrl with the header:

X-VAE-Signature: sha256=<HMAC-SHA256(rawBody, yourWebhookSecret)>

Verify it against the raw request body (do not re-serialize the JSON):

from verifyanyemail import verify_webhook_signature

# e.g. inside a Flask view
raw_body = request.get_data()                 # bytes
signature = request.headers.get("X-VAE-Signature", "")
secret = "whsec_..."                          # dashboard Settings

if not verify_webhook_signature(raw_body, signature, secret):
    abort(400)  # reject
# ...process the event, return 2xx to acknowledge

It is also available as VerifyAnyEmail.verify_webhook_signature(...).

Method reference

VerifyAnyEmail(api_key, base_url="https://api.verifyany.email", timeout=30.0)

VerificationResult fields

email, normalized, account, domain, status, sub_status, score, checks (a Checks), suggestion, safe_to_send, duration_ms, checked_at, and raw (the full JSON dict).

Checks fields

syntax, has_mx_records, null_mx, smtp_connectable, mailbox_exists, catch_all, role_based, disposable, free_provider, possible_typo, gibberish, and raw. Fields the API marks nullable may be None (e.g. when the SMTP probe was skipped).

Error handling

Any non-2xx response raises VerifyAnyEmailError:

from verifyanyemail import VerifyAnyEmail, VerifyAnyEmailError

client = VerifyAnyEmail(api_key="vae_...")

try:
    result = client.verify("name@example.com")
except VerifyAnyEmailError as exc:
    print(exc.status)   # HTTP status code
    print(exc.code)     # machine-readable code (JSON "error")
    print(exc.message)  # human-readable message
    print(exc.body)     # raw parsed JSON body (or None)

Common statuses:

Network/timeout failures raise VerifyAnyEmailError with status == 0 and code == "network_error".

License

MIT © 2026 VerifyAnyEmail