How it works

Anymail is a Django library that replaces Django’s default email backend with a unified interface for transactional email providers. Its built-in Mailtrap backend connects to Mailtrap’s API, so you send emails through Django’s standard django.core.mail module while Mailtrap handles delivery, analytics, and authentication. Switch between Mailtrap’s transactional Email API and Email Sandbox with a single setting – no code changes needed.

Configure

1. Get started

Create a Mailtrap account, verify your sending domain, and copy your API token from Sending Domains → Integration → API.

2. Install Anymail with the Mailtrap extra:

<code>pip install "django-anymail[mailtrap]"

3. Add Anymail to your Django settings:

# settings.py

INSTALLED_APPS = [
    # ...
    "anymail",
]

EMAIL_BACKEND = "anymail.backends.mailtrap.EmailBackend"

ANYMAIL = {
    "MAILTRAP_API_TOKEN": "<your API token>",
}

DEFAULT_FROM_EMAIL = "you@yourdomain.com"

4. To use Email Sandbox for testing, add your sandbox inbox ID:

ANYMAIL = {
    "MAILTRAP_API_TOKEN": "<your API token>",
    "MAILTRAP_SANDBOX_ID": 12345,  # from your sandbox inbox URL
}

Anymail looks for MAILTRAP_API_TOKEN in three places (in order):

• ANYMAIL["MAILTRAP_API_TOKEN"] – in Django settings dict
• ANYMAIL_MAILTRAP_API_TOKEN – as an environment variable
• MAILTRAP_API_TOKEN – as a root-level Django setting

Other settings:

• MAILTRAP_SANDBOX_ID – your sandbox inbox ID (from the inbox URL, e.g., mailtrap.io/inboxes/12345/messages). Routes emails to Email Sandbox instead of production.
• MAILTRAP_API_URL – optional. Auto-selected based on sandbox mode: send.api.mailtrap.io for transactional, sandbox.api.mailtrap.io for sandbox, bulk.api.mailtrap.io for bulk.

For full configuration details, consult the Anymail Mailtrap documentation.

Getting started

Send a basic email using Django’s standard EmailMessage:

from django.core.mail import EmailMessage

message = EmailMessage(
    subject="Your order has shipped",
    body="Your package is on the way.",
    from_email="orders@yourdomain.com",
    to=["customer@example.com"],
)
message.send()

Send a batch email with per-recipient merge data using a Mailtrap template:

from django.core.mail import EmailMessage

message = EmailMessage(
    from_email="orders@yourdomain.com",
    to=["alice@example.com", "Bob <bob@example.com>"],
)
message.template_id = "11111111-abcd-1234-0000-0123456789ab"
message.merge_data = {
    "alice@example.com": {"name": "Alice", "order_no": "12345"},
    "bob@example.com": {"name": "Bob", "order_no": "54321"},
}
message.merge_global_data = {
    "ship_date": "May 15",
}
message.send()

When merge_data is set, Anymail sends separate messages per recipient. Without it, all recipients see the full To list.

Use cases

• Send transactional emails (order confirmations, password resets, account notifications) from a Django app with high deliverability
• Switch your existing Django email code to Mailtrap by changing one setting – no rewrite of email-sending logic
• Route all emails to Email Sandbox during development and staging by setting MAILTRAP_SANDBOX_ID, then remove it for production

Supported functionality

• Send transactional emails via Mailtrap Email API
• Send batch emails with per-recipient merge data and Mailtrap templates
• Route emails to Email Sandbox for testing (toggle with a single setting)
• Use Mailtrap-hosted email templates with template_id
• Bulk email sending via bulk.api.mailtrap.io
• Message category tagging