Welcome to TemplateMail

TemplateMail is a simple Python library that solves most projects' email templating and delivery needs with minimal hassle. Suppose you want to send a welcome email to a new user using Mailgun:

import templatemail
import templatemail.engines.mailgun

# Credentials for Mailgun
MAILGUN_API_KEY = 'YOUR API KEY'
MAILGUN_DOMAIN = 'MAILGUN_DOMAIN'

# The engine is in charge of sending email using a backend system.
engine = templatemail.engines.mailgun.MailgunDeliveryEngine(
    api_key=MAILGUN_API_KEY,
    domain_name=MAILGUN_DOMAIN)
    
# The mailer is in charge of rendering templates and sending them using an engine.
mailer = templatemail.TemplateMail(
    template_dirs=['email_templates'],
    delivery_engine=engine)

# Using the two, you can send templates.
template_name = 'welcome.html'
result = mailer.send_email(
    to_addresses=['test@example.com'],
    from_address='from@example.com',
    template_name=template_name,
    user_name='Ken'
)

welcome.html is an email template used to render the subject, html, and text versions of an email. Let's have a look at email_templates/welcome.html:

{% block subject %}Welcome to our system{% endblock %}
{% block html_body %}
<h1>Welcome to our system, {{ user_name }}</h1>
<p>We think you'll really enjoy it here.</p>
{% endblock %}
{% block text_body %}
Welcome to our system, {{ user_name }}
--------------------------------------------

We think you'll really enjoy it here.
{% endblock %}

The subject block renders the subject, while html_body and text_body render the HTML and text versions of the email respectively. The work of composing the correct mime envelope, as well as delivery, is handled by an engine. At this time, TemplateMail has native Mailgun and SMTP backends, however you are also free to write your own. (See Writing your own engine)

It's that simple.

Installation

You can install templatemail like any other Python module.

pip install templatemail

NOTE: Only Python 3 is supported.

Read More

Read the documentation online at Read The Docs.

Get in touch

Have a pull request or an issue? Use Github.

Legal stuff

© Copyright 2019 Ken Kinder. Includes work from Mailgun, which is © Copyright 2014 Mailgun.

TemplateMail is licensed under the Apache 2.0 license. See LICENSE for details.

Includes templates from the Mailgun Responsive Templates repository. See LICENSE-mailgun-templates for details on its license.