Django Templated Mail

Common errors

• django.template.exceptions.TemplateDoesNotExist: emails/welcome.html

  cause Django's template loaders could not find the specified template file for your email.
  fix Ensure the template file exists at the correct path (e.g., `your_app/templates/emails/welcome.html`) and that your Django `TEMPLATES` settings correctly include `APP_DIRS=True` or `DIRS` pointing to your template folders.

• AttributeError: 'WelcomeEmail' object has no attribute 'send_to'

  cause You are attempting to use the deprecated `send_to` method, which was renamed to `send`.
  fix Update your code to use `email.send(...)` instead of `email.send_to(...)`. This change was introduced in version 0.2.0.

• ImproperlyConfigured: Requested setting TEMPLATES, but settings have not been configured.

  cause You are trying to use `django-templated-mail` without a properly configured Django environment.
  fix Ensure Django settings are configured and `django.setup()` has been called before using `BaseEmailMessage`. In a typical Django project, `manage.py` handles this. For standalone scripts, you need to explicitly configure settings and call `django.setup()`.

Warnings

• breaking The `set_context_data` method on `BaseEmailMessage` was renamed to `get_context_data` in version 1.0.0.
  Fix: Update calls from `email.set_context_data()` to `email.get_context_data()`.
• breaking The method `BaseEmailMessage.send_to` was renamed to `BaseEmailMessage.send` in version 0.2.0 for consistency.
  Fix: Replace all calls to `email.send_to(...)` with `email.send(...)`.
• breaking Support for Django 1.10 was removed in version 1.1.0. The library now requires Django 1.11 or higher.
  Fix: Upgrade your Django project to version 1.11 or a later compatible version (e.g., Django 2.0+).
• gotcha Prior to version 1.1.1, the `from_email` parameter in `BaseEmailMessage.send` did not always correctly fall back to `settings.DEFAULT_FROM_EMAIL` if omitted.
  Fix: Upgrade to `django-templated-mail` version 1.1.1 or higher. Alternatively, explicitly pass the `from_email` argument to the `send` method or set it on the `BaseEmailMessage` instance.

Install

• pip install django-templated-mail Install stable release

Imports

• BaseEmailMessage

  from templated_mail.mail import BaseEmailMessage

Quickstart

This quickstart demonstrates how to define a templated email class and send an email using `django-templated-mail`. It sets up minimal Django settings for a runnable example. Remember to create the actual template file (e.g., `my_app/templates/emails/welcome.html`) in your Django project, extending `templated_mail/email.html` and defining `subject`, `html`, and `plain` blocks.

import os
import django
from django.conf import settings
from templated_mail.mail import BaseEmailMessage

# Minimal Django setup for demonstration purposes.
# In a real Django project, these settings would be in your settings.py
# and django.setup() would be handled by manage.py.
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

if not settings.configured:
    settings.configure(
        INSTALLED_APPS=['templated_mail'],
        TEMPLATES=[
            {
                'BACKEND': 'django.template.backends.django.DjangoTemplates',
                'DIRS': [],
                'APP_DIRS': True, # Allows finding templates in app 'templates' subdirectories
                'OPTIONS': {
                    'debug': True,
                },
            },
        ],
        DEFAULT_FROM_EMAIL='noreply@example.com',
        EMAIL_BACKEND='django.core.mail.backends.console.EmailBackend', # Prints email to console
    )
# Ensure Django is set up *after* settings are configured.
django.setup()

# Define your custom email message class.
# IMPORTANT: You need to create the actual template file in your Django project.
# For example, create 'my_app/templates/emails/welcome.html' with content like:
#
# {% extends "templated_mail/email.html" %}
# {% block subject %}Welcome, {{ user_name }}!{% endblock %}
# {% block html %}<p>Hello {{ user_name }},</p><p>Thank you for joining our service!</p>{% endblock %}
# {% block plain %}{% block subject %}{% endblock %} Hello {{ user_name }}, Thank you for joining our service!{% endblock %}

class WelcomeEmail(BaseEmailMessage):
    # This path assumes 'emails/welcome.html' is found in one of your TEMPLATES DIRS or APP_DIRS
    template_name = 'emails/welcome.html'

# Instantiate and send the email
context_data = {'user_name': 'John Doe'}
email = WelcomeEmail(context=context_data)
email.send(to=['john.doe@example.com'], from_email='noreply@myservice.com')

print("\nEmail sent (output to console). Check your console for details.")