django-templated-email 3.1.1

Overview

django-templated-email is oriented towards sending templated emails. The library supports template inheritance, adding cc’d and bcc’d recipients, configurable template naming and location.

The send_templated_email method can be thought of as the render_to_response shortcut for email.

Make sure you are reading the correct documentation:

develop branch: https://github.com/vintasoftware/django-templated-email/blob/develop/README.rst

stable pypi/main: https://github.com/vintasoftware/django-templated-email/blob/main/README.rst

Requirements

• Python (3.9*, 3.10, 3.11, 3.12, 3.13)

• Django (4.2, 5.0, 5.1)

We highly recommend and only officially support the latest patch release of each Python and Django series.

Python 3.9 is no longer supported in Django 5.0 and newer, so is only supported with Django 4.2.

Getting going - installation

Installing:

pip install django-templated-email

You can add the following to your settings.py (but it works out the box):

TEMPLATED_EMAIL_BACKEND = 'templated_email.backends.vanilla_django.TemplateBackend'

# You can use a shortcut version
TEMPLATED_EMAIL_BACKEND = 'templated_email.backends.vanilla_django'

# You can also use a class directly
from templated_email.backends.vanilla_django import TemplateBackend
TEMPLATED_EMAIL_BACKEND = TemplateBackend

Sending templated emails

Example usage using vanilla_django TemplateBackend backend

Python to send mail:

from templated_email import send_templated_mail
send_templated_mail(
        template_name='welcome',
        from_email='from@example.com',
        recipient_list=['to@example.com'],
        context={
            'username':request.user.username,
            'full_name':request.user.get_full_name(),
            'signup_date':request.user.date_joined
        },
        # Optional:
        # cc=['cc@example.com'],
        # bcc=['bcc@example.com'],
        # headers={'My-Custom-Header':'Custom Value'},
        # template_prefix="my_emails/",
        # template_suffix="email",
)

If you would like finer control on sending the email, you can use get_templated_email, which will return a django EmailMessage object, prepared using the vanilla_django backend:

from templated_email import get_templated_mail
get_templated_mail(
        template_name='welcome',
        from_email='from@example.com',
        to=['to@example.com'],
        context={
            'username':request.user.username,
            'full_name':request.user.get_full_name(),
            'signup_date':request.user.date_joined
        },
        # Optional:
        # cc=['cc@example.com'],
        # bcc=['bcc@example.com'],
        # headers={'My-Custom-Header':'Custom Value'},
        # template_prefix="my_emails/",
        # template_suffix="email",
)

You can also cc and bcc recipients using cc=[‘example@example.com’].

{% block subject %}My subject for {{username}}{% endblock %}
{% block plain %}
  Hi {{full_name}},

  You just signed up for my website, using:
      username: {{username}}
      join date: {{signup_date}}

  Thanks, you rock!
{% endblock %}

{% block html %}
  <p>Hi {{full_name}},</p>

  <p>You just signed up for my website, using:
      <dl>
        <dt>username</dt><dd>{{username}}</dd>
        <dt>join date</dt><dd>{{signup_date}}</dd>
      </dl>
  </p>

  <p>Thanks, you rock!</p>
{% endblock %}

TEMPLATED_EMAIL_AUTO_PLAIN = False

def convert_html_to_text(html):
    ...

TEMPLATED_EMAIL_PLAIN_FUNCTION = convert_html_to_text

TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/' #use '' for top level template dir, ensure there is a trailing slash
TEMPLATED_EMAIL_FILE_EXTENSION = 'email'

Using with Django Anymail

Anymail integrates several transactional email service providers (ESPs) into Django, with a consistent API that lets you use ESP-added features without locking your code to a particular ESP. It supports Mailgun, Postmark, SendGrid, SparkPost and more.

You can use it with django-templated-email, just follow their instructions in their quick start to configure it.

Optionally you can use their custom EmailMessage class with django-templated-email by using the following settings:

# This replaces django.core.mail.EmailMessage
TEMPLATED_EMAIL_EMAIL_MESSAGE_CLASS='anymail.message.AnymailMessage'

# This replaces django.core.mail.EmailMultiAlternatives
TEMPLATED_EMAIL_EMAIL_MULTIALTERNATIVES_CLASS='anymail.message.AnymailMessage'

Inline images

You can add inline images to your email using the InlineImage class.

First get the image content from a file or a ImageField:

# From a file
with open('pikachu.png', 'rb') as pikachu:
  image = pikachu.read()

# From an ImageField
# Suppose we have this model
class Company(models.Model):
  logo = models.ImageField()

image = company.logo.read()

Then create an instance of InlineImage:

from templated_email import InlineImage

inline_image = InlineImage(filename="pikachu.png", content=image)

Now pass the object on the context to the template when you send the email.

send_templated_mail(template_name='welcome',
                    from_email='from@example.com',
                    recipient_list=['to@example.com'],
                    context={'pikachu_image': inline_image})

Finally in your template add the image on the html template block:

<img src="{{ pikachu_image }}">

Note: All InlineImage objects you add to the context will be attached to the e-mail, even if they are not used in the template.

Add link to view the email on the web

# Add templated email to INSTALLED_APPS
INSTALLED_APPS = [
  ...
  'templated_email'
]

# and this to your url patterns
url(r'^', include('templated_email.urls', namespace='templated_email')),

# when sending the email use the *create_link* parameter.
send_templated_mail(
    template_name='welcome', from_email='from@example.com',
    recipient_list=['to@example.com'],
    context={}, create_link=True)

And, finally add the link to your template.

<!-- With the 'if' the link will only appear on the email. -->
{% if email_uuid %}
  <!-- Note: you will need to add your site since you will need to access
             it from the email -->
  You can view this e-mail on the web here:
  <a href="http://www.yoursite.com{% url 'templated_email:show_email' uuid=email_uuid %}">
    here
  </a>
{% endif %}

Notes:

• A copy of the rendered e-mail will be stored on the database. This can grow if you send too many e-mails. You are responsible for managing it.

• If you use InlineImage all images will be uploaded to your media storage, keep that in mind too.

Class Based Views

It’s pretty common for emails to be sent after a form is submitted. We include a mixin to be used with any view that inherit from Django’s FormMixin.

In your view add the mixin and the usual Django’s attributes:

from templated_email.generic_views import TemplatedEmailFormViewMixin

class AuthorCreateView(TemplatedEmailFormViewMixin, CreateView):
    model = Author
    fields = ['name', 'email']
    success_url = '/create_author/'
    template_name = 'authors/create_author.html'

By default the template will have the form_data if the form is valid or from_errors if the form is not valid in it’s context.

You can view an example here

Now you can use the following attributes/methods to customize it’s behavior:

Attributes:

templated_email_template_name (mandatory if you don’t implement templated_email_get_template_names()):

String naming the template you want to use for the email. ie: templated_email_template_name = ‘welcome’.

templated_email_send_on_success (default: True):

This attribute tells django-templated-email to send an email if the form is valid.

templated_email_send_on_failure (default: False):

This attribute tells django-templated-email to send an email if the form is invalid.

templated_email_from_email (default: settings.TEMPLATED_EMAIL_FROM_EMAIL. If it’s also not defined, falls back to DEFAULT_FROM_EMAIL):

String containing the email to send the email from.

Methods:

templated_email_get_template_names(self, valid) (mandatory if you don’t set templated_email_template_name):

If the method returns a string it will use it as the template to render the email. If it returns a list it will send the email only with the first existing template.

templated_email_get_recipients(self, form) (mandatory):

Return the recipient list to whom the email will be sent to. ie:

def templated_email_get_recipients(self, form):
    return [form.data['email']]

templated_email_get_context_data(**kwargs) (optional):

Use this method to add extra data to the context used for rendering the template. You should get the parent class’s context from calling super. ie:

def templated_email_get_context_data(self, **kwargs):
    context = super(ThisClassView, self).templated_email_get_context_data(**kwargs)
    # add things to context
    return context

templated_email_get_send_email_kwargs(self, valid, form) (optional):

Add or change the kwargs that will be used to send the e-mail. You should call super to get the default kwargs. ie:

def templated_email_get_send_email_kwargs(valid, form):
  kwargs = super(ThisClassView, self).templated_email_get_send_email_kwargs(valid, form)
  kwargs['bcc'] = ['admin@example.com']
  return kwargs

templated_email_send_templated_mail(*args, **kwargs) (optional):

This method calls django-templated-email’s send_templated_mail method. You could change this method to use a celery’s task for example or to handle errors.

Settings

You can configure Django-Templated-Email by setting the following settings

TEMPLATED_EMAIL_FROM_EMAIL = None                 # String containing the email to send the email from - fallback to DEFAULT_FROM_EMAIL
TEMPLATED_EMAIL_BACKEND = TemplateBackend         # The backend class that will send the email, as a string like 'foo.bar.TemplateBackend' or the class reference itself
TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/' # The directory containing the templates, use '' if using the top level
TEMPLATED_EMAIL_FILE_EXTENSION = 'email'          # The file extension of the template files
TEMPLATED_EMAIL_AUTO_PLAIN = True                 # Set to false to disable the behavior of calculating the plain part from the html part of the email when `html2text <https://pypi.python.org/pypi/html2text>` is installed
TEMPLATED_EMAIL_PLAIN_FUNCTION = None             # Specify a custom function that converts from HTML to the plain part

# Specific for anymail integration:
TEMPLATED_EMAIL_EMAIL_MESSAGE_CLASS = 'django.core.mail.EmailMessage'                     # Replaces django.core.mail.EmailMessage
TEMPLATED_EMAIL_EMAIL_MULTIALTERNATIVES_CLASS = 'django.core.mail.EmailMultiAlternatives' # Replaces django.core.mail.EmailMultiAlternatives

Future Plans

See https://github.com/vintasoftware/django-templated-email/issues?state=open

Using django_templated_email in 3rd party applications

If you would like to use django_templated_email to handle mail in a reusable application, you should note that:

• Your calls to send_templated_mail should set a value for template_dir, so you can keep copies of your app-specific templates local to your app (although the loader will find your email templates if you store them in <your app>/templates/templated_email, if TEMPLATED_EMAIL_TEMPLATE_DIR has not been overridden)

• If you do (and you should) set a value for template_dir, remember to include a trailing slash, i.e. ‘my_app_email/’

• The deployed app may use a different backend which doesn’t use the django templating backend, and as such make a note in your README warning developers that if they are using django_templated_email already, with a different backend, they will need to ensure their email provider can send all your templates (ideally enumerate those somewhere convenient)

Notes on specific backends

TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/' #Use '' for top level template dir
TEMPLATED_EMAIL_FILE_EXTENSION = 'email'

TEMPLATED_EMAIL_DJANGO_SUBJECTS = {
    'welcome':'Welcome to my website',
}

from_email='your.email@com/'          # Override the email sender. Default: (default: **settings.TEMPLATED_EMAIL_FROM_EMAIL**. If it's also not defined, falls back to **DEFAULT_FROM_EMAIL**)
template_prefix='your_template_dir/'  # Override where the method looks for email templates (alternatively, use template_dir)
template_suffix='email'               # Override the file extension of the email templates (alternatively, use file_extension)
cc=['fubar@example.com']              # Set a CC on the mail
bcc=['fubar@example.com']             # Set a BCC on the mail
template_dir='your_template_dir/'     # Override where the method looks for email templates
connection=your_connection            # Takes a django mail backend connection, created using **django.core.mail.get_connection**
auth_user='username'                  # Override the user that the django mail backend uses, per **django.core.mail.send_mail**
auth_password='password'              # Override the password that the django mail backend uses, per **django.core.mail.send_mail**

Releasing a new version of this package:

• Create a new branch off develop, named like feat/update-to-x.y.z where x.y.z is the new version number.

• Update CHANGELOG file.

• Update the version executing:

  bumpversion [major,minor,patch]

• Open a pull request to merge your branch into main, and get it reviewed.

• Once the pull request is approved and merged, checkout main branch and pull the latest changes.

• Push the tag generated by bumpversion to the remote repository:

  git push origin --tags

• Create a new release on GitHub, using the tag created by bumpversion. Make sure to use the same version number as the one you set with bumpversion.

• Finally, publish the new version to PyPI executing:

  python -m build
  python -m twine upload dist/*

• Update develop branch with the changes from main, and push it to the remote repository:

  git checkout develop
  git pull origin main
  git push origin develop

Commercial Support

This project, as other Vinta Software open-source projects is used in products of Vinta’s clients. We are always looking for exciting work, so if you need any commercial support, feel free to get in touch: contact@vinta.com.br