Django Email Templates
======================

© 2016 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.4-1.9 of Django under Python
2.6 and 2.7.

| |Build Status| |Coverage Status|

-  `django-appconf`_ is the only external dependency.
-  `html2text`_ is required to use the text autogeneration
   functionality.
-  `South`_ is supported but not required (for Django<1.7).

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 = ['michael@mcoconnor.net',]
    t.attach_file('/docs/Hello.pdf')
    t.send()

Email templates support the same attributes that
``EmailMultiAlternatives``\ s 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``.

Migrations
----------

Django-emailmessagetemplates provides database migrations using both
South and Django’s built-in migration system. You can apply the
migrations as follows:

**If you’re using Django >= 1.7 and the built-in migration system:**

::

    python manage.py migrate emailmessagetemplates   

**If you’re using Django < 1.7 and South >= 1.0:**

::

    python manage.py syncdb
    python manage.py migrate emailmessagetemplates   

**If you’re using Django < 1.7 and South < 1.0:**

Include ``emailmessagetemplates`` in your ``SOUTH_MIGRATION_MODULES``
setting, like

::

    SOUTH_MIGRATION_MODULES = {
        'emailmessagetemplates': 'emailmessagetemplates.south_migrations',
    }

The run the standard migration commands:

::

    python manage.py syncdb
    python manage.py migrate emailmessagetemplates   

.. _django-appconf: https://pypi.python.org/pypi/django-appconf/0.6
.. _html2text: https://pypi.python.org/pypi/html2text
.. _South: http://south.aeracode.org/

.. |Build Status| image:: https://travis-ci.org/mcoconnor/django-emailmessagetemplates.svg?branch=master
   :target: https://travis-ci.org/mcoconnor/django-emailmessagetemplates
.. |Coverage Status| image:: https://coveralls.io/repos/mcoconnor/django-emailmessagetemplates/badge.svg?branch=master
   :target: https://coveralls.io/r/mcoconnor/django-emailmessagetemplates?branch=master