Skip to main content

Templated Email for Python

Project description

![Build Status](https://travis-ci.org/kkinder/templatemail.svg?branch=master)

![Build Status](https://travis-ci.org/kkinder/templatemail.svg?branch=master)

# 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:

```python
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`:

```jinja2
{% 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](/engines/#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](https://templatemail.readthedocs.io/en/latest/) at Read The Docs.

## Get in touch
Have a pull request or an issue? [Use Github](https://github.com/kkinder/templatemail).

## 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

templatemail-0.2.0.tar.gz (9.0 kB view details)

Uploaded Source

File details

Details for the file templatemail-0.2.0.tar.gz.

File metadata

  • Download URL: templatemail-0.2.0.tar.gz
  • Upload date:
  • Size: 9.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.18.4 setuptools/40.6.3 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.6.7

File hashes

Hashes for templatemail-0.2.0.tar.gz
Algorithm Hash digest
SHA256 1d6dbd93fea111703218b130cdc9fffe372eb24bc8939e685200d17dc1b5c580
MD5 c0cc1b63cd6bf85d344be31e8bdba6c5
BLAKE2b-256 0d8dfd3c289f1b99ad45fc40d4ca4a7be21c4b02cfcc84219454eba1b6af5db0

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page