appmail 1.3

Description:

appmail 1.3

Django-AppMail
Django app for managing transactional email templates.

Compatibility
This project now requires Django2.2+ and Python3.7+. If you require a previous
version you will have to refer to the relevant branch or tag.


Background
This project arose out of a project to integrate a large transactional Django
application with Mandrill, and the lessons learned. It also owes a minor h/t
to this project from 2011 (https://github.com/hugorodgerbrown/AppMail).
The core requirement is to provide an easy way to add / edit email templates
to a Django project, in such a way that it doesn’t require a developer to make
changes. The easiest way to use templated emails in Django is to rely on the
in-built template structure, but that means that the templates are held in
files, under version control, which makes it very hard for non-developers to
edit.
This is not a WYSIWYG HTML editor, and it doesn’t do anything clever. It
doesn’t handle the sending of the emails - it simply provides a convenient
mechanism for storing and rendering email content.
from appmail.models import EmailTemplate

def send_order_confirmation(order_id):
order = Orders.objects.get(id=order_id)
template = EmailTemplate.objects.current('order_confirmation')
context = { "order": order }
# create_message accepts EmailMultiAlternatives constructor kwargs
# and returns a standard Django email object which can be updated / sent.
message = template.create_message(context, to=[order.recipient.email])
message.send()
The core requirements are:

List / preview existing templates
Edit subject line, plain text and HTML content
Use standard Django template syntax
Support base templates
Template versioning
Language support
Send test emails

Template properties
Individual templates are stored as model objects in the database. The
standard Django admin site is used to view / filter templates. The templates
are ordered by name, language and version. This combination is unique. The
language and version properties have sensible defaults (
version=settings.LANGUAGE_CODE and version=0) so don’t need to set if you
don’t require it. There is no inheritance or relationship between different
languages and versions - they are stored as independent objects.
# get the default order_summary email (language = settings.LANGUAGE_CODE)
template = EmailTemplate.objects.current('order_summary')
# get the french version
template = EmailTemplate.objects.current('order_summary', language='fr')
# get a specific version
template = EmailTemplate.objects.version('order_summary', 1)
Template syntax
The templates themselves use standard Django template syntax, including
the use of tags, filters. There is nothing special about them, however there
is one caveat - template inheritance.
Template inheritance
Although the template content is not stored on disk, without re-engineering
the template rendering methods any parent templates must be. This is annoying,
but there is a valid assumption behind it - if you are changing your base
templates you are probably involving designers and developers already, so
having to rely on a developer to make the changes is acceptable.
Sending test emails
You can send test emails to an email address through the admin list view.

The custom admin action ‘Send test emails’ will redirect to an intermediate
page where you can enter the recipient email address and send the email:

There is also a linkon individual template admin pages (top-right, next to the history link):




Tests
There is a test suite for the app, which is best run through tox.


Licence
MIT


Contributing
Usual rules apply:

Fork to your own account
Create a branch, fix the issue / add the feature
Submit PR

Please take care to follow the coding style - and PEP8.


Release
If you have found yourself in the situation of having to release a new version, and assuming you already have the necessary PyPi permissions, here are the next steps you need to take:

1. Update `setup.py` with the bumped version. Push it to master

PATCH version for backwards-compatible hotfixes
MINOR version for backwards-compatible features
MAJOR version for incompatible features


2. Tag this new version by running the following commands

git tag -a v1.0.x -m v.1.0.x
git push –tags



Now, if you go to github and take a look at the tags, you should be able to see your version among them.

3. Build the wheel

python3 setup.py sdist bdist_wheel


4. Upload it on PyPi using twine

twine upload dist/*
you will be asked to provide your PyPi username and password