Python

Check addresses in your Python backend before creating accounts. Keep the API key in server configuration and reuse a client so HTTP connections stay pooled.

Availability

PyPI publication is pending. Install version 0.2.0 from the public tagged source; this requires Git:

python -m pip install "git+https://github.com/IrondomeDev/sdks.git@javascript/v0.2.0#subdirectory=python"

Python 3.11 or newer is required.

Synchronous client

Set IRONDOME_API_KEY in your server environment. Client defaults to https://api.irondome.dev.

import os
from irondome import APIError, Client

client = Client(os.environ["IRONDOME_API_KEY"])

def check_email(email: str):
    try:
        return client.check(email)
    except APIError as error:
        print(error.status_code, error.code, error.request_id)
        raise

with client:
    print(check_email("person@example.com"))

The synchronous client can be shared across threads. Create it after a process fork and close it only when the worker is shutting down. Do not create a client for each address.

Async client

Use AsyncClient within one long-lived event loop. In an ASGI application, create it during application startup and close it during shutdown.

import asyncio
import os
from irondome import AsyncClient

async def main():
    async with AsyncClient(os.environ["IRONDOME_API_KEY"]) as client:
        result = await client.check("person@example.com")
        print(result)

asyncio.run(main())

This standalone example uses one event loop and one client. In an ASGI server, retain the AsyncClient across requests and close it during shutdown. Do not share an async client across event loops or repeated asyncio.run calls.

Results and failures

check() returns provider, valid, disposable, and reason, with optional request_id and detector_version. valid does not verify mailbox existence or deliverability. APIError exposes status_code, code, request_id, and retry_after_seconds. Local validation, transport, timeout, busy, and closed-client errors are separate failures. Handle them separately from classifications.

client.warmup() sends an unauthenticated health request on the same pool. It is optional and does not verify the API key. Use it ahead of independent work if useful, not as a required step before every check.

The SDK also provides check_bulk(emails) for up to 100 addresses. Each syntactically valid address counts as one check. See the bulk API guide and performance guide.