Skip to content

Latest commit

 

History

History
148 lines (112 loc) · 5.94 KB

README.rst

File metadata and controls

148 lines (112 loc) · 5.94 KB
Raw

Django Email Templates

© 2019 Michael O’Connor, http://www.mcoconnor.net https://github.com/mcoconnor/django-emailmessagetemplates

In many cases, users will want to be able to edit the emails sent by your application without having to go to developers to change hard-coded email content. This package provides a Django app that allows users to edit email content with an easy-to-integrate developer API.

Requirements

Django Email Templates supports versions 1.9-1.11 of Django under Python 2.7.

Build Status Coverage Status
  • django-appconf is the only external dependency.
  • html2text is required to use the text autogeneration functionality.

Installation

Django Email Templates is a standard Django app.

To add it to a project, just include 'emailmessagetemplates' in the INSTALLED_APPS section of your settings.py file.

If you would like to use text version autogeneration for HTML templates, include the text_autogen extras in your install (e.g. pip install django-emailmessagetemplates[text_autogen]) or ensure you've installed html2text separately.

Usage

The central piece of functionality in this app is the EmailMessageTemplate class, which is a Django model that also inherits from Django’s EmailMultiAlternatives class. Usage is derived from its parents: to select a template to send, query for it as a model. To send an email, first populate the message with the template context, recipients, and other data, and then call the send method. For example:

::

from emailmessagetemplates.models import EmailMessageTemplate

t = EmailMessageTemplate.objects.get(name='Hello World') t.context = {'a':'hello','b':'world'} t.to = ['[email protected]',] t.attach_file('/docs/Hello.pdf') t.send()

Email templates support the same attributes that EmailMultiAlternativess do, including to, cc, bcc, from_email, headers, and attachments.

HTML/Multipart Messages

Django Email Templates can either send plain text emails or HTML formatted messages with plain-text alternative content. To enable HTML emails, the EMAILMESSAGETEMPLATES_ALLOW_HTML_MESSAGES setting must be set to True, and the type field on the EmailMessageTemplate instance must be set to ‘HTML’. Plain text alternative can either be auto-generated from the rendered HTML body content (via the HTML2Text library, which converts the message to Markdown) or by manually maintaining a separate plain text body template.

Convenience Functions

The email convenience functions provided by Django replicated for message templates. These include send_mail, send_mass_mail, mail_admins, mail_managers and are used similarly:

::
from emailmessagetemplates.utils import send_mail, send_mass_mail,
mail_admins, mail_managers
send_mail(name, related_object=None, context={}, from_email=None,
recipient_list=[], fail_silently=False, auth_user=None, auth_password=None, connection=None)
send_mass_mail(name, related_object=None, datatuple=(), fail_silently=False,
auth_user=None, auth_password=None, connection=None)
mail_admins(name, related_object=None, context={}, fail_silently=False,
connection=None)
mail_managers(name, related_object=None, context={}, fail_silently=False,
connection=None)

Differences from EmailMultiAlternatives

While EmailMessageTemplate behaves like Django’s EmailMultiAlternatives in many ways, there are some differences:

  • Subject and body values cannot be set directly; instead they’re constructed from templates saved in the model rendered against the specified context
  • If from_email is not specified when a message is prepared, the value defaults first to the sender set on the template model, then to the EMAILMESSAGETEMPLATES_DEFAULT_FROM_EMAIL setting
  • Values required by the message (e.g the recipients) cannot be set in the EmailMessageTemplate constructor like they are for EmailMessage (since normally you will retrieve an existing model instance rather than constructing one). Instead, they must be set individually on the instance.
  • An HTML alternative is automatically added for messages with an HTML type (when HTML messages are permitted by application settings). A plain text alternative is also provided, either generated from a separate template or autogenerated from the HTML content.

Settings

EMAILMESSAGETEMPLATES_DEFAULT_FROM_EMAIL

Default: The DEFAULT_FROM_EMAIL value from your project’s settings.

The default email address to use for message sent from templates. This is can be overridden on a per-template basis by setting the sender field on the template model instance. It can be overridden on a per-email basis by setting the from_email attribute on an instantiated EmailMessageTemaple object or using the from_email argument to any of the convenience functions.

EMAILMESSAGETEMPLATES_ALLOW_HTML_MESSAGES

Default: False

If true, templates can produce HTML-formatted messages and provide plain-text alternative content. Enabling this option will display additional fields in the Django admin form and will enable HTML generation for templates that have a type of text/html.