lettermint-django

An unofficial Django email backend for Lettermint. 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. An optional tracking application records sent messages and delivery events through Lettermint webhooks.

Built and maintained by zzinnovate. Not affiliated with Lettermint.

Documentation

📖 View Full Documentation →

• Getting Started: Installation • Configuration • Usage • Tracking • Bulk sending
• Reference: Settings • Backend
• Project: Contributing • Changelog • Security

Requirements

• Python 3.11+ (Django 6 requires Python 3.12+)
• Django 4.2, 5.x, or 6.x
• lettermint 2.0+

Install

pip install lettermint-django

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

Quick start

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.

Email tracking (optional)

Add the app, set the webhook secret and include the webhook URL to record every sent message and its delivery events (delivered, bounced, failed):

INSTALLED_APPS += ["lettermint_django"]
LETTERMINT_WEBHOOK_SECRET = os.getenv("LETTERMINT_WEBHOOK_SECRET")

# urls.py
path("", include("lettermint_django.urls")),

python manage.py migrate lettermint_django

Point a webhook in the Lettermint dashboard at /lettermint/message-events/ (change it with LETTERMINT_WEBHOOK_PATH). Query LmEmailMessage and LmEmailEvent, or connect to the lm_email_bounced signal. See the tracking guide.

Bulk sending

Send the same mail to many people, or a personalised mail to each of them, in batches through Lettermint's batch endpoint:

from lettermint_django.bulk import send_bulk_mail

result = send_bulk_mail(
    [{"email": g.email, "name": g.name, "link": g.invite_url} for g in guests],
    subject="{{ name }}, you are invited",
    text_template="emails/invite.txt",
    html_template="emails/invite.html",
    tag="invites",
)
result.sent_count, result.failed   # per-message outcome, with message ids

See the bulk sending guide.

Roadmap

This project is actively developed with a clear path toward v1.0.0. Our roadmap includes email tracking, bounce monitoring, and engagement analytics.

• Current: v0.4.x (email backend, delivery tracking via webhooks, bulk sending)
• Next: v0.5.0 (opens, clicks, analytics)
• Planned: v1.0.0 (production-ready)

View the full roadmap →

Settings Reference

Per-message Route

Override the route for a specific message via extra_headers:

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"] = "app-priority"
msg.send()

HTML Emails

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 for development setup, testing, and workflow guidelines.

Security

See SECURITY.md for reporting vulnerabilities and best practices.

Credits

This package is built on top of the official lettermint Python SDK, which handles all API communication.

• Sjoerd Zaalberg van Zelst (zzinnovate)
• All contributors

License

MIT. See LICENSE.