Mailgun

Anymail integrates with the Mailgun transactional email service from Rackspace, using their REST API.

Settings

EMAIL_BACKEND

To use Anymail’s Mailgun backend, set:

EMAIL_BACKEND = "anymail.backends.mailgun.MailgunBackend"

in your settings.py. (Watch your capitalization: Mailgun spells their name with a lowercase “g”, so Anymail does too.)

MAILGUN_API_KEY

Required. Your Mailgun API key:

ANYMAIL = {
    ...
    "MAILGUN_API_KEY": "<your API key>",
}

Anymail will also look for MAILGUN_API_KEY at the root of the settings file if neither ANYMAIL["MAILGUN_API_KEY"] nor ANYMAIL_MAILGUN_API_KEY is set.

MAILGUN_API_URL

The base url for calling the Mailgun API. It does not include the sender domain. (Anymail figures this out for you.)

The default is MAILGUN_API_URL = "https://api.mailgun.net/v3" (It’s unlikely you would need to change this.)

Email sender domain

Mailgun’s API requires a sender domain in the API url. By default, Anymail will use the domain of each email’s from address as the domain for the Mailgun API.

If you need to override this default, you can use Anymail’s esp_extra dict, either on an individual message:

message = EmailMessage(from_email="sales@europe.example.com", ...)
message.esp_extra = {"sender_domain": "example.com"}

... or as a global send default setting that applies to all messages:

ANYMAIL = {
    ...
    "MAILGUN_SEND_DEFAULTS": {
        "esp_extra": {"sender_domain": "example.com"}
    }
}

exp_extra support

Anymail’s Mailgun backend will pass all esp_extra values directly to Mailgun. You can use any of the (non-file) parameters listed in the Mailgun sending docs. Example:

message = AnymailMessage(...)
message.esp_extra = {
    'o:testmode': 'yes',  # use Mailgun's test mode
}

Batch sending/merge and ESP templates

Mailgun does not offer ESP stored templates, so Anymail’s template_id message attribute is not supported with the Mailgun backend.

Mailgun does support batch sending with per-recipient merge data. You can refer to Mailgun “recipient variables” in your message subject and body, and supply the values with Anymail’s normalized merge_data and merge_global_data message attributes:

message = EmailMessage(
    ...
    subject="Your order %recipient.order_no% has shipped",
    body="""Hi %recipient.name%,
            We shipped your order %recipient.order_no%
            on %recipient.ship_date%.""",
    to=["alice@example.com", "Bob <bob@example.com>"]
)
# (you'd probably also set a similar html body with %recipient.___% variables)
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"  # Anymail maps globals to all recipients
}

Mailgun does not natively support global merge data. Anymail emulates the capability by copying any merge_global_data values to each recipient’s section in Mailgun’s “recipient-variables” API parameter.

See the Mailgun batch sending docs for more information.

Status tracking webhooks

If you are using Anymail’s normalized status tracking, enter the url in your Mailgun dashboard on the “Webhooks” tab. Mailgun allows you to enter a different URL for each event type: just enter this same Anymail tracking URL for all events you want to receive:

https://random:random@yoursite.example.com/anymail/mailgun/tracking/

If you use multiple Mailgun sending domains, you’ll need to enter the webhook URLs for each of them, using the selector on the left side of Mailgun’s dashboard.

Mailgun implements a limited form of webhook signing, and Anymail will verify these signatures (based on your MAILGUN_API_KEY Anymail setting).

Mailgun will report these Anymail event_types: delivered, rejected, bounced, complained, unsubscribed, opened, clicked.

The event’s esp_event field will be a Django QueryDict object of Mailgun event fields.