A standalone Django app to send templated emails in batch. Features a custom query engine and template editor with preview.
Project description
django-massmailer
django-massmailer
is a standalone Django app that you can plug in your
website to send e-mails in bulk. It features:
-
An e-mail template engine to write your e-mail template, supporting both plaintext and HTML, with a live preview:
-
A query language to select the subset of users you want to send e-mails to, and preview the list of selected users:
-
A batch status report that shows how many e-mails have been sent, and is able to track bounces.
Installation
First, install django-massmailer
and its Python dependencies:
pip install django-massmailer
Then, add massmailer
and its Django dependencies to your project's
INSTALLED_APPS
:
INSTALLED_APPS = (
# ...
'massmailer',
'crispy_forms',
'django_bootstrap_breadcrumbs',
'reversion',
)
Add the following URL pattern to your urls.py
to put the mailing
dashboard in /mailing
:
urlpatterns = [
# ...
path('mailing', include('massmailer.urls')),
]
Then, execute the migrations to create the massmailer models:
python3 manage.py migrate
You also need to have a working Celery setup with your website. You can check out the official tutorial to setup Celery in your Django website, or just look at how we do it in our demo application:
How to use
Permissions
Only staff users can see the mailing dashboard. By default, only superusers can use anything in massmailer. There are three categories of permissions you can grant to some staff users to allow them to make changes:
mailing.{view,create,change,delete}_template
to view, create, change and delete templates.mailing.{view,create,change,delete}_query
to view, create, change and delete queries. ⚠ These permissions give access to personal user data. ⚠mailing.{view,create,change,delete}_batch
to view, send, change and delete batches. ⚠ These permissions give access to sending bulk e-mails. ⚠
Because django-massmailer
intrinsically gives access to powerful features
(access to user data and sending e-mails in bulk) it is strongly recommended to
be as restrictive as possible when granting these permissions to prevent abuse
or spam.
Query syntax
django-massmailer
allows you to write queries in a domain-specific language
to select the users you want to reach. You can think of it as heavily
simplified SQL with a syntax that looks like filters in the Django ORM.
Here is a short demonstration of the syntax:
SomeModel [as name]
.field = 42
(.field contains "string" or
.field contains i"case insensitive")
count(.related_field) > 10
alias some_name = .some_field
Filters are implicity joined by the and operator. If you are not querying on the User model directly, you must create a user alias targeting a field containing the related user.
Templates
Templates use the Jinja2 templating engine to generate the contents of the e-mails. The model selected in your query will be passed directly in the context of the template, as well as the different aliases that were defined in the query.
There are three templates you have to fill, one for the subject line, one for the plaintext content, and optionally one for the HTML content. The HTML template can also be generated directly from the plaintext e-mail.
Example:
Greetings, {{ user.get_full_name().strip().title() }}!
{% if user.is_staff %}With great power comes great responsibility.{% endif %}
Template filters
In addition to the Jinja2 builtin
filters,
django-massmailer
provides a few other convenience filters.
The following filters are directly passed to the Babel functions of the same name using the locale set in template:
format_date
: formats the date according to a given pattern.format_time
: formats the time according to a given pattern.format_datetime
: formats the datetime according to a given pattern.
Example:
You have joined our website on {{ user.date_joined|format_date }}.
Contributing
django-massmailer
enforces various style constraints. You need to install
pre-commit hooks to make sure your commits respect them:
pip install -r requirements-dev.txt
pre-commit install
Licence
django-massmailer
is distributed under the GPLv3 licence.
- Copyright (C) 2016 Alexandre Macabies
- Copyright (C) 2016 Antoine Pietri
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
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
Built Distribution
Hashes for django_massmailer-0.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0147954914ad6d961d717b5621064fca2d2a79c3cc1c0c35d35586d0a8c6b599 |
|
MD5 | 77e763189e0e75190675d225c515b7de |
|
BLAKE2b-256 | be978ad916a14d0eb72fce08ffdd2a0c1a43d8412ff70f1c6ace7b3167f146af |