inboxili (Python)

Python client for the Inboxili transactional email API. No dependencies, Python 3.9+, type hints included.

pip install inboxili

Send an email

import os
from inboxili import Inboxili

client = Inboxili(os.environ["INBOXILI_API_KEY"])

result = client.emails.send(
    to="ada@example.com",
    from_email="hello@yourdomain.com",  # must be a sender on a verified domain
    from_name="Acme",
    subject="Welcome, {{first_name}}",
    html_body="<p>Hi {{first_name}}, your account is ready.</p>",
    text_body="Hi Ada, your account is ready.",
    template_data={"first_name": "Ada"},
)
print(result.status, result.message_id)

status == "sent" means the delivery provider accepted the message, not that it reached the inbox. Use webhooks for delivery events.

From a template

client.emails.send(
    to="ada@example.com",
    from_email="hello@yourdomain.com",
    template_id="00000000-0000-0000-0000-000000000000",
    template_data={"first_name": "Ada"},
)

Authentication

Create an API key in the dashboard under Settings, Developer, with the transactional:send scope. Load it from the environment or a secret manager. Never commit it.

Options

Inboxili(api_key, base_url="https://api.inboxili.com/api/v1", timeout=10.0, max_retries=2)

Error handling

from inboxili import InboxiliError, InboxiliConnectionError

try:
    client.emails.send(...)
except InboxiliError as e:
    print(e.status, e.code, e.message)   # e.g. 422 sender_not_verified
except InboxiliConnectionError:
    ...  # no response; the email may or may not have been sent

Retries. Only HTTP 429 is retried (max_retries, default 2), because the request was rejected before sending. Timeouts and 5xx are never retried: the API has no idempotency key, so a retry could send a duplicate.

Webhooks

from inboxili import verify_webhook_signature

ok = verify_webhook_signature(raw_body_bytes, request.headers["X-Inboxili-Signature"], os.environ["INBOXILI_WEBHOOK_SECRET"])

Pass the raw body bytes, not a re-serialised object.

Limits of the API

One recipient per request. No attachments, CC, BCC or reply-to fields. No scheduling. See the API reference.

Development

PYTHONPATH=src python -m unittest discover -s tests

Links

Documentation · Python guide · Report a vulnerability · MIT licensed