Usage

Once configured, use Django's standard mail helpers as usual, no API-specific imports needed.

Simple email

from django.core.mail import send_mail

send_mail(
    subject="Hello from Django",
    message="Plain text body.",
    from_email="noreply@example.com",
    recipient_list=["user@example.com"],
)

HTML email

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>Welcome aboard!</h1>", "text/html")
msg.send()

CC, BCC, Reply-To

from django.core.mail import EmailMessage

msg = EmailMessage(
    subject="Project update",
    body="Here is the latest update.",
    from_email="team@example.com",
    to=["client@example.com"],
    cc=["manager@example.com"],
    bcc=["archive@example.com"],
    reply_to=["support@example.com"],
)
msg.send()

Attachments

from django.core.mail import EmailMessage

msg = EmailMessage(
    subject="Invoice",
    body="Please find the attached invoice.",
    from_email="billing@example.com",
    to=["client@example.com"],
)
msg.attach("invoice.pdf", pdf_bytes, "application/pdf")
msg.send()

Per-message route override

Override the Lettermint route for a specific message using extra_headers:

from django.core.mail import EmailMessage

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

The X-Lettermint-Route header takes the slug of a route in your Lettermint project, and takes precedence over the global LETTERMINT_ROUTE setting.

Per-message tag

Set X-Lettermint-Tag to categorise a message in Lettermint, for example by campaign. With tracking installed the tag is stored on LmEmailMessage.tag, so LmEmailMessage.objects.tagged("launch-2026") returns everything sent for that campaign.

msg.extra_headers["X-Lettermint-Tag"] = "launch-2026"

Neither header is passed on as an email header.

Many recipients

To send the same mail to many people, or a personalised mail to each of them, use bulk sending. It goes through Lettermint's batch endpoint, in batches of 500 messages by default.

Sending multiple messages

Django's connection can be reused across multiple sends:

from django.core.mail import get_connection, EmailMessage

connection = get_connection()
messages = [
    EmailMessage("Subject 1", "Body 1", "from@example.com", ["a@example.com"]),
    EmailMessage("Subject 2", "Body 2", "from@example.com", ["b@example.com"]),
]
connection.send_messages(messages)