Quick start guide

Prerequisites

  • You’ll need Django 1.11.1 or later.
  • Your project needs to use either Django’s default DjangoTemplates or Jinja2 template engine.
  • Your project needs to use Python 3.5 or later.

Installation

This package isn’t on PyPI yet, so you’ll need to install it directly from GitHub for now:

pip install git+git://github.com/18F/django-email-pal

Required settings

Add emailpal.apps.EmailPalConfig to your INSTALLED_APPS setting, e.g.:

INSTALLED_APPS = (
    # ...
    'emailpal.apps.EmailPalConfig',
    # ...
)

Then add the following to your project’s urls.py:

from django.conf.urls import include, url

urlpatterns = [
    # ...
    url(r'^examples/', include('emailpal.urls')),
    # ...
]

This sets up the email example gallery at /examples/ on your app. You can change it to something else if you want, or you can hide it behind some logic if you only want it to be exposed during development.

Your first email

Let’s get started by adding an email example to your project. We’re going to assume that your project has an app called example in it.

Create a file at example\emails.py and put the following in it:

from emailpal import SendableEmail


class MySendableEmail(SendableEmail):
    """
    This is a simple example email.
    """

    template_name = 'example/my_template.html'
    subject = 'Check this out, {full_name}!'
    example_ctx = {'full_name': 'Jane Doe'}

Then create a file at example\templates\example\my_template.html and put this in it:

{% extends "emailpal/really_simple/base.html" %}

{% block content %}
<p>Hello {{ full_name }},</p>

<p>This is a simple email which uses Lee Munroe's <em>Really Simple
Responsive HTML Email Template</em> to be easily viewable across a
wide range of mail clients.</p>

{% include "emailpal/really_simple/cta.html" with action="learn more about the template" url="https://github.com/leemunroe/responsive-html-email-template" %}

<p>Hopefully it will be useful.</p>
{% endblock %}

Important

If you’re using Jinja2, you’ll want to put the template at example\jinja2\example\my_template.html.

Also, replace the line containing the {% include %} directive with the following:

{% with action="learn more about the template",
        url="https://github.com/leemunroe/responsive-html-email-template" %}
{% include "emailpal/really_simple/cta.html" %}
{% endwith %}

As you can probably guess, the email expects the context variable full_name to contain the full name of the recipient. The example version of the email will use “Jane Doe”.

The email will also contain a call-to-action (CTA) that directs the user to a website.

Sending the email

You can create a Django EmailMessage with your email’s create_message() method like so:

msg = MySendableEmail().create_message(
    {'full_name': 'boop jones'},
    from_email='foo@example.org',
    to=['bar@example.org'],
    headers={'Message-ID': 'blah'},
)

Then you can send the message with msg.send().

Adding smoke tests

Since your email has an example context, it’s straightforward to add smoke tests for it: just render the email with the example context and make sure nothing explodes. In fact, django-email-pal comes with tooling that makes this particularly easy.

Just create a new test module and add the following to it:

from unittest import TestCase
from emailpal import EmailSmokeTestsMixin


class EmailTests(TestCase, EmailSmokeTestsMixin):
    pass

Now when you run manage.py test (or whatever your choice of test runners is), all the emails you’ve listed in settings.SENDABLE_EMAILS will be rendered with their example context to ensure that they don’t throw any exceptions.