apiddress 0.1.0

Official Python SDK for the APIddress email validation API

apiddress

Official Python SDK for the APIddress email validation API.

• Zero runtime dependencies (stdlib urllib only)
• Python 3.9+, fully type-hinted, frozen dataclass responses
• Automatic retry with backoff on 429 and 5xx (batch creation is never retried)

Install

pip install apiddress

Quickstart

from apiddress import Client

client = Client("YOUR_API_KEY")

result = client.validate_email("[e-mail]")
print(result.status)  # "valid"
print(result.score)   # 0.98

Configuration

client = Client(
    "YOUR_API_KEY",
    base_url="https://api.apiddress.com",  # default
    timeout=10.0,                          # per-request timeout (seconds), default 10
    max_retries=2,                         # retries on 429/5xx, default 2
)

Usage

Validate one email

result = client.validate_email(
    "[e-mail]",
    check_smtp=False,        # default
    allow_role_based=True,   # server default
)
# result.status: "valid" | "invalid" | "risky" | "disposable" | "unknown"
# result.suggestion: "[e-mail]" for typo-like addresses, else None
# result.checks: ValidationChecks(syntax, domain_exists, mx, smtp, disposable, ...)

A malformed value (e.g. "not-an-email") is a verdict, not an error: you get status == "invalid" with reason == "invalid_syntax".

Validate up to 100 emails synchronously

response = client.validate_emails(["[e-mail]", "[e-mail]"])
print(response.count, [r.status for r in response.results])

Batch jobs (up to 5000 emails)

batch = client.create_batch(
    emails,
    callback_url="https://yourapp.com/webhooks/apiddress",  # optional
)

done = client.wait_for_batch(
    batch.batch_id,
    poll_interval=1.0,  # default
    timeout=60.0,       # default
)
print(done.status, len(done.results))

# Or poll yourself:
status = client.get_batch(batch.batch_id)

wait_for_batch returns the terminal state ("completed" or "failed") — check status before using results.

Account

profile = client.me()         # plan, limits, usage
usage = client.usage()        # current month
may = client.usage("2026-05") # specific month
health = client.health()      # no auth required

Error handling

Every failed request raises an APIddressError:

from apiddress import APIddressError, Client

try:
    client.validate_email("[e-mail]")
except APIddressError as err:
    print(err.status, err.code, err.message, err.details)
    # 429 quota_exceeded "Monthly request limit exceeded." {"requests_used": ..., "requests_limit": ...}

status	code
400	invalid_request
401	unauthorized
404	not_found
429	quota_exceeded
500	internal_error
0	timeout (request or wait_for_batch timeout)

Development

python3 -m venv .venv
.venv/bin/pip install -e . pytest

# Integration tests need a live backend:
APIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev \
  .venv/bin/pytest

License

MIT