Giter Club home page Giter Club logo

djrill's Introduction

Djrill, for Mandrill

https://secure.travis-ci.org/medmunds/Djrill.png

Djrill is an email backend for Django users who want to take advantage of the Mandrill transactional email service from MailChimp.

An optional Django admin interface is included. The admin interface allows you to:

  • Check the status of your Mandrill API connection.
  • See stats on email senders, tags and urls.

Djrill is made available under the BSD license.

Installation

Install from PyPI:

pip install djrill

Note: the fork you're looking at here is likely different from the official release in PyPI. If you really want this version, you can install it directly from github:

pip install git+git://github.com/medmunds/Djrill.git#egg=djrill

The only dependency other than Django is the requests library from Kenneth Reitz. (If you do not install Djrill using pip or setuptools, you will also need to pip install requests.)

Configuration

In settings.py:

  1. Add djrill to your INSTALLED_APPS:
INSTALLED_APPS = (
    ...
    "djrill"
)
  1. Add the following line, substituting your own MANDRILL_API_KEY:
MANDRILL_API_KEY = "brack3t-is-awesome"
  1. Override your existing email backend with the following line:
EMAIL_BACKEND = "djrill.mail.backends.djrill.DjrillBackend"
  1. (optional) If you want to be able to add senders through Django's admin or view stats about your messages, do the following in your base urls.py:
...
from django.contrib import admin

from djrill import DjrillAdminSite

admin.site = DjrillAdminSite()
admin.autodiscover()
...

urlpatterns = patterns('',
    ...
    url(r'^admin/', include(admin.site.urls)),
)

Usage

Since you are replacing the global EMAIL_BACKEND, all emails are sent through Mandrill's service.

In general, Djrill "just works" with Django's built-in django.core.mail package, including send_mail, send_mass_mail, EmailMessage and EmailMultiAlternatives.

You can also take advantage of Mandrill-specific features like tags, metadata, and tracking by creating a Django EmailMessage (or for HTML, EmailMultiAlternatives) object and setting Mandrill-specific properties on it before calling its send method.

Example, sending HTML email with Mandrill tags and metadata:

from django.core.mail import EmailMultiAlternatives

msg = EmailMultiAlternatives(
    subject="Djrill Message",
    body="This is the text version of your email",
    from_email="Djrill Sender <[email protected]>",
    to=["Djrill Receiver <[email protected]>", "[email protected]"],
    headers={'Reply-To': "Service <[email protected]>"} # optional extra headers
)
msg.attach_alternative("<p>This is the HTML version of your email</p>", "text/html")

# Optional Mandrill-specific extensions (see full list below):
msg.tags = ["one tag", "two tag", "red tag", "blue tag"]
msg.metadata = {'user_id': "8675309"}

# Send it:
msg.send()

If the Mandrill API returns an error response for any reason, the send call will raise a djrill.mail.backends.djrill.DjrillBackendHTTPError exception (unless called with fail_silently=True).

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

  • Djrill accepts additional headers, but only Reply-To and X-* (since that is all that Mandrill accepts). Any other extra headers will raise a ValueError exception when you attempt to send the message.
  • Djrill requires that if you attach_alternative to a message, there must be only one alternative type, and it must be text/html. Otherwise, Djrill will raise a ValueError exception when you attempt to send the message. (Mandrill doesn't support sending multiple html alternative parts, or any non-html alternatives.)
  • Djrill (currently) silently ignores all attachments on a message.
  • Djrill treats all cc and bcc recipients as if they were additional "to" addresses. (Mandrill does not distinguish cc, and only allows a single bcc -- which Djrill doesn't use. Caution: depending on the preserve_recipients setting, this could result in exposing bcc addresses to all recipients. It's probably best to just avoid bcc.)
  • All email addresses (from, to, cc) can be simple ("[email protected]") or can include a display name ("Real Name <[email protected]>").
  • The from_email must be in one of the approved sending domains in your Mandrill account.

Many of the options from the Mandrill messages/send.json 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 -- see the caution about bcc addresses above
  • 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., { '[email protected]': { '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.py for examples.

Testing

Djrill is tested against Django 1.3 and 1.4 on Python 2.6 and 2.7, and Django 1.5beta on Python 2.7. (It may also work with Django 1.2 and Python 2.5, if you use an older version of requests compatible with that code.)

https://secure.travis-ci.org/medmunds/Djrill.png?branch=master

The included tests verify that Djrill constructs the expected Mandrill API calls, without actually calling Mandrill or sending any email. So the tests don't require a Mandrill API key, but they do require mock (pip install mock). To run the tests, either:

python setup.py test

or:

python runtests.py

Release Notes

Version 0.2.0:

  • MANDRILL_API_URL is no longer required in settings.py
  • Earlier versions of Djrill required use of a DjrillMessage class to specify Mandrill-specific options. This is no longer needed -- Mandrill options can now be set directly on a Django EmailMessage object or any subclass. (Existing code can continue to use DjrillMessage.)

Thanks

Thanks to the MailChimp team for asking us to build this nifty little app. Also thanks to James Socol on Github for his django-adminplus library that got us off on the right foot for the custom admin views. Oh, and, of course, Kenneth Reitz for the awesome requests library.

djrill's People

Contributors

arnaudf avatar chrisjones-brack3t avatar jarcoal avatar kennethlove avatar medmunds avatar rebelliard avatar

Stargazers

 avatar

Watchers

 avatar  avatar

Forkers

mfogel

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.