Django-Mailgun
A Django email backend for use with Mailgun
Overview
Django-Mailgun is a drop-in mail backend for Django.
Getting going
Install django-mailgun:
pip install django-mailgun
Add the following to your settings.py:
EMAIL_BACKEND = 'django_mailgun.MailgunBackend' MAILGUN_ACCESS_KEY = 'ACCESS-KEY' MAILGUN_SERVER_NAME = 'SERVER-NAME'
Replace ACCESS-KEY with the "API-KEY" value from your Mailgun account details and
SERVER-NAME with the last part of your "API Base URL"
(eg. https://api.mailgun.net/v3/<your_server_name>), also found in your Mailgun
account details.
Now, when you use django.core.mail.send_mail, Mailgun will send the messages.
Extra features
Passing user-specific data
Mailgun also includes the ability to send emails to a group of recipients via a single
API call (https://documentation.mailgun.com/user_manual.html#batch-sending). To make use of this,
you need to pass Recipient Variables along with your API call. To do so with Django-Mailgun,
add a valid JSON string to the extra_headers attribute of EmailMessage and Django-Mailgun will
remove the string from the headers and send it appropriately. For example:
email = EmailMessage('Hi!', 'Cool message for %recipient.first_name%', 'admin@example.com', [joe@example.com, jane@example.com])
email.extra_headers['recipient_variables'] = '{"joe@example.com":{"first_name":"Joe"}, "jane@example.com":{"first_name":"Jane"}}'
email.send()
When Jane receives her email, its body should read 'Cool message for Jane', and Joe will see 'Cool message for Joe'.
Analytics and other tracking features
Mailgun provides the ability to track certain events that concern your emails. The
API exposes these options (see https://documentation.mailgun.com/api-sending.html#sending). These
options can also be passed to Mailgun's SMTP server (see "Passing Sending Options" under
https://documentation.mailgun.com/user_manual.html#sending-via-smtp). If you add
any of the SMTP options to the extra_headers attribute of EmailMessage, Django-Mailgun
will map those values over to the appropriate API parameter. For example:
email = EmailMessage('Hi!', 'Cool message for Joe', 'admin@example.com', [joe@example.com])
email.extra_headers['X-Mailgun-Tag'] = ['Tag 1', 'Tag 2']
email.send()
When the email is sent, it will be tagged with 'Tag 1' and 'Tag 2'. You can provide a string for any value, or a list or tuple that contains strings for options that can take multiple values.
NOTE: Django-Mailgun does NOT validate your data for compliance with Mailgun's API; it merely maps over whatever values you provide. For example, Mailgun's API states that no more than 3 tags are allowed per email, and each tag must be no greater than 128 characters (https://documentation.mailgun.com/user_manual.html#tagging). If you provide 4 tags, or a tag longer than 128 characters, Django-Mailgun will attempt to send such (potentially) invalid data. You must ensure what you send is appropriate.