django-lettermint

A Django email backend that sends mail through Lettermint using the official lettermint Python SDK.

Supported versions

• Django 6.1
• Python 3.12

Other versions may work, but are not tested.

Configuration and Installation

pip install django-lettermint

Add "django_lettermint" to INSTALLED_APPS. Then configure it as a mailer in MAILERS.

MAILERS = {
    "default": {
        "BACKEND": "django_lettermint.backend.LettermintEmailBackend",
        "OPTIONS": {
            "sending_token": os.environ["LETTERMINT_SENDING_TOKEN"],
            "route": os.environ.get("LETTERMINT_ROUTE", ""),
        },
    },
}

Lettermint-specific options per message

You can set these optional attributes on any EmailMessage:

message = EmailMultiAlternatives(subject, text, to=[user.email])
message.attach_alternative(html, "text/html")
message.lettermint_tags = {"campaign": "welcome"}  # name -> value
message.lettermint_metadata = {"user_id": str(user.pk)}
message.lettermint_route = "broadcast"  # overrides the route option
message.lettermint_idempotency_key = f"welcome-{user.pk}"
message.send()

message.lettermint_message_id  # "…", set after a successful send
message.lettermint_status  # "pending"

How a Django message is mapped

Handling failures

The backend doesn't support fail_silently, following Django's Replacing fail_silently advice. Every failure raises, so the caller decides what to ignore:

from lettermint import LettermintError

try:
    message.send()
except LettermintError:
    logger.warning("Lettermint could not send %r", message.subject)

When one call sends several messages and one fails, the messages before it were already sent and have lettermint_message_id set.

Checking it works

• manage.py check --deploy warns (lettermint.W001) when a Lettermint mailer has no sending_token.
• manage.py check errors (lettermint.E001) on unknown OPTIONS, and on a sending_token or timeout the SDK rejects, such as a token with a trailing newline.
• Send a real test email with manage.py sendtestemail you@example.com.

Limitations

• A message needs at least one to recipient; Bcc-only messages raise ValueError.
• One API request per message, sent synchronously. There is no batch sending (/send/batch) or background queue.
• Only one HTML body and no other alternatives; a text/plain alternative next to an HTML body is rejected too.
• No per-message scheduling, tracking settings or sandbox results.
• No webhooks yet, so delivery events are visible only in the Lettermint dashboard.

Development

make check  # ruff, and the tests
make build  # sdist and wheel in dist/