Skip to content

Latest commit

 

History

History
250 lines (167 loc) · 8.62 KB

mailgun.rst

File metadata and controls

250 lines (167 loc) · 8.62 KB
Raw

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.

ANYMAIL_MAILGUN_API_KEY

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.

ANYMAIL_MAILGUN_SENDER_DOMAIN

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 mailgun-sender-domain below for examples.

ANYMAIL_MAILGUN_API_URL

MAILGUN_API_URL

The base url for calling the Mailgun API. It does not include the sender domain. (Anymail figures this out <mailgun-sender-domain> 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 <ANYMAIL_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 ~anymail.message.AnymailMessage.esp_extra for that message:

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

exp_extra support

Anymail's Mailgun backend will pass all ~anymail.message.AnymailMessage.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 ~anymail.message.AnymailMessage.metadata keys if you need to access that metadata from an opened, clicked, or unsubscribed tracking event <event-tracking> handler.

Batch sending/merge and ESP templates

Mailgun does not offer ESP stored templates <esp-stored-templates>, so Anymail's ~anymail.message.AnymailMessage.template_id message attribute is not supported with the Mailgun backend.

Mailgun does support batch sending <batch-send> 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 ~anymail.message.AnymailMessage.merge_data and ~anymail.message.AnymailMessage.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 <event-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_SECRET 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_MAILGUN_API_KEY> Anymail setting).

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

The event's ~anymail.signals.AnymailTrackingEvent.esp_event field will be a Django ~django.http.QueryDict object of Mailgun event fields.

Inbound webhook

If you want to receive email from Mailgun through Anymail's normalized inbound <inbound> handling, follow Mailgun's Receiving, Storing and Fowarding Messages guide to set up an inbound route that forwards to Anymail's inbound webhook. (You can configure routes using Mailgun's API, or simply using the "Routes" tab in your Mailgun dashboard.)

The action for your route will be either:

forward("https://{random}:{random}@{yoursite.example.com}/anymail/mailgun/inbound/") forward("https://{random}:{random}@{yoursite.example.com}/anymail/mailgun/inbound_mime/")

  • random:random is an ANYMAIL_WEBHOOK_SECRET shared secret
  • yoursite.example.com is your Django site

Anymail accepts either of Mailgun's "fully-parsed" (.../inbound/) and "raw MIME" (.../inbound_mime/) formats; the URL tells Mailgun which you want. Because Anymail handles parsing and normalizing the data, both are equally easy to use. The raw MIME option will give the most accurate representation of any received email (including complex forms like multi-message mailing list digests). The fully-parsed option may use less memory while processing messages with many large attachments.

If you want to use Anymail's normalized ~anymail.inbound.AnymailInboundMessage.spam_detected and ~anymail.inbound.AnymailInboundMessage.spam_score attributes, you'll need to set your Mailgun domain's inbound spam filter to "Deliver spam, but add X-Mailgun-SFlag and X-Mailgun-SScore headers" (in the Mailgun dashboard on the "Domains" tab).