Django email backend and webhook consumer for the Clario email API.

Requirements

• Python 3.10+
• Django 4.2+
• Clario API key with emails:send
• Free, Solo, or Pro plan (API included on Free within quotas)

Installation

pip install clario-django

Configuration

# settings.py
EMAIL_BACKEND = "clario.django.email_backend.EmailBackend"
CLARIO_API_KEY = "clario_live_..."
# Optional when Django From matches a Clario address:
# CLARIO_MAIL_ADDRESS_ID = "01HX..."
# CLARIO_MAIL_ADDRESSES = {"noreply@acme.com": "01HX..."}
CLARIO_BASE_URL = "https://clario-mail.com/api/v1"

Send

from django.core.mail import EmailMultiAlternatives

msg = EmailMultiAlternatives(
    subject="Welcome",
    body="Plain text",
    from_email="noreply@acme.com",
    to=["user@example.com"],
)
msg.attach_alternative("<p>Welcome</p>", "text/html")
msg.extra_headers["X-Clario-Idempotency-Key"] = "welcome-user-42-v1"
msg.send()

Sender resolution

1. X-Clario-Mail-Address-Id header → mail_address_id
2. CLARIO_MAIL_ADDRESSES[from] → mail_address_id
3. CLARIO_MAIL_ADDRESS_ID → mail_address_id
4. Django from_email → from (API resolves the mailbox)

Idempotency

Prefer a stable business key via X-Clario-Idempotency-Key or Idempotency-Key. If omitted, the backend hashes the rendered message so retries of the same content do not double-send.

Webhooks (optional)

CLARIO_WEBHOOKS_ENABLED = True
CLARIO_WEBHOOK_SECRET = "whsec_..."
CLARIO_WEBHOOK_TOLERANCE = 300

# urls.py
from django.urls import include, path

urlpatterns = [
    path("clario/", include("clario.webhooks.urls")),
]

Point Clario Developers to https://your-app/clario/webhook.

from django.dispatch import receiver
from clario.webhooks.signals import email_delivered

@receiver(email_delivered)
def on_delivered(sender, event, **kwargs):
    # event.email_id, event.data, event.event_id
    ...

Signatures use Clario-Signature: t=…,v1=… (HMAC-SHA256 of timestamp.rawBody). Invalid signatures return 401.

Attachments

Max 10 files, 5 MB each. Allowed MIME types: PDF, JPEG/PNG/GIF, Word, Excel, CSV, plain text.

Exceptions

clario.exceptions.ClarioApiError exposes status_code, error_code, request_id, and retryable.

Development

pip install -e ".[dev]"
pytest

Publishing

python -m build
twine check dist/*
twine upload dist/*

Tag releases as v0.1.0 (CI can publish on tag).

License

MIT