Skip to main content

A Django app that allows users to edit email content with an easy-to-integrate developer API.

Project description

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

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

History

0.1.2 (2016-5-6)

  • Update for Django>=1.9

0.1.1 (2015-3-19)

  • Fix packaging errors

  • Add South initial migration

0.1.0 (2015-3-18)

  • First release on PyPI.

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

django-emailmessagetemplates-0.1.2.tar.gz (17.6 kB view hashes)

Uploaded Source

Supported by

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