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.EmailBackend"
in your settings.py.
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_SENDER_DOMAIN
If you are using a specific Mailgun sender domain
that is different from your messages’ from_email
domains,
set this to the domain you’ve configured in your Mailgun account.
If your messages’ from_email
domains always match a configured
Mailgun sender domain, this setting is not needed.
See Email sender domain below for examples.
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 identifying the sender domain.
By default, Anymail uses the domain of each messages’s from_email
(e.g., “example.com” for “from@example.com”).
You will need to override this default if you are using
a dedicated Mailgun sender domain that is different from
a message’s from_email
domain.
For example, if you are sending from “orders@example.com”, but your
Mailgun account is configured for “mail1.example.com”, you should provide
MAILGUN_SENDER_DOMAIN
in your settings.py:
ANYMAIL = { ... "MAILGUN_API_KEY": "<your API key>", "MAILGUN_SENDER_DOMAIN": "mail1.example.com" }
If you need to override the sender domain for an individual message,
include sender_domain
in Anymail’s esp_extra
for that message:
message = EmailMessage(from_email="[email protected]", ...) message.esp_extra = {"sender_domain": "mail2.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 }
Limitations and quirks¶
- Metadata keys and tracking webhooks
- Because of the way Mailgun supplies custom data (user-variables) to webhooks,
there are a few metadata keys that Anymail cannot reliably retrieve in some
tracking events. You should avoid using “body-plain”, “h”, “message-headers”,
“message-id” or “tag” as
metadata
keys if you need to access that metadata from an opened, clicked, or unsubscribed tracking event handler.
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=["[email protected]", "Bob <[email protected]>"] ) # (you'd probably also set a similar html body with %recipient.___% variables) message.merge_data = { '[email protected]': {'name': "Alice", 'order_no': "12345"}, '[email protected]': {'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/
- random:random is an
ANYMAIL_WEBHOOK_AUTHORIZATION
shared secret- yoursite.example.com is your Django site
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_type
s:
delivered, rejected, bounced, complained, unsubscribed, opened, clicked.
The event’s esp_event
field will be
a Django QueryDict
object of Mailgun event fields.