django-simple-mailer

A simple Django app for sending template-driven emails.

Features

• Send HTML + plain-text emails using Django templates
• Optional email logging — persist every send attempt to a MailLog table, viewable in Django admin (disabled by default, enable with SIMPLE_MAILER_LOG_EMAILS = True)
• Clean MailerError exception for straightforward error handling

Installation

pip install django-simple-mailer

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "django_simple_mailer",
]

Configure Django's email settings (standard Django — nothing library-specific):

DEFAULT_FROM_EMAIL = "no-reply@example.com"
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.example.com"
EMAIL_HOST_USER = "..."
EMAIL_HOST_PASSWORD = "..."
EMAIL_PORT = 587
EMAIL_USE_TLS = True

Ensure your TEMPLATES setting has APP_DIRS enabled — this is how the mailer finds your email templates. Django's default setup already includes it:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
        ...
    }
]

With APP_DIRS = True, place your email templates inside any app's templates/ directory and Email() will resolve them automatically. If your project uses a custom loaders list instead of APP_DIRS, make sure django.template.loaders.app_directories.Loader is included.

For more info on templates see Template Convention below.

No migrate step is needed unless you enable email logging (see Email Logging below).

Usage

For each email, create three template files inside any app's templates/ directory. Templates can sit anywhere within the templates/ directory:

your_app/
  templates/
    emails/
      welcome_email.subject   ← subject line (single line, no newlines)
      welcome_email.txt       ← plain-text body
      welcome_email.html      ← HTML body

Then send the email:

from django_simple_mailer import Email

Email(
    template="emails/welcome_email",  # path relative to `templates/`
    context={"name": "Jane", "link": "https://app.example.com"},
    recipients=["jane@example.com"],
).send()

Email() resolves templates using Django's template engine. APP_DIRS = True is the standard setup but any configured template discoverable by Django should work.

Error Handling

send() raises MailerError on delivery failure, you can get the original exception from __cause__:

from django_simple_mailer import Email, MailerError

try:
    Email(template="welcome_email", context={...}, recipients=[...]).send()
except MailerError as exc:
    # The underlying SMTP/backend exception is available as exc.__cause__
    logger.error("Email delivery failed: %s", exc.__cause__)

Email Logging

Disabled by default. Enable with SIMPLE_MAILER_LOG_EMAILS = True. requires having a database configured and 'django.contrib.admin' installed.

When enabled, every send() call — success or failure — writes a MailLog record to the database. Logs are viewable and searchable from Django admin.

Setup:

# settings.py
SIMPLE_MAILER_LOG_EMAILS = True  # default: False

Then run migrations to create the MailLog table:

python manage.py migrate

What gets logged:

Without a database:

When SIMPLE_MAILER_LOG_EMAILS = False (the default), the library has zero database interaction and works in Django projects without a configured database.

Settings Reference

Template Convention

Each email requires exactly three files with the same name and path relative to any app's templates/ directory:

When using Email(), the template argument must match the path relative to templates/. Subdirectories are supported — template="emails/welcome/welcome_email" resolves to templates/emails/welcome/welcome_email.{subject,txt,html}.

All three files are rendered with the same context dict passed to Email().