djrill 0.3.0

Django EmailMessage Support

Djrill supports most of the functionality of Django’s EmailMessage and EmailMultiAlternatives classes. Some notes and limitations:

• Display Names: All email addresses (from, to, cc) can be simple (”email@example.com”) or can include a display name (“Real Name <email@example.com>”).

• From Address: The from_email must be in one of the approved sending domains in your Mandrill account.

• CC Recipients: Djrill treats all “cc” recipients as if they were additional “to” addresses. (Mandrill does not distinguish “cc” from “to”.) Note that you will also need to set preserve_recipients True if you want each recipient to see the other recipients listed in the email headers.

• BCC Recipients: Mandrill does not permit more than one “bcc” address. Djrill raises djrill.NotSupportedByMandrillError if you attempt to send a message with multiple bcc’s. (Mandrill’s bcc option seems intended primarily for logging. To send a single message to multiple recipients without exposing their email addresses to each other, simply include them all in the “to” list and leave preserve_recipients set to False.)

• Attachments: Djrill includes a message’s attachments, but only with the mimetypes “text/*”, “image/*”, or “application/pdf” (since that is all Mandrill allows). Any other attachment types will raise djrill.NotSupportedByMandrillError when you attempt to send the message.

• Headers: Djrill accepts additional headers, but only Reply-To and X-* (since that is all that Mandrill accepts). Any other extra headers will raise djrill.NotSupportedByMandrillError when you attempt to send the message.

• Alternative Parts: Djrill requires that if you attach_alternative to a message, there must be only one alternative part, and it must be text/html. Otherwise, Djrill will raise djrill.NotSupportedByMandrillError when you attempt to send the message. (Mandrill doesn’t support sending multiple html alternative parts, or any non-html alternatives.)

Mandrill Message Options

Many of the options from the Mandrill messages/send API message struct can be set directly on an EmailMessage (or subclass) object:

• track_opens - Boolean

• track_clicks - Boolean (If you want to track clicks in HTML only, not plaintext mail, you must not set this property, and instead just set the default in your Mandrill account sending options.)

• auto_text - Boolean

• url_strip_qs - Boolean

• preserve_recipients - Boolean

• global_merge_vars - a dict – e.g., { 'company': "ACME", 'offer': "10% off" }

• recipient_merge_vars - a dict whose keys are the recipient email addresses and whose values are dicts of merge vars for each recipient – e.g., { 'wiley@example.com': { 'offer': "15% off anvils" } }

• tags - a list of strings

• google_analytics_domains - a list of string domain names

• google_analytics_campaign - a string or list of strings

• metadata - a dict

• recipient_metadata - a dict whose keys are the recipient email addresses, and whose values are dicts of metadata for each recipient (similar to recipient_merge_vars)

These Mandrill-specific properties work with any EmailMessage-derived object, so you can use them with many other apps that add Django mail functionality (such as Django template-based messages).

If you have any questions about the python syntax for any of these properties, see DjrillMandrillFeatureTests in tests/test_mandrill_send.py for examples.

Mandrill Templates

To use a Mandrill (MailChimp) template, set a template_name and (optionally) template_content on your EmailMessage object:

msg = EmailMessage(subject="Shipped!", from_email="store@example.com",
    to=["customer@example.com", "accounting@example.com"])
msg.template_name = "SHIPPING_NOTICE"   # A Mandrill template name
msg.template_content = {                # Content blocks to fill in
    'TRACKING_BLOCK': "<a href='.../\*\|TRACKINGNO\|\*'>track it</a>" }
msg.global_merge_vars = {               # Merge tags in your template
    'ORDERNO': "12345", 'TRACKINGNO': "1Z987" }
msg.merge_vars = {                      # Per-recipient merge tags
    'accounting@example.com': { 'NAME': "Pat" },
    'customer@example.com':   { 'NAME': "Kim" } }
msg.send()

If template_name is set, Djrill will use Mandrill’s messages/send-template API, rather than messages/send. All of the other options listed above can be used.

(This is for MailChimp templates stored in your Mandrill account. If you want to use a Django template, you can use Django’s render_to_string template shortcut to build the body and html, and send using EmailMultiAlternatives as in the earlier examples.)

Using Multiple Email Backends

You can use Django mail’s optional connection argument to send some mail through Mandrill and others through a different system. This can be useful to send customer emails with Mandrill, but admin emails directly through an SMTP server. Example:

from django.core.mail import send_mail, get_connection

# send_mail connection defaults to the settings EMAIL_BACKEND, which
# we've set to DjrillBackend. This will be sent using Mandrill:
send_mail("Subject", "Body", "support@example.com", ["user@example.com"])

# Get a connection to an SMTP backend, and send using that instead:
smtp_backend = get_connection('django.core.mail.backends.smtp.EmailBackend')
send_mail("Subject", "Body", "admin@example.com", ["alert@example.com"],
    connection=smtp_backend)

You can supply a different connection to Django’s django.core.mail send_mail and send_mass_mail helpers, and in the constructor for an EmailMessage or EmailMultiAlternatives.