A Django email backend for hijacking email sending in a test environment.
Python
Switch branches/tags
Nothing to show
Pull request Compare This branch is 4 commits ahead, 62 commits behind caktus:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bandit
.gitignore
CHANGELOG.rst
LICENSE.txt
MANIFEST.in
README.rst
runtests.py
setup.py

README.rst

Django-Email-Bandit

A Django email backend for hijacking email sending in test environment. It extends the default SMTP backend to intercept outgoing emails and instead send them to a single email address.

It does not intercept emails going to the site admins (as defined by the ADMINS setting) so it will not impact the 500 error emails.

Requirements

  • Django >= 1.2

Installation

To install django-email-bandit via pip:

pip install django-email-bandit

Or you can from the latest version from Github manually:

git clone git://github.com/caktus/django-email-bandit.git
cd django-email-bandit
python setup.py install

or via pip:

pip install -e git+https://github.com/caktus/django-email-bandit.git

Add django-email-bandit to your installed apps:

INSTALLED_APPS = (
    ...
    'bandit',
    ...
)

For your test environment you should enable the backend:

EMAIL_BACKEND = 'bandit.backends.smtp.HijackSMTPBackend'

and set the email which will receive all of the emails:

BANDIT_EMAIL = 'bandit@example.com'

Using django-seacucumber

django-email-bandit supports sending email through SES via django-seacucumber.

To configure django-email-bandit, set your email backend as follows:

EMAIL_BACKEND = 'bandit.backends.seacuke.HijackSESBackend'

Only logging emails

In environments where your application may generate lots of emails all at once, it may be desirable to hijack emails to non-admins and have them logged, but not sent out.

django-email-bandit supports this with the bandit.backends.smtp.LogOnlySMTPBackend and the bandit.backends.seacuke.LogOnlySESBackend. For example, to configure django-email-bandit to only log emails to non-admins, but still send via SMTP emails to admins, configure your email backend like so:

EMAIL_BACKEND = 'bandit.backends.smtp.LogOnlySMTPBackend'

Whitelisting certain email addresses

In certain scenarios, you may want to allow certain email domains to bypass bandit (eg: you want to let a client test the site's emails). In that case, you can use BANDIT_WHITELIST_EMAILS to set a list of email patterns (regular expressions) that will not be affected by bandit.

To allow emails to be sent to any emails for theclient.com, use the following:

BANDIT_WHITELIST_EMAILS = [r'.*\@theclient\.com',]

You can also add your own company's domain so developers will receive emails:

BANDIT_WHITELIST_EMAILS = [
    r'.*\@theclient\.com',
    r'.*\@mycompany\.com',
]

although it's more efficient to use one regular expression for that:

BANDIT_WHITELIST_EMAILS = [
    r'.*\@(theclient\.com|mycompany\.com)',
]

Hijacking Arbitrary Backends

You can also hijack email to an arbitrary Django email backend by wrapping a backend of your choice with the HijackBackendMixin. For example, if you wanted to send email through SES but prefer to use django-ses, you would create a class like this inside your project:

from django_ses import SESBackend
from bandit.backends.base import HijackBackendMixin


class MyHijackBackend(HijackBackendMixin, SESBackend):
    """
    This backend intercepts outgoing messages drops them to a single email
    address, using the SESBackend in django-ses.
    """
    pass

and then set EMAIL_BACKEND as follows:

EMAIL_BACKEND = 'my.project.path.to.MyHijackBackend'

Note that the order in which you specify the mixin and base class is very important. If you specify the mixin last, your email will not be hijacked.

Questions or Issues?

If you have questions, issues or requests for improvements please let us know on Github.

Development sponsored by Caktus Consulting Group, LLC.