Welcome to django-templated-mail documentation!¶

Getting started¶

Supported Python versions¶

Python 2.7
Python 3.4
Python 3.5
Python 3.6

Supported Django versions¶

Django 1.8
Django 1.11
Django 2.0

Installation¶

$ pip install -U django-templated-mail

No need to add it to your INSTALLED_APPS.

Settings¶

You may optionally provide following settings:

'DOMAIN': 'example.com'
'SITE_NAME': 'Foo Website'

DOMAIN¶

Used in email template context. In most cases it is used to simplify building URLs, when frontend and backend are hosted under different address’. If not provided the current site’s domain will be used.

Required: False

SITE_NAME¶

Used in email template context. Usually it will contain the desired title of your app. If not provided the current site’s name will be used.

Default: False

Templates syntax¶

Email templates can be built using three simple blocks:

subject - used for subject of an email message
text_body - used for plaintext body of an email message (not required)
html_body - used for html body of an email message (not required)

Examples¶

{% block subject %}Text and HTML mail subject{% endblock %}

{% block text_body %}Foobar email content{% endblock %}

{% block subject %}Text and HTML mail subject{% endblock %}

{% block text_body %}Foobar email content{% endblock %}
{% block html_body %}<p>Foobar email content</p>{% endblock %}

Sample usage¶

At first let’s discuss the simplest possible use case, where you just wish to send an email to a given address and using the given template.

from templated_mail.mail import BaseEmailMessage

BaseEmailMessage(template_name='email.html').send(to=['foo@bar.tld'])

This one-liner will do all of the work required to render proper template blocks and assign the results to proper email pieces. It will also determine appropriate content type (including support for MIME) and send the output message to provided list of email address’.

You might also wish to define your own subclass of templated_mail.mail.BaseEmailMessage to customize a thing or two. What might be most interesting for you is the get_context_data method, which returns context used during template rendering.

class MyEmailMessage(BaseEmailMessage):
    def get_context_data(self):
        context = super(MyEmailMessage, self).get_context_data()
        context['foo'] = 'bar'
        return context

You might also provide custom context data using the context parameter.

from templated_mail.mail import BaseEmailMessage

BaseEmailMessage(context={'foo': 'bar'}, template_name='email.html').send(to=['foo@bar.tld'])

In other cases you might notice that some of your emails use common template_name and so to save some space you might wish to override the base class’ attribute.

class MyEmailMessage(BaseEmailMessage):
    template_name = 'email.html'