{% trans "Send Test Emails" %}
17 |
18 |
25 | {% trans 'Templates to test' %}
19 |-
20 | {% for template in templates %}
21 |
- {{ template.name }}: "{{ template.subject }}" 22 | {% endfor %} 23 |
26 |
48 | {% endblock %}
49 |
--------------------------------------------------------------------------------
/appmail/management/commands/truncate_logged_messages.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 |
3 | from datetime import date, timedelta
4 | from typing import Any
5 |
6 | from django.core.management.base import BaseCommand, CommandParser
7 | from django.db.models.query import QuerySet
8 | from django.utils.translation import gettext_lazy as _lazy
9 |
10 | from appmail.models import LoggedMessage
11 | from appmail.settings import LOG_RETENTION_PERIOD
12 |
13 |
14 | class Command(BaseCommand):
15 | help = _lazy("Truncate all log records that have passed the LOG_RETENTION_PERIOD.")
16 |
17 | def add_arguments(self, parser: CommandParser) -> None:
18 | super().add_arguments(parser)
19 | parser.add_argument(
20 | "-r",
21 | "--retention",
22 | dest="retention",
23 | type=int,
24 | default=LOG_RETENTION_PERIOD,
25 | help="The number of days to retain logged messages.",
26 | )
27 | parser.add_argument(
28 | "-c",
29 | "--commit",
30 | dest="commit",
31 | action="store_true",
32 | default=False,
33 | help="If not set the transaction will be rolled back (no change).",
34 | )
35 |
36 | def get_logs(self, cutoff: date) -> QuerySet:
37 | """Return the queryset of logs to delete."""
38 | return LoggedMessage.objects.filter(timestamp__lt=cutoff)
39 |
40 | def cutoff(self, retention: int) -> date:
41 | """Return the date before which to truncate logs."""
42 | return date.today() - timedelta(days=retention)
43 |
44 | def handle(self, *args: Any, **options: Any) -> None:
45 | retention = options["retention"]
46 | commit = options["commit"]
47 | cutoff = self.cutoff(retention)
48 | self.stdout.write(f"Truncating records before {cutoff}")
49 | logs = self.get_logs(cutoff)
50 | self.stdout.write(f"Deleting {logs.count()} records")
51 | if not commit:
52 | self.stderr.write("Aborting transaction as --commit is False.")
53 | return
54 | count, _ = logs.delete()
55 | self.stdout.write(f"Deleted {count} records.")
56 | return
57 |
--------------------------------------------------------------------------------
/.github/workflows/tox.yml:
--------------------------------------------------------------------------------
1 | name: Python / Django
2 |
3 | on:
4 | push:
5 | branches:
6 | - master
7 |
8 | pull_request:
9 | types: [opened, synchronize, reopened]
10 |
11 | jobs:
12 | format:
13 | name: Check formatting
14 | runs-on: ubuntu-latest
15 | strategy:
16 | matrix:
17 | toxenv: [fmt, lint, mypy]
18 | env:
19 | TOXENV: ${{ matrix.toxenv }}
20 |
21 | steps:
22 | - name: Check out the repository
23 | uses: actions/checkout@v4
24 |
25 | - name: Set up Python (3.11)
26 | uses: actions/setup-python@v4
27 | with:
28 | python-version: "3.11"
29 |
30 | - name: Install and run tox
31 | run: |
32 | pip install tox
33 | tox
34 |
35 | checks:
36 | name: Run Django checks
37 | runs-on: ubuntu-latest
38 | strategy:
39 | matrix:
40 | toxenv: ["django-checks"]
41 | env:
42 | TOXENV: ${{ matrix.toxenv }}
43 |
44 | steps:
45 | - name: Check out the repository
46 | uses: actions/checkout@v4
47 |
48 | - name: Set up Python (3.11)
49 | uses: actions/setup-python@v4
50 | with:
51 | python-version: "3.11"
52 |
53 | - name: Install and run tox
54 | run: |
55 | pip install tox
56 | tox
57 |
58 | test:
59 | name: Run tests
60 | runs-on: ubuntu-latest
61 | strategy:
62 | matrix:
63 | python: ["3.9", "3.10", "3.11", "3.12"]
64 | # build LTS versions and main
65 | django: ["42", "50", "52", "main"]
66 | exclude:
67 | - python: "3.9"
68 | django: "50"
69 | - python: "3.9"
70 | django: "52"
71 | - python: "3.9"
72 | django: "main"
73 | - python: "3.10"
74 | django: "main"
75 | - python: "3.11"
76 | django: "main"
77 |
78 | env:
79 | TOXENV: django${{ matrix.django }}-py${{ matrix.python }}
80 |
81 | steps:
82 | - name: Check out the repository
83 | uses: actions/checkout@v4
84 |
85 | - name: Set up Python ${{ matrix.python }}
86 | uses: actions/setup-python@v4
87 | with:
88 | python-version: ${{ matrix.python }}
89 |
90 | - name: Install and run tox
91 | run: |
92 | pip install tox
93 | tox
94 |
--------------------------------------------------------------------------------
/tests/test_helpers.py:
--------------------------------------------------------------------------------
1 | from django.test import TestCase
2 |
3 | from appmail import helpers
4 |
5 |
6 | class HelperTests(TestCase):
7 | """appmail.helpers module tests."""
8 |
9 | def test_get_context(self):
10 | self.assertEqual(
11 | helpers.get_context("{{a}} {{b.c}}"), {"a": "A", "b": {"c": "C"}}
12 | )
13 |
14 | def test_extract_vars(self):
15 | """Check extract_vars handles expected input."""
16 | for x, y in (
17 | ("", []),
18 | (None, []),
19 | ("{{foo}}", ["foo"]),
20 | ("{{ foo}}", ["foo"]),
21 | ("{{ foo }}", ["foo"]),
22 | ("{{ foo }", []),
23 | ("{% foo %}", []),
24 | ("{{ foo|time }}", []),
25 | ("{{foo}} {{bar}}", ["foo", "bar"]),
26 | ):
27 | self.assertEqual(set(helpers.extract_vars(x)), set(y))
28 |
29 | def test_expand_list(self):
30 | """Check dot notation expansion."""
31 | self.assertRaises(ValueError, helpers.expand_list, None)
32 | self.assertRaises(ValueError, helpers.expand_list, "")
33 | self.assertEqual(helpers.expand_list(["a", "b.c"]), {"a": {}, "b": {"c": {}}})
34 |
35 | def test_fill_leaf_values(self):
36 | """Check the default func is applied."""
37 | self.assertRaises(ValueError, helpers.fill_leaf_values, None)
38 | self.assertRaises(ValueError, helpers.fill_leaf_values, "")
39 | self.assertEqual(
40 | helpers.fill_leaf_values({"a": {}, "b": {"c": {}}}),
41 | {"a": "A", "b": {"c": "C"}},
42 | )
43 |
44 | def test_merge_dicts(self):
45 | self.assertEqual(helpers.merge_dicts({"foo": 1}), {"foo": 1})
46 | self.assertEqual(
47 | helpers.merge_dicts({"foo": 1}, {"bar": 2}), {"foo": 1, "bar": 2}
48 | )
49 | self.assertEqual(helpers.merge_dicts({"foo": 1}, {"foo": 2}), {"foo": 2})
50 |
51 | def test_patch_context(self):
52 | foo = {"foo": 1}
53 | bar = {"bar": 2}
54 | baz = {"baz": 3}
55 |
56 | def cp1(request):
57 | return bar
58 |
59 | def cp2(request):
60 | return baz
61 |
62 | self.assertEqual(helpers.patch_context(foo, []), foo)
63 |
64 | self.assertEqual(
65 | helpers.patch_context(foo, [cp1]), helpers.merge_dicts(foo, bar)
66 | )
67 |
68 | self.assertEqual(
69 | helpers.patch_context(foo, [cp1, cp2]), helpers.merge_dicts(foo, bar, baz)
70 | )
71 |
--------------------------------------------------------------------------------
/tests/settings.py:
--------------------------------------------------------------------------------
1 | import os
2 |
3 | from django.core.exceptions import ImproperlyConfigured
4 |
5 | DEBUG = True
6 |
7 | USE_TZ = False
8 |
9 | DATABASES = {
10 | "default": {
11 | "ENGINE": "django.db.backends.sqlite3",
12 | "NAME": "test.db",
13 | }
14 | }
15 |
16 | INSTALLED_APPS = (
17 | "django.contrib.admin",
18 | "django.contrib.auth",
19 | "django.contrib.contenttypes",
20 | "django.contrib.sessions",
21 | "django.contrib.messages",
22 | "django.contrib.staticfiles",
23 | "appmail",
24 | "tests",
25 | )
26 |
27 | MIDDLEWARE = [
28 | "django.contrib.sessions.middleware.SessionMiddleware",
29 | "django.middleware.common.CommonMiddleware",
30 | "django.middleware.csrf.CsrfViewMiddleware",
31 | "django.contrib.auth.middleware.AuthenticationMiddleware",
32 | "django.contrib.messages.middleware.MessageMiddleware",
33 | ]
34 |
35 | TEMPLATES = [
36 | {
37 | "BACKEND": "django.template.backends.django.DjangoTemplates",
38 | "DIRS": [
39 | # insert your TEMPLATE_DIRS here
40 | ],
41 | "APP_DIRS": True,
42 | "OPTIONS": {
43 | "context_processors": [
44 | # Insert your TEMPLATE_CONTEXT_PROCESSORS here or use this
45 | # list if you haven't customized them:
46 | "django.contrib.auth.context_processors.auth",
47 | "django.template.context_processors.debug",
48 | "django.template.context_processors.i18n",
49 | "django.template.context_processors.media",
50 | "django.template.context_processors.request",
51 | "django.template.context_processors.static",
52 | "django.template.context_processors.tz",
53 | "django.contrib.messages.context_processors.messages",
54 | ]
55 | },
56 | }
57 | ]
58 |
59 | EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
60 |
61 | # Update storage settings to use the new STORAGES format
62 | STORAGES = {
63 | "default": {
64 | "BACKEND": "django.core.files.storage.FileSystemStorage",
65 | },
66 | "staticfiles": {
67 | "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
68 | },
69 | }
70 |
71 | STATIC_URL = "/static/"
72 | STATIC_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "static"))
73 |
74 | SECRET_KEY = "top secret" # noqa: S105
75 |
76 | ROOT_URLCONF = "tests.urls"
77 |
78 | APPEND_SLASH = True
79 |
80 | if not DEBUG:
81 | raise ImproperlyConfigured("This project is only intended to be used for testing.")
82 |
83 | # ===
84 |
85 | APPMAIL_DEFAULT_SENDER = "test@example.com"
86 |
--------------------------------------------------------------------------------
/appmail/helpers.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 |
3 | import re
4 | from typing import Callable, Iterable
5 |
6 | from django.http import HttpRequest
7 |
8 | # regex for extracting django template {{ variable }}s
9 | TEMPLATE_VARS = re.compile(r"{{([ ._[a-z]*)}}")
10 |
11 |
12 | def get_context(content: str) -> dict:
13 | """
14 | Return a dummary context dict for a content block.
15 |
16 | This function works by taking template content,
17 | extracting the template variables ({{ foo.bar }}),
18 | expanding out the list of variables into a dict
19 | using the '.' separator, and then populating the
20 | value of each leaf node with the node key ('foo': "FOO").
21 |
22 | Used for generating test data.
23 |
24 | """
25 | return fill_leaf_values(expand_list(extract_vars(content)))
26 |
27 |
28 | def extract_vars(content: str) -> list[str]:
29 | """
30 | Extract variables from template content.
31 |
32 | Returns a deduplicated list of all the variable names
33 | found in the content.
34 |
35 | """
36 | content = content or ""
37 | # if I was better at regex I wouldn't need the strip.
38 | return list({s.strip() for s in TEMPLATE_VARS.findall(content)})
39 |
40 |
41 | def expand_list(_list: list[str]) -> dict:
42 | """
43 | Convert list of '.' separated values to a nested dict.
44 |
45 | Taken from SO article which I now can't find, this will take a list
46 | and return a dictionary which contains an empty dict as each leaf
47 | node.
48 |
49 | >>> expand_list(['a', 'b.c'])
50 | {
51 | 'a': {},
52 | 'b': {
53 | 'c': {}
54 | }
55 | }
56 |
57 | """
58 | if not isinstance(_list, list):
59 | raise ValueError("arg must be a list")
60 | tree = {} # type: dict[str, dict]
61 | for item in _list:
62 | t = tree
63 | for part in item.split("."):
64 | t = t.setdefault(part, {})
65 | return tree
66 |
67 |
68 | def fill_leaf_values(tree: dict) -> dict:
69 | """
70 | Recursive function that populates empty dict leaf nodes.
71 |
72 | This function will look for all the leaf nodes in a dictionary
73 | and replace them with a value that looks like the variable
74 | in the template - e.g. {{ foo }}.
75 |
76 | >>> fill_leaf_values({'a': {}, 'b': 'c': {}})
77 | {
78 | 'a': '{{ A }}',
79 | 'b': {
80 | 'c': '{{ C }}'
81 | }
82 | }
83 |
84 | """
85 | if not isinstance(tree, dict):
86 | raise ValueError("arg must be a dictionary")
87 | for k in tree.keys():
88 | if tree[k] == {}:
89 | tree[k] = k.upper()
90 | else:
91 | fill_leaf_values(tree[k])
92 | return tree
93 |
94 |
95 | def merge_dicts(*dicts: dict) -> dict:
96 | """Merge multiple dicts into one."""
97 | context = {}
98 | for d in dicts:
99 | context.update(d)
100 | return context
101 |
102 |
103 | def patch_context(
104 | context: dict,
105 | processors: Iterable[Callable[[HttpRequest], dict]],
106 | request: HttpRequest | None = None,
107 | ) -> dict:
108 | """Add template context_processor content to context."""
109 | cpx = [p(request) for p in processors]
110 | return merge_dicts(context, *cpx)
111 |
--------------------------------------------------------------------------------
/appmail/migrations/0001_initial.py:
--------------------------------------------------------------------------------
1 | # -*- coding: utf-8 -*-
2 | # Generated by Django 1.10 on 2017-03-11 11:36
3 | from __future__ import unicode_literals
4 |
5 | from django.db import migrations, models
6 |
7 |
8 | class Migration(migrations.Migration):
9 | initial = True
10 |
11 | dependencies = []
12 |
13 | operations = [
14 | migrations.CreateModel(
15 | name="EmailTemplate",
16 | fields=[
17 | (
18 | "id",
19 | models.AutoField(
20 | auto_created=True,
21 | primary_key=True,
22 | serialize=False,
23 | verbose_name="ID",
24 | ),
25 | ),
26 | (
27 | "name",
28 | models.CharField(
29 | db_index=True,
30 | help_text=(
31 | "Template name - must be unique for a given language/"
32 | "version combination."
33 | ),
34 | max_length=100,
35 | verbose_name="Template name",
36 | ),
37 | ),
38 | (
39 | "language",
40 | models.CharField(
41 | db_index=True,
42 | default="en-us",
43 | help_text=(
44 | "Used to support localisation of emails, defaults to "
45 | "settings.LANGUAGE_CODE."
46 | ),
47 | max_length=20,
48 | verbose_name="Language code",
49 | ),
50 | ),
51 | (
52 | "version",
53 | models.IntegerField(
54 | db_index=True,
55 | default=0,
56 | help_text=(
57 | "Integer value - can be used for versioning or A/B testing."
58 | ),
59 | verbose_name="Version (or variant)",
60 | ),
61 | ),
62 | (
63 | "subject",
64 | models.CharField(
65 | help_text=(
66 | "Email subject line (may contain template variables)."
67 | ),
68 | max_length=100,
69 | verbose_name="Subject line template",
70 | ),
71 | ),
72 | (
73 | "body_text",
74 | models.TextField(
75 | help_text=(
76 | "Plain text content (may contain template variables)."
77 | ),
78 | verbose_name="Plain text template",
79 | ),
80 | ),
81 | (
82 | "body_html",
83 | models.TextField(
84 | help_text="HTML content (may contain template variables).",
85 | verbose_name="HTML template",
86 | ),
87 | ),
88 | ],
89 | ),
90 | migrations.AlterUniqueTogether(
91 | name="emailtemplate", unique_together={("name", "language", "version")}
92 | ),
93 | ]
94 |
--------------------------------------------------------------------------------
/appmail/migrations/0007_loggedemailmessage.py:
--------------------------------------------------------------------------------
1 | # Generated by Django 3.1.5 on 2021-01-04 06:48
2 |
3 | import django.core.serializers.json
4 | import django.db.models.deletion
5 | import django.utils.timezone
6 | from django.conf import settings
7 | from django.db import migrations, models
8 |
9 |
10 | class Migration(migrations.Migration):
11 | dependencies = [
12 | migrations.swappable_dependency(settings.AUTH_USER_MODEL),
13 | ("appmail", "0006_emailtemplate_supports_attachments"),
14 | ]
15 |
16 | operations = [
17 | migrations.CreateModel(
18 | name="LoggedMessage",
19 | fields=[
20 | (
21 | "id",
22 | models.AutoField(
23 | auto_created=True,
24 | primary_key=True,
25 | serialize=False,
26 | verbose_name="ID",
27 | ),
28 | ),
29 | (
30 | "to",
31 | models.EmailField(
32 | help_text="Address to which the the Email was sent.",
33 | max_length=254,
34 | ),
35 | ),
36 | (
37 | "timestamp",
38 | models.DateTimeField(
39 | default=django.utils.timezone.now,
40 | help_text="When the email was sent.",
41 | db_index=True,
42 | ),
43 | ),
44 | (
45 | "subject",
46 | models.TextField(blank=True, help_text="Email subject line."),
47 | ),
48 | (
49 | "body",
50 | models.TextField(
51 | blank=True,
52 | help_text="Plain text content.",
53 | verbose_name="Plain text",
54 | ),
55 | ),
56 | (
57 | "html",
58 | models.TextField(
59 | blank=True, help_text="HTML content.", verbose_name="HTML"
60 | ),
61 | ),
62 | (
63 | "context",
64 | models.JSONField(
65 | default=dict,
66 | encoder=django.core.serializers.json.DjangoJSONEncoder,
67 | help_text="Appmail template context.",
68 | ),
69 | ),
70 | (
71 | "template",
72 | models.ForeignKey(
73 | blank=True,
74 | help_text="The appmail template used.",
75 | null=True,
76 | on_delete=django.db.models.deletion.SET_NULL,
77 | related_name="logged_emails",
78 | to="appmail.emailtemplate",
79 | ),
80 | ),
81 | (
82 | "user",
83 | models.ForeignKey(
84 | blank=True,
85 | null=True,
86 | on_delete=django.db.models.deletion.SET_NULL,
87 | related_name="logged_emails",
88 | to=settings.AUTH_USER_MODEL,
89 | ),
90 | ),
91 | ],
92 | options={
93 | "get_latest_by": "timestamp",
94 | "verbose_name": "Email message",
95 | "verbose_name_plural": "Email messages sent",
96 | },
97 | ),
98 | ]
99 |
--------------------------------------------------------------------------------
/tests/test_forms.py:
--------------------------------------------------------------------------------
1 | # type: ignore
2 | from unittest import mock
3 |
4 | from django.core.exceptions import ValidationError
5 | from django.forms import Textarea
6 | from django.http import HttpRequest
7 | from django.test import TestCase
8 |
9 | from appmail.forms import (
10 | EmailTestForm,
11 | JSONWidget,
12 | MultiEmailField,
13 | MultiEmailTemplateField,
14 | )
15 | from appmail.models import AppmailMessage, EmailTemplate
16 |
17 |
18 | class JSONWidgetTests(TestCase):
19 | def test_format_value(self):
20 | widget = JSONWidget()
21 | self.assertEqual(widget.format_value(None), "{}")
22 | self.assertEqual(widget.format_value(""), "{}")
23 | self.assertEqual(widget.format_value('{"foo": true}'), '{\n "foo": true\n}')
24 | self.assertRaises(TypeError, widget.format_value, {"foo": True})
25 |
26 | def test_render(self):
27 | widget = JSONWidget()
28 | textarea = Textarea()
29 | for val in [None, "", '{"foo": true}']:
30 | self.assertEqual(
31 | widget.render("test", val),
32 | textarea.render(
33 | "test", widget.format_value(val), attrs=widget.DEFAULT_ATTRS
34 | ),
35 | )
36 |
37 |
38 | class MultiEmailFieldTests(TestCase):
39 | def test_to_python(self):
40 | form = MultiEmailField()
41 | self.assertEqual(form.to_python(None), [])
42 | self.assertEqual(form.to_python(""), [])
43 | self.assertEqual(form.to_python("fred@example.com"), ["fred@example.com"])
44 | self.assertEqual(
45 | form.to_python("fred@example.com , ginger@example.com"),
46 | ["fred@example.com", "ginger@example.com"],
47 | )
48 | self.assertEqual(form.to_python(["fred@example.com"]), ["fred@example.com"])
49 |
50 | def test_validate(self):
51 | form = MultiEmailField()
52 | form.validate(["fred@example.com"])
53 | form.validate(form.to_python("fred@example.com, ginger@example.com"))
54 | # single email address fails validation - must be a list
55 | self.assertRaises(ValidationError, form.validate, "fred@example.com")
56 |
57 |
58 | class MultiEmailTemplateFieldTests(TestCase):
59 | @mock.patch.object(EmailTemplate.objects, "filter")
60 | def test_to_python(self, mock_filter):
61 | form = MultiEmailTemplateField()
62 | self.assertEqual(list(form.to_python(None)), list(EmailTemplate.objects.none()))
63 | self.assertEqual(list(form.to_python("")), list(EmailTemplate.objects.none()))
64 | qs = EmailTemplate.objects.none()
65 | self.assertEqual(form.to_python(qs), qs)
66 | form.to_python("1, 2")
67 | mock_filter.assert_called_once_with(pk__in=[1, 2])
68 |
69 |
70 | class EmailTestFormTests(TestCase):
71 | def test_clean_context(self):
72 | form = EmailTestForm()
73 | form.cleaned_data = {"context": "true"}
74 | self.assertEqual(form.clean_context(), True)
75 | form.cleaned_data["context"] = True
76 | self.assertRaises(ValidationError, form.clean_context)
77 |
78 | def test__create_message(self):
79 | form = EmailTestForm()
80 | form.cleaned_data = {
81 | "context": {"foo": "bar"},
82 | "to": ["fred@example.com"],
83 | "cc": [],
84 | "bcc": [],
85 | "from_email": "donotreply@example.com",
86 | }
87 | template = EmailTemplate()
88 | email = form._create_message(template)
89 | self.assertEqual(email.from_email, "donotreply@example.com")
90 | self.assertEqual(email.to, ["fred@example.com"])
91 | self.assertEqual(email.cc, [])
92 | self.assertEqual(email.bcc, [])
93 |
94 | @mock.patch("appmail.forms.messages")
95 | @mock.patch.object(AppmailMessage, "send")
96 | def test_send_emails(self, mock_send, mock_messages):
97 | template = EmailTemplate().save()
98 | form = EmailTestForm()
99 | form.cleaned_data = {
100 | "context": {"foo": "bar"},
101 | "to": ["fred@example.com"],
102 | "cc": [],
103 | "bcc": [],
104 | "from_email": "donotreply@example.com",
105 | "templates": [template],
106 | }
107 | request = HttpRequest()
108 | form.send_emails(request)
109 | mock_send.assert_called_once()
110 | mock_messages.success.assert_called_once()
111 |
112 | # test email failure
113 | mock_send.side_effect = Exception()
114 | form.send_emails(request)
115 | mock_messages.error.assert_called_once()
116 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Django-AppMail
2 |
3 | [](https://pypi.org/project/django-appmail/)
4 |
5 | Django app for managing transactional email templates.
6 |
7 | ## Compatibility
8 |
9 | This project requires Django 4.2+ and Python 3.9+.
10 |
11 | ## Background
12 |
13 | This project arose out of a project to integrate a large transactional Django
14 | application with Mandrill, and the lessons learned. It also owes a minor h/t to
15 | this project from 2011 (https://github.com/hugorodgerbrown/AppMail).
16 |
17 | The core requirement is to provide an easy way to add / edit email templates to
18 | a Django project, in such a way that it doesn't require a developer to make
19 | changes. The easiest way to use templated emails in Django is to rely on the
20 | in-built template structure, but that means that the templates are held in
21 | files, under version control, which makes it very hard for non-developers to
22 | edit.
23 |
24 | This is **not** a WYSIWYG HTML editor, and it doesn't do anything clever. It
25 | doesn't handle the sending of the emails - it simply provides a convenient
26 | mechanism for storing and rendering email content.
27 |
28 | ```python
29 | from appmail.models import EmailTemplate, AppmailMessage
30 |
31 | def send_order_confirmation(order_id):
32 | order = Orders.objects.get(id=order_id)
33 | template = EmailTemplate.objects.current('order_confirmation')
34 | context = { "order": order }
35 | message = AppmailMessage(
36 | template=template,
37 | context=context,
38 | to=[order.recipient.email]
39 | )
40 | message.send()
41 | ```
42 |
43 | The core requirements are:
44 |
45 | 1. List / preview existing templates
46 | 2. Edit subject line, plain text and HTML content
47 | 3. Use standard Django template syntax
48 | 4. Support base templates
49 | 5. Template versioning
50 | 6. Language support
51 | 7. Send test emails
52 | 8. Log emails sent (if desired)
53 |
54 | ### Email logging (v2)
55 |
56 | From v2 on, it is possible to log all emails that are sent via
57 | `AppmailMessage.send`. It records the template, context and the rendered output,
58 | so that the email can be views as sent, and resent. It will attempt to record
59 | the User to whom the email was sent, as well as the email address. This is
60 | dependent on there being a unique 1:1 match from email to User object, but can
61 | prove useful in tracking emails sent to users when they change their email
62 | address.
63 |
64 | ### Template properties
65 |
66 | Individual templates are stored as model objects in the database. The standard
67 | Django admin site is used to view / filter templates. The templates are ordered
68 | by name, language and version. This combination is unique. The language and
69 | version properties have sensible defaults (`version=settings.LANGUAGE_CODE` and
70 | `version=0`) so don't need to set if you don't require it. There is no
71 | inheritance or relationship between different languages and versions - they are
72 | stored as independent objects.
73 |
74 | ```python
75 | # get the default order_summary email (language = settings.LANGUAGE_CODE)
76 | template = EmailTemplate.objects.current('order_summary')
77 | # get the french version
78 | template = EmailTemplate.objects.current('order_summary', language='fr')
79 | # get a specific version
80 | template = EmailTemplate.objects.version('order_summary', 1)
81 | ```
82 |
83 | **Template syntax**
84 |
85 | The templates themselves use standard Django template syntax, including the use
86 | of tags, filters. There is nothing special about them, however there is one
87 | caveat - template inheritance.
88 |
89 | **Template inheritance**
90 |
91 | Although the template content is not stored on disk, without re-engineering the
92 | template rendering methods any parent templates must be. This is annoying, but
93 | there is a valid assumption behind it - if you are changing your base templates
94 | you are probably involving designers and developers already, so having to rely
95 | on a developer to make the changes is acceptable.
96 |
97 | **Sending test emails**
98 |
99 | You can send test emails to an email address through the admin list view.
100 |
101 | Test attributes
27 | 47 |
103 |
104 | The custom admin action 'Send test emails' will redirect to an intermediate page
105 | where you can enter the recipient email address and send the email:
106 |
107 | 
108 |
109 | There is also a linkon individual template admin pages (top-right, next to the
110 | history link):
111 |
112 | 
114 |
115 | ## Tests
116 |
117 | There is a test suite for the app, which is best run through `tox`.
118 |
119 | ## License
120 |
121 | MIT
122 |
123 | ## Contributing
124 |
125 | Usual rules apply:
126 |
127 | 1. Fork to your own account
128 | 2. Fix the issue / add the feature
129 | 3. Submit PR
130 |
131 | Please take care to follow the coding style - and PEP8.
132 |
--------------------------------------------------------------------------------
/appmail/views.py:
--------------------------------------------------------------------------------
1 | """Views supporting template previews in admin site."""
2 |
3 | from __future__ import annotations
4 |
5 | import json
6 | import logging
7 |
8 | from django.conf import settings as django_settings
9 | from django.contrib import messages
10 | from django.contrib.auth.decorators import user_passes_test
11 | from django.http import HttpRequest, HttpResponse, HttpResponseRedirect
12 | from django.http.response import HttpResponseBadRequest
13 | from django.shortcuts import get_object_or_404, render
14 | from django.urls import reverse
15 | from django.utils.translation import gettext as _
16 | from django.views.decorators.clickjacking import xframe_options_sameorigin
17 |
18 | from .forms import EmailTestForm, MultiEmailTemplateField
19 | from .helpers import merge_dicts
20 | from .models import EmailTemplate, LoggedMessage
21 |
22 | logger = logging.getLogger(__name__)
23 |
24 |
25 | @user_passes_test(lambda u: u.is_staff)
26 | @xframe_options_sameorigin
27 | def render_template_subject(request: HttpRequest, template_id: int) -> HttpResponse:
28 | """Render the template subject."""
29 | template = get_object_or_404(EmailTemplate, id=template_id)
30 | html = template.render_subject(template.test_context)
31 | return HttpResponse(html, content_type="text/plain")
32 |
33 |
34 | @user_passes_test(lambda u: u.is_staff)
35 | @xframe_options_sameorigin
36 | def render_template_body(
37 | request: HttpRequest, template_id: int, content_type: str
38 | ) -> HttpResponse:
39 | """Render the template body as plain text or HTML."""
40 | template = get_object_or_404(EmailTemplate, id=template_id)
41 | if content_type in (
42 | EmailTemplate.CONTENT_TYPE_PLAIN,
43 | EmailTemplate.CONTENT_TYPE_HTML,
44 | ):
45 | html = template.render_body(template.test_context, content_type)
46 | return HttpResponse(html, content_type=content_type)
47 | # do not return the content_type to the user, as it is
48 | # user-generated and _could_ be a vulnerability.
49 | return HttpResponse("Invalid content_type specified.", status=400)
50 |
51 |
52 | @user_passes_test(lambda u: u.is_staff)
53 | def send_test_email(request: HttpRequest) -> HttpResponseRedirect:
54 | """Intermediate admin action page for sending a single test email."""
55 | # use the field.to_python here as belt-and-braces - if it works here
56 | # we can be confident that it'll work on the POST.
57 | templates = MultiEmailTemplateField().to_python(request.GET["templates"])
58 |
59 | if request.method == "GET":
60 | contexts = merge_dicts(*[t.test_context for t in templates])
61 | context = json.dumps(contexts, indent=4, sort_keys=True)
62 | initial = {"templates": request.GET["templates"], "context": context}
63 | try:
64 | template = templates.get()
65 | initial["from_email"] = template.from_email
66 | initial["reply_to"] = template.reply_to
67 | except EmailTemplate.MultipleObjectsReturned:
68 | initial["from_email"] = django_settings.DEFAULT_FROM_EMAIL
69 | initial["reply_to"] = django_settings.DEFAULT_FROM_EMAIL
70 | form = EmailTestForm(initial=initial)
71 | return render(
72 | request,
73 | "appmail/send_test_email.html",
74 | {
75 | "form": form,
76 | "templates": templates,
77 | # opts are used for rendering some page furniture - breadcrumbs etc.
78 | "opts": EmailTemplate._meta,
79 | },
80 | )
81 |
82 | if request.method == "POST":
83 | form = EmailTestForm(request.POST)
84 | if form.is_valid():
85 | form.send_emails(request)
86 | return HttpResponseRedirect(
87 | "{}?{}".format(
88 | reverse("appmail:send_test_email"), request.GET.urlencode()
89 | )
90 | )
91 | else:
92 | return render(
93 | request,
94 | "appmail/send_test_email.html",
95 | {
96 | "form": form,
97 | "templates": templates,
98 | # opts are used for rendering some page furniture - breadcrumbs etc.
99 | "opts": EmailTemplate._meta,
100 | },
101 | status=422,
102 | )
103 |
104 |
105 | @user_passes_test(lambda u: u.is_staff)
106 | def resend_email(request: HttpRequest, email_id: int) -> HttpResponseRedirect:
107 | """Resend a specific LoggedMessage."""
108 | email = LoggedMessage.objects.get(id=email_id)
109 | email.resend()
110 | messages.success(request, _("Resent email to {}".format(email.to)))
111 | return HttpResponseRedirect(reverse("admin:appmail_loggedmessage_changelist"))
112 |
113 |
114 | @user_passes_test(lambda u: u.is_staff)
115 | @xframe_options_sameorigin
116 | def render_message_body(
117 | request: HttpRequest, email_id: int, content_type: str
118 | ) -> HttpResponse:
119 | """Render the email body as plain text or HTML."""
120 | email = get_object_or_404(LoggedMessage, id=email_id)
121 | if content_type == EmailTemplate.CONTENT_TYPE_PLAIN:
122 | return HttpResponse(email.body, content_type=content_type)
123 | if content_type == EmailTemplate.CONTENT_TYPE_HTML:
124 | return HttpResponse(email.html, content_type=content_type)
125 | return HttpResponseBadRequest("Invalid content_type specified.")
126 |
--------------------------------------------------------------------------------
/appmail/forms.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 |
3 | import json
4 | import logging
5 | from typing import TYPE_CHECKING
6 |
7 | from django import forms
8 | from django.contrib import messages
9 | from django.core.validators import validate_email
10 | from django.http import HttpRequest
11 | from django.utils.translation import gettext_lazy as _lazy
12 |
13 | from .models import AppmailMessage, EmailTemplate, EmailTemplateQuerySet
14 |
15 | if TYPE_CHECKING:
16 | from typing import Union
17 |
18 |
19 | logger = logging.getLogger(__name__)
20 |
21 |
22 | class JSONWidget(forms.Textarea):
23 | """Pretty print JSON in a text area."""
24 |
25 | DEFAULT_ATTRS: dict[str, Union[str, int]] = {
26 | "class": "vLargeTextField",
27 | "rows": 15,
28 | }
29 |
30 | def format_value(self, value: str) -> str:
31 | """Pretty format JSON text."""
32 | value = value or "{}"
33 | if not isinstance(value, str):
34 | raise TypeError("Value must JSON parseable string instance")
35 | value = json.loads(value)
36 | return json.dumps(value, indent=4, sort_keys=True)
37 |
38 | def render(
39 | self,
40 | name: str,
41 | value: str,
42 | attrs: dict[str, str | int] | None = None,
43 | renderer: forms.renderers.BaseRenderer | None = None,
44 | ) -> str:
45 | attrs = attrs or JSONWidget.DEFAULT_ATTRS
46 | value = self.format_value(value)
47 | return super().render(name, value, attrs=attrs, renderer=renderer)
48 |
49 |
50 | class MultiEmailField(forms.Field):
51 | """Taken from https://docs.djangoproject.com/en/1.11/ref/forms/validation/#form-field-default-cleaning""" # noqa
52 |
53 | def to_python(self, value: list[str] | str | None) -> list[str]:
54 | """Normalize data to a list of strings."""
55 | if isinstance(value, list):
56 | return value
57 |
58 | if not value:
59 | return []
60 |
61 | return [v.strip() for v in value.split(",")]
62 |
63 | def validate(self, value: list[str]) -> None:
64 | """Check if value consists only of valid emails."""
65 | # Use the parent's handling of required fields, etc.
66 | super().validate(value)
67 | for email in value:
68 | validate_email(email)
69 |
70 |
71 | class MultiEmailTemplateField(forms.Field):
72 | """Convert comma-separated ids into EmailTemplate queryset."""
73 |
74 | def to_python(
75 | self, value: EmailTemplateQuerySet | str | None
76 | ) -> EmailTemplateQuerySet:
77 | """Normalize data to a queryset of EmailTemplates."""
78 | if isinstance(value, EmailTemplateQuerySet):
79 | return value
80 |
81 | if not value:
82 | return EmailTemplate.objects.none()
83 |
84 | values = [int(i) for i in value.split(",")]
85 | return EmailTemplate.objects.filter(pk__in=values)
86 |
87 |
88 | class EmailTestForm(forms.Form):
89 | """Renders email template on intermediate page."""
90 |
91 | from_email = forms.EmailField(
92 | label=_lazy("From"), help_text=_lazy("Email address to be used as the sender")
93 | )
94 | reply_to = MultiEmailField(
95 | label=_lazy("Reply-To"),
96 | help_text=_lazy("Comma separated list of email addresses"),
97 | )
98 | to = MultiEmailField(
99 | label=_lazy("To"), help_text=_lazy("Comma separated list of email addresses")
100 | )
101 | cc = MultiEmailField(
102 | label=_lazy("cc"),
103 | help_text=_lazy("Comma separated list of email addresses"),
104 | required=False,
105 | )
106 | bcc = MultiEmailField(
107 | label=_lazy("bcc"),
108 | help_text=_lazy("Comma separated list of email addresses"),
109 | required=False,
110 | )
111 | context = forms.CharField(
112 | widget=forms.Textarea,
113 | required=False,
114 | help_text=_lazy("JSON used to render the subject and body templates"),
115 | )
116 | # comma separated list of template ids.
117 | templates = MultiEmailTemplateField(widget=forms.HiddenInput())
118 |
119 | def clean_context(self) -> dict:
120 | """Load text input back into JSON."""
121 | context = self.cleaned_data["context"] or "{}"
122 | try:
123 | return json.loads(context)
124 | except (TypeError, ValueError) as ex:
125 | raise forms.ValidationError(_lazy("Invalid JSON: %s" % ex))
126 |
127 | def _create_message(self, template: EmailTemplate) -> AppmailMessage:
128 | """Create EmailMultiMessage from form data."""
129 | return AppmailMessage(
130 | template,
131 | self.cleaned_data["context"],
132 | from_email=self.cleaned_data["from_email"],
133 | to=self.cleaned_data["to"],
134 | cc=self.cleaned_data["cc"],
135 | bcc=self.cleaned_data["bcc"],
136 | )
137 |
138 | def send_emails(self, request: HttpRequest) -> None:
139 | """Send test emails."""
140 | for template in self.cleaned_data.get("templates"):
141 | email = self._create_message(template)
142 | try:
143 | email.send()
144 | except Exception as ex: # noqa: B902
145 | logger.exception("Error sending test email")
146 | messages.error(
147 | request,
148 | _lazy(
149 | "Error sending test email '{}': {}".format(template.name, ex)
150 | ),
151 | )
152 | else:
153 | messages.success(
154 | request,
155 | _lazy(
156 | "'{}' email sent to '{}'".format(
157 | template.name, ", ".join(email.to)
158 | )
159 | ),
160 | )
161 |
--------------------------------------------------------------------------------
/tests/test_views.py:
--------------------------------------------------------------------------------
1 | from unittest import mock
2 |
3 | from django.contrib.auth.models import AnonymousUser, User
4 | from django.test import RequestFactory, TestCase
5 | from django.urls import reverse
6 |
7 | from appmail import views
8 | from appmail.forms import EmailTestForm
9 | from appmail.models import EmailTemplate
10 |
11 |
12 | class ViewTests(TestCase):
13 | def setUp(self):
14 | # Every test needs access to the request factory.
15 | self.factory = RequestFactory()
16 | self.template = EmailTemplate(
17 | subject="ßello, {{user.first_name}}",
18 | body_text="ßello,\n{{user.first_name}}",
19 | body_html="ßello, {{user.first_name}}",
20 | ).save()
21 | self.subject_url = reverse(
22 | "appmail:render_template_subject", kwargs={"template_id": self.template.id}
23 | )
24 | self.body_text_url = reverse(
25 | "appmail:render_template_body_text",
26 | kwargs={"template_id": self.template.id},
27 | )
28 | self.body_html_url = reverse(
29 | "appmail:render_template_body_html",
30 | kwargs={"template_id": self.template.id},
31 | )
32 |
33 | def test_render_template_subject(self):
34 | template = self.template
35 | request = self.factory.get(self.subject_url)
36 | # check that non-staff are denied
37 | request.user = AnonymousUser()
38 | response = views.render_template_subject(request, template.id)
39 | self.assertEqual(response.status_code, 302)
40 | # non-staff user
41 | request.user = User()
42 | response = views.render_template_subject(request, template.id)
43 | self.assertEqual(response.status_code, 302)
44 | # staff user
45 | request.user.is_staff = True
46 | response = views.render_template_subject(request, template.id)
47 | self.assertEqual(response.status_code, 200)
48 | # should render the template with the dummy context
49 | self.assertEqual(
50 | response.content.decode("utf-8"),
51 | template.render_subject(template.test_context),
52 | )
53 |
54 | def test_render_template_body(self):
55 | template = self.template
56 | request = self.factory.get(self.body_text_url)
57 | # check that non-staff are denied
58 | request.user = AnonymousUser()
59 | response = views.render_template_body(
60 | request, template.id, EmailTemplate.CONTENT_TYPE_PLAIN
61 | )
62 | self.assertEqual(response.status_code, 302)
63 | # non-staff user
64 | request.user = User()
65 | response = views.render_template_body(
66 | request, template.id, EmailTemplate.CONTENT_TYPE_PLAIN
67 | )
68 | self.assertEqual(response.status_code, 302)
69 | # staff user
70 | request.user.is_staff = True
71 | response = views.render_template_body(
72 | request, template.id, EmailTemplate.CONTENT_TYPE_PLAIN
73 | )
74 | self.assertEqual(response.status_code, 200)
75 | # should render the template with the dummy context
76 | self.assertEqual(
77 | response.content.decode("utf-8"),
78 | template.render_body(
79 | template.test_context, EmailTemplate.CONTENT_TYPE_PLAIN
80 | ),
81 | )
82 | # now check the HTML version
83 | response = views.render_template_body(
84 | request, template.id, EmailTemplate.CONTENT_TYPE_HTML
85 | )
86 | self.assertEqual(
87 | response.content.decode("utf-8"),
88 | template.render_body(
89 | template.test_context, EmailTemplate.CONTENT_TYPE_HTML
90 | ),
91 | )
92 |
93 | # now check the HTML version
94 | response = views.render_template_body(request, template.id, "foo")
95 | self.assertEqual(response.status_code, 400)
96 | self.assertEqual(
97 | response.content.decode("utf-8"), "Invalid content_type specified."
98 | )
99 |
100 | def test_send_test_emails_GET(self):
101 | user = User.objects.create( # noqa: S106, E501
102 | username="admin", password="password", is_staff=True
103 | )
104 | template = self.template
105 | url = "{}?templates={}".format(reverse("appmail:send_test_email"), template.pk)
106 | response = self.client.get(url)
107 | self.assertEqual(response.status_code, 302)
108 | self.client.force_login(user)
109 | response = self.client.get(url)
110 | self.assertEqual(response.status_code, 200)
111 | self.assertContains(response, template.name)
112 |
113 | @mock.patch.object(EmailTestForm, "send_emails")
114 | def test_send_test_emails_POST(self, mock_send):
115 | user = User.objects.create( # noqa: S106, E501
116 | username="admin", password="password", is_staff=True
117 | )
118 | template = self.template
119 | url = "{}?templates={}".format(reverse("appmail:send_test_email"), template.pk)
120 | self.client.force_login(user)
121 | payload = {
122 | "to": "fred@example.com",
123 | "cc": "",
124 | "bcc": "",
125 | "context": "",
126 | "from_email": "donotreply@example.com",
127 | "reply_to": ["donotreply1@example.com"],
128 | "templates": template.pk,
129 | }
130 | response = self.client.post(url, payload)
131 | self.assertEqual(mock_send.call_count, 1)
132 | mock_send.assert_called_once_with(response.wsgi_request)
133 | self.assertEqual(response.status_code, 302)
134 |
135 | # check that bad response returns 422
136 | response = self.client.post(url, {})
137 | self.assertEqual(mock_send.call_count, 1)
138 | self.assertEqual(response.status_code, 422)
139 |
--------------------------------------------------------------------------------
/appmail/admin.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 |
3 | import json
4 |
5 | from django.contrib import admin, messages
6 | from django.core.exceptions import ValidationError
7 | from django.db.models import JSONField
8 | from django.db.models.query import QuerySet
9 | from django.http import HttpRequest, HttpResponseRedirect
10 | from django.template.defaultfilters import truncatechars
11 | from django.urls import reverse
12 | from django.utils.html import format_html
13 | from django.utils.safestring import mark_safe
14 | from django.utils.translation import gettext_lazy as _lazy
15 |
16 | from .forms import JSONWidget
17 | from .models import EmailTemplate, LoggedMessage
18 |
19 |
20 | class ValidTemplateListFilter(admin.SimpleListFilter):
21 | """Filter on whether the template can be rendered or not."""
22 |
23 | title = _lazy("Is valid")
24 | parameter_name = "valid"
25 |
26 | def lookups(
27 | self, request: HttpRequest, model_admin: admin.ModelAdmin
28 | ) -> tuple[tuple[str, str], tuple[str, str]]:
29 | """
30 | Return valid template True/False filter values tuples.
31 |
32 | The first element in each tuple is the coded value for the option
33 | that will appear in the URL query. The second element is the
34 | human-readable name for the option that will appear
35 | in the right sidebar.
36 |
37 | """
38 | return (("1", _lazy("True")), ("0", _lazy("False")))
39 |
40 | def queryset(self, request: HttpRequest, queryset: QuerySet) -> QuerySet:
41 | """
42 | Return the filtered queryset.
43 |
44 | Filter based on the value provided in the query string and
45 | retrievable via `self.value()`.
46 |
47 | """
48 | valid_ids = []
49 | invalid_ids = []
50 |
51 | if not self.value():
52 | # By default, the lookup is not run at all because it is
53 | # computationally expensive to render the entire list of
54 | # emails on every page load.
55 | return
56 |
57 | for obj in queryset:
58 | try:
59 | obj.clean()
60 | valid_ids.append(obj.pk)
61 | except ValidationError:
62 | invalid_ids.append(obj.pk)
63 |
64 | if self.value() == "1":
65 | return queryset.filter(pk__in=valid_ids)
66 | if self.value() == "0":
67 | return queryset.filter(pk__in=invalid_ids)
68 |
69 |
70 | class AdminBase(admin.ModelAdmin):
71 | def iframe(self, url: str) -> str:
72 | """Return an iframe containing the url for display in change view."""
73 | return format_html(
74 | f""
75 | f"View in new tab." 76 | ) 77 | 78 | def pretty_print(self, data: dict | None) -> str: 79 | """Convert dict into formatted HTML.""" 80 | if data is None: 81 | return "(None)" 82 | pretty = json.dumps(data, sort_keys=True, indent=4, separators=(",", ": ")) 83 | html = pretty.replace(" ", " ").replace("\n", "
") 84 | return mark_safe("
%sHello {{ first_name }}
", 28 | ) 29 | context = {"first_name": "fr¡da"} 30 | return AppmailMessage(template, context, to=["fred@example.com"]) 31 | 32 | 33 | class EmailTemplateQuerySetTests(TestCase): 34 | def test_active(self): 35 | template1 = EmailTemplate(name="test1", language="en-us").save() 36 | _ = EmailTemplate(name="test2", language="en-us", is_active=False).save() 37 | self.assertEqual(EmailTemplate.objects.active().get(), template1) 38 | 39 | def test_current(self): 40 | # manually setting the version in the wrong order, so the first 41 | # template is actually the last, when ordered by version. 42 | template1 = EmailTemplate(name="test", language="en-us", version=1).save() 43 | _ = EmailTemplate(name="test", language="en-us", version=0).save() 44 | self.assertEqual(EmailTemplate.objects.current("test"), template1) 45 | self.assertEqual( 46 | EmailTemplate.objects.current("test", language="klingon"), None 47 | ) 48 | 49 | def test_version(self): 50 | template1 = EmailTemplate(name="test", language="en-us", version=1).save() 51 | template2 = EmailTemplate(name="test", language="en-us", version=0).save() 52 | self.assertEqual(EmailTemplate.objects.version("test", 1), template1) 53 | self.assertEqual(EmailTemplate.objects.version("test", 0), template2) 54 | 55 | 56 | class EmailTemplateTests(TestCase): 57 | """appmail.models.EmailTemplate model tests.""" 58 | 59 | def test_defaults(self): 60 | template = EmailTemplate() 61 | self.assertEqual(template.language, settings.LANGUAGE_CODE) 62 | self.assertEqual(template.from_email, settings.DEFAULT_FROM_EMAIL) 63 | self.assertEqual(template.reply_to, settings.DEFAULT_FROM_EMAIL) 64 | self.assertEqual(template.reply_to_list, [settings.DEFAULT_FROM_EMAIL]) 65 | self.assertEqual(template.version, 0) 66 | 67 | template.reply_to = "fred@example.com, ginger@example.com" 68 | self.assertEqual( 69 | template.reply_to_list, ["fred@example.com", "ginger@example.com"] 70 | ) 71 | 72 | @mock.patch.object(EmailTemplate, "clean") 73 | def test_save(self, mock_clean): 74 | template = EmailTemplate( 75 | subject="test ßmail", 76 | body_text="this is plain text", 77 | body_html="this is html", 78 | ) 79 | with mock.patch("appmail.models.VALIDATE_ON_SAVE", False): 80 | template.save() 81 | self.assertEqual(mock_clean.call_count, 0) 82 | with mock.patch("appmail.models.VALIDATE_ON_SAVE", True): 83 | template.save() 84 | self.assertEqual(mock_clean.call_count, 1) 85 | # test the override 86 | template.save(validate=False) 87 | self.assertEqual(mock_clean.call_count, 1) 88 | 89 | @mock.patch.object(EmailTemplate, "render_subject") 90 | def test__validate_subject(self, mock_render): 91 | template = EmailTemplate() 92 | mock_render.side_effect = TemplateDoesNotExist("foo.html") 93 | self.assertEqual( 94 | template._validate_subject(), 95 | {"subject": "Template does not exist: foo.html"}, 96 | ) 97 | mock_render.side_effect = TemplateSyntaxError("No can do") 98 | self.assertEqual(template._validate_subject(), {"subject": "No can do"}) 99 | mock_render.side_effect = None 100 | self.assertEqual(template._validate_subject(), {}) 101 | mock_render.side_effect = Exception("Something else") 102 | self.assertRaises(Exception, template._validate_subject) 103 | 104 | @mock.patch.object(EmailTemplate, "render_body") 105 | def test__validate_body__success(self, mock_render): 106 | template = EmailTemplate() 107 | mock_render.side_effect = None 108 | self.assertEqual(template._validate_body(EmailTemplate.CONTENT_TYPE_HTML), {}) 109 | 110 | @mock.patch.object(EmailTemplate, "render_body") 111 | def test__validate_body__template_does_not_exist(self, mock_render): 112 | template = EmailTemplate() 113 | mock_render.side_effect = TemplateDoesNotExist("foo.html") 114 | self.assertEqual( 115 | template._validate_body(content_type=EmailTemplate.CONTENT_TYPE_PLAIN), 116 | {"body_text": "Template does not exist: foo.html"}, 117 | ) 118 | 119 | @mock.patch.object(EmailTemplate, "render_body") 120 | def test__validate_body__template_syntax_error(self, mock_render): 121 | template = EmailTemplate() 122 | mock_render.side_effect = TemplateSyntaxError("No can do") 123 | self.assertEqual( 124 | template._validate_body(content_type=EmailTemplate.CONTENT_TYPE_HTML), 125 | {"body_html": "No can do"}, 126 | ) 127 | 128 | @mock.patch.object(EmailTemplate, "render_body") 129 | def test__validate_body__url_no_reverse_match(self, mock_render): 130 | template = EmailTemplate() 131 | mock_render.side_effect = NoReverseMatch("Reverse for 'briefs' not found.") 132 | self.assertEqual( 133 | template._validate_body(content_type=EmailTemplate.CONTENT_TYPE_HTML), 134 | {"body_html": "Reverse for 'briefs' not found."}, 135 | ) 136 | 137 | @mock.patch.object(EmailTemplate, "render_body") 138 | def test__validate_body__unhandled_exception(self, mock_render): 139 | template = EmailTemplate() 140 | mock_render.side_effect = Exception("Something else") 141 | self.assertRaises(Exception, template._validate_body) 142 | 143 | @mock.patch.object(EmailTemplate, "_validate_body") 144 | def test_clean(self, mock_body): 145 | template = EmailTemplate() 146 | template.clean() 147 | mock_body.return_value = {"body_text": "Template not found"} 148 | self.assertRaises(ValidationError, template.clean) 149 | 150 | def test_render_subject(self): 151 | template = EmailTemplate(subject="Hello {{ first_name }}") 152 | subject = template.render_subject({"first_name": "fråd"}) 153 | self.assertEqual(subject, "Hello fråd") 154 | 155 | def test_render_body(self): 156 | template = EmailTemplate( 157 | body_text="Hello {{ first_name }}", 158 | body_html="Hello {{ first_name }}
", 159 | ) 160 | context = {"first_name": "fråd"} 161 | self.assertEqual(template.render_body(context), "Hello fråd") 162 | self.assertEqual( 163 | template.render_body( 164 | context, content_type=EmailTemplate.CONTENT_TYPE_PLAIN 165 | ), 166 | "Hello fråd", 167 | ) 168 | self.assertEqual( 169 | template.render_body(context, content_type=EmailTemplate.CONTENT_TYPE_HTML), 170 | "Hello fråd
", 171 | ) 172 | self.assertRaises(ValueError, template.render_body, context, content_type="foo") 173 | 174 | def test_clone_template(self): 175 | template = EmailTemplate( 176 | name="Test template", language="en-us", version=0 177 | ).save() 178 | pk = template.pk 179 | clone = template.clone() 180 | template = EmailTemplate.objects.get(id=pk) 181 | self.assertEqual(clone.name, template.name) 182 | self.assertEqual(clone.language, template.language) 183 | self.assertEqual(clone.version, 1) 184 | self.assertNotEqual(clone.id, template.id) 185 | 186 | 187 | class AppmailMessageTests(TestCase): 188 | def test_init(self): 189 | template = EmailTemplate( 190 | subject="Welcome message", 191 | body_text="Hello {{ first_name }}", 192 | body_html="Hello {{ first_name }}
", 193 | ) 194 | context = {"first_name": "fråd"} 195 | message = AppmailMessage(template, context) 196 | self.assertIsInstance(message, EmailMultiAlternatives) 197 | self.assertEqual(message.subject, "Welcome message") 198 | self.assertEqual(message.body, "Hello fråd") 199 | self.assertEqual( 200 | message.alternatives, 201 | [("Hello fråd
", EmailTemplate.CONTENT_TYPE_HTML)], 202 | ) 203 | self.assertEqual(message.to, []) 204 | self.assertEqual(message.cc, []) 205 | self.assertEqual(message.bcc, []) 206 | self.assertEqual(message.from_email, settings.DEFAULT_FROM_EMAIL) 207 | self.assertEqual(message.reply_to, [settings.DEFAULT_FROM_EMAIL]) 208 | 209 | message = AppmailMessage( 210 | template, 211 | context, 212 | to=["bruce@kung.fu"], 213 | cc=["fred@example.com"], 214 | bcc=["ginger@example.com"], 215 | from_email="FredHello {{ first_name }}
", 242 | supports_attachments=True, 243 | ) 244 | AppmailMessage(template, {}, attachments=[mock.Mock(spec=MIMEImage)]) 245 | 246 | def test_init__with_attachments__disallowed(self): 247 | template = EmailTemplate( 248 | subject="Welcome {{ first_name }}", 249 | body_text="Hello {{ first_name }}", 250 | body_html="Hello {{ first_name }}
", 251 | supports_attachments=False, 252 | ) 253 | with self.assertRaisesMessage( 254 | ValueError, "Email template does not support attachments." 255 | ): 256 | AppmailMessage(template, {}, attachments=[mock.Mock(spec=MIMEImage)]) 257 | 258 | def test_init__special_characters(self): 259 | template = EmailTemplate( 260 | subject="Welcome {{ first_name }}", 261 | body_text="Hello {{ first_name }}", 262 | body_html="Hello {{ first_name }}
", 263 | ) 264 | 265 | context = {"first_name": "Test & Company"} 266 | message = AppmailMessage(template, context) 267 | self.assertIsInstance(message, EmailMultiAlternatives) 268 | self.assertEqual(message.subject, "Welcome Test & Company") 269 | self.assertEqual(message.body, "Hello Test & Company") 270 | self.assertEqual( 271 | message.alternatives, 272 | [("Hello Test & Company
", EmailTemplate.CONTENT_TYPE_HTML)], 273 | ) 274 | 275 | def test_init__special_characters__complex_context(self): 276 | template = EmailTemplate( 277 | subject="Hello {{ user.first_name }} and welcome to {{ company_name }}", 278 | body_text="Hello {{ user.first_name }} and welcome to {{ company_name }}", 279 | body_html=( 280 | "Hello {{ user.first_name }}
" 281 | "Welcome to {{ company_name }}
" 282 | ), 283 | ) 284 | context = { 285 | "user": {"first_name": "Test & Company"}, 286 | "company_name": "Me & Co Inc", 287 | } 288 | message = AppmailMessage(template, context) 289 | self.assertIsInstance(message, EmailMultiAlternatives) 290 | self.assertEqual( 291 | message.subject, "Hello Test & Company and welcome to Me & Co Inc" 292 | ) 293 | self.assertEqual( 294 | message.body, "Hello Test & Company and welcome to Me & Co Inc" 295 | ) 296 | self.assertEqual( 297 | message.alternatives, 298 | [ 299 | ( 300 | "Hello Test & Company
" 301 | "Welcome to Me & Co Inc
", 302 | EmailTemplate.CONTENT_TYPE_HTML, 303 | ) 304 | ], 305 | ) 306 | 307 | @mock.patch.object(LoggedMessageManager, "log") 308 | def test_send__logging(self, mock_log): 309 | template = EmailTemplate.objects.create( 310 | subject="Welcome message", 311 | body_text="Hello {{ first_name }}", 312 | body_html="