Metadata-Version: 2.4
Name: lettermint-django
Version: 0.2.1a0
Summary: Django email backend for Lettermint
Author-email: Sjoerd Zaalberg van Zelst <hello@zzinnovate.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/zzinnovate/lettermint-django
Project-URL: Repository, https://github.com/zzinnovate/lettermint-django
Keywords: lettermint,django,email,backend
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Email
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lettermint>=2.0.0
Requires-Dist: django>=4.2
Provides-Extra: dev
Requires-Dist: pytest<8.5.0,>=8.3.0; extra == "dev"
Requires-Dist: pytest-cov<7.0,>=5; extra == "dev"
Requires-Dist: pytest-mock<4.0,>=3.14.1; extra == "dev"
Requires-Dist: pytest-django<5.0,>=4.8.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: watchdog>=4.0.0; extra == "docs"
Requires-Dist: mkdocs>=1.6.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin>=6.0.0; extra == "docs"
Requires-Dist: mkdocstrings>=0.24.0; extra == "docs"
Requires-Dist: mkdocstrings-python>=1.10.0; extra == "docs"
Provides-Extra: all
Requires-Dist: lettermint-django[dev,docs]; extra == "all"
Dynamic: license-file

# lettermint-django

[![PyPI version](https://img.shields.io/pypi/v/lettermint-django.svg)](https://pypi.org/project/lettermint-django/)
[![Tests](https://github.com/zzinnovate/lettermint-django/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/zzinnovate/lettermint-django/actions/workflows/run-tests.yml)
[![codecov](https://codecov.io/gh/zzinnovate/lettermint-django/graph/badge.svg)](https://codecov.io/gh/zzinnovate/lettermint-django)
![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)
![Django Version](https://img.shields.io/badge/django-4.2%20%7C%205.x%20%7C%206.x-092E20)

An unofficial Django email backend for [Lettermint](https://lettermint.co/). Drop it in as your `EMAIL_BACKEND` and all Django mail (`send_mail()`, `EmailMessage`, `EmailMultiAlternatives`) routes through the Lettermint API. Supports per-message routing, HTML emails, attachments, and reply-to headers with no changes to your existing email code.

Built and maintained by [zzinnovate](https://github.com/zzinnovate). Not affiliated with Lettermint.

## Documentation

📖 **[View Full Documentation →](https://zzinnovate.github.io/lettermint-django/)**

- **Getting Started**: [Installation](https://zzinnovate.github.io/lettermint-django/getting-started/installation/) • [Configuration](https://zzinnovate.github.io/lettermint-django/getting-started/configuration/) • [Usage](https://zzinnovate.github.io/lettermint-django/getting-started/usage/)
- **Reference**: [Settings](https://zzinnovate.github.io/lettermint-django/reference/settings/) • [Backend](https://zzinnovate.github.io/lettermint-django/reference/backend/)
- **Project**: [Contributing](https://zzinnovate.github.io/lettermint-django/project/contributing/) • [Changelog](https://zzinnovate.github.io/lettermint-django/project/changelog/) • [Security](https://zzinnovate.github.io/lettermint-django/project/security/)

## Requirements

- Python 3.11+ (Django 6 requires Python 3.12+)
- Django 4.2, 5.x, or 6.x
- [lettermint](https://github.com/lettermint/lettermint-python) 2.0+

## Install

```bash
pip install lettermint-django

# For development (includes testing tools)
pip install -e ".[dev]"
```

## Quick start

```python
import os

EMAIL_BACKEND = "lettermint_django.LettermintEmailBackend"
LETTERMINT_API_KEY = os.getenv("LETTERMINT_API_KEY")
```

That's it. All `send_mail()`, `EmailMessage`, and `EmailMultiAlternatives` calls in Django will now route through Lettermint.

## Settings Reference

| Setting | Required | Default | Description |
|---|---|---|---|
| `LETTERMINT_API_KEY` | Yes | - | Your project API token from the Lettermint dashboard |
| `LETTERMINT_BASE_URL` | No | SDK default | Override the Lettermint API base URL |
| `LETTERMINT_ROUTE` | No | - | Default route applied to all outgoing emails |
| `LETTERMINT_TIMEOUT` | No | SDK default | Request timeout in seconds |

## Per-message Route

Override the route for a specific message via `extra_headers`:

```python
from django.core.mail import EmailMessage

msg = EmailMessage(
    subject="Password reset",
    body="Click the link...",
    from_email="noreply@example.com",
    to=["user@example.com"],
)
msg.extra_headers["X-Lettermint-Route"] = "transactional"
msg.send()
```

## HTML Emails

```python
from django.core.mail import EmailMultiAlternatives

msg = EmailMultiAlternatives(
    subject="Welcome",
    body="Plain text fallback.",
    from_email="noreply@example.com",
    to=["user@example.com"],
)
msg.attach_alternative("<h1>Hello!</h1>", "text/html")
msg.send()
```

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and workflow guidelines.

## Security

See [SECURITY.md](SECURITY.md) for reporting vulnerabilities and best practices.

## Credits

This package is built on top of the official [lettermint Python SDK](https://github.com/lettermint/lettermint-python), which handles all API communication. 

- [Sjoerd Zaalberg van Zelst](https://github.com/sjoerdzzid) (zzinnovate)
- [All contributors](https://github.com/zzinnovate/lettermint-django/graphs/contributors)

## License

MIT. See [LICENSE](LICENSE).
