Metadata-Version: 2.4
Name: clario-django
Version: 0.1.0
Summary: Django email backend and webhook consumer for the Clario email API.
Project-URL: Homepage, https://github.com/Agirem/clario-django
Project-URL: Documentation, https://docs.clario-mail.com
Project-URL: Issues, https://github.com/Agirem/clario-django/issues
Project-URL: Source, https://github.com/Agirem/clario-django
Author-email: Clario <hello@clario-mail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: clario,django,email,mail,webhooks
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.10
Requires-Dist: django>=4.2
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-django>=4.8; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install clario-django
```

## Configuration

```python
# 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

```python
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)

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

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

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

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

```python
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

```bash
pip install -e ".[dev]"
pytest
```

## Publishing

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

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

## License

MIT
