Skip to main content

Markdown template based HTML and text emails for Django.

Project description

Django eMark↓

emark logo: envelope with markdown stamp

Markdown template based HTML and text emails for Django.

  • simple email templates with markdown
  • support for HTML and text emails
  • i18n support
  • built-in UTM tracking
  • built-in sent, open and click tracking
  • automatic CSS inliner via premailer

PyPi Version Test Coverage GitHub License

Setup

python3 -m pip install emark
# settings.py
INSTALLED_APPS = [
    'emark',
    # ...
]
python3 manage.py migrate

Usage

<!-- myapp/my_message.md -->
# Hello World

Hi {{ user.short_name }}!
# myapp/emails.py
from emark.message import MarkdownEmail

class MyMessage(MarkdownEmail):
    subject = "Hello World"
    template_name = "myapp/my_message.md"
# myapp/views.py
from . import emails

def my_view(request):
    message = emails.MyMessage.to_user(request.user)
    message.send()

Templates

You can use Django's template engine, just like you usually would. You can use translations, template tags, filters, blocks, etc.

You may also have a base template, that you inherit form in your individual emails to provide a consistent salutation and farewell.

<!-- base.md -->
{% load static i18n %}
{% block salutation %}Hi {{ user.short_name }}!{% endblock %}

{% block content %}{% endblock %}

{% block farewell %}
{% blocktrans trimmed %}
Best regards,
{{ site_admin }}
{% endblocktrans %}
{% endblock %}

{% block footer %}
Legal footer.
{% endblock %}
<!-- myapp/email.md -->
{% extends "base.md" %}

{% block content %}
This is the content of the email.
{% endblock %}

Context

The context is passed to the template as a dictionary. Furthermore, you may override the get_context_data method to add additional context variables.

# myapp/emails.py
from emark.message import MarkdownEmail

class MyMessage(MarkdownEmail):
    subject = "Hello World"
    template_name = "myapp/email.md"

    def get_context_data(self):
        context = super().get_context_data()
        context["my_variable"] = "Hello World"
        return context

Tracking

Sent, Open & Click Tracking

Django eMark comes with built-in tracking for sent, open and click events. The tracking is done via a tracking pixel and a redirect view.

As an added bonus, this feature also comes with an open-in-browser link that allows the user to view the email in their browser if their email client does not support HTML emails.

This feature is disabled by default. To enable it, you need to use a separate email backend. This backend will send the email via SMTP and also add the tracking pixel and redirect view. However, it will send a separate email for each recipient, which may not be desirable in all cases.

# settings.py
EMAIL_BACKEND = "emark.backends.TrackingSMTPEmailBackend"

Furthermore, you need to add the tracking view to your urls.py:

# urls.py
from django.urls import include, path

urlpatterns = [
    # … other urls
    path("emark/", include("emark.urls")),
]

You will need to provide a domain name for the tracking pixel and redirect view. This can be done via the DOMAIN setting:

# settings.py
EMARK = {
    "DOMAIN": "example.com"
}

If the site framework is installed and no settings are provided, the domain will be automatically set to the current site's domain.

The tracking data is stored in the database. You need to run migrations to create the necessary tables:

python3 manage.py migrate

You can analyze the tracking data via the tables emark_sent, emark_open and emark_click.

UTM Tracking

Every MarkdownEmail subclass comes with automatic UTM tracking. UTM parameters are added to all links in the email. Existing UTM params on link that have been explicitly set, are not overridden. The default parameters are:

  • utm_source: website
  • utm_medium: email
  • utm_campaign: {{ EMAIL_CLASS_NAME }}

The global UTM parameters can be overridden via the EMARK_UTM_PARAMS setting, which is a dictionary of parameters:

# settings.py
EMARK = {
  "UTM_PARAMS": {
      "utm_source": "website",  # default
      "utm_medium": "email",  # default
  }
}

You may also change the UTM parameters by overriding the get_utm_params or passing a utm_params dictionary to class constructor.

# myapp/emails.py
from emark.message import MarkdownEmail


class MyMessage(MarkdownEmail):
  subject = "Hello World"
  template_name = "myapp/email.md"

  # override the parameters for this email class
  def get_utm_params(self):
    return {
      "utm_source": "myapp",
      "utm_medium": "email",
      "utm_campaign": "my-campaign",
    }


# or alternatively during instantiation
MyMessage(utm_params={"utm_campaign": "my-other-campaign"}).send()

Development

Pretty HTML emails are great, unless they spam your console during development. To prevent this, you can use the ConsoleEmailBackend:

# settings.py
EMAIL_BACKEND = "emark.backends.ConsoleEmailBackend"

The ConsoleEmailBackend will only print the plain text version of the email.

Email Dashboard

Django eMark comes with a simple email dashboard to preview your templates.

To enable the dashboard, add the app to your INSTALLED_APPS setting

# settings.py
INSTALLED_APPS = [
    # ...
    "emark",
    "emark.contrib.dashboard",  # needs to be added before Django's admin app
    # ...
    "django.contrib.admin",  # required for the dashboard
    # ...
]

and add the following to your urls.py:

# urls.py
from django.urls import include, path


urlpatterns = [
    # … other urls
    path("emark/", include([
        path("", include("emark.urls")),
        path("dashboard/", include("emark.contrib.dashboard.urls")),
    ])),
]

Next you need to register the email classes you want to preview in the dashboard:

# myapp/emails.py
from emark.message import MarkdownEmail
from emark.contrib import dashboard

@dashboard.register
class MyMessage(MarkdownEmail):
    subject = "Hello World"
    template_name = "myapp/email.md"

Credits

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

emark-2.1.3.tar.gz (21.0 kB view details)

Uploaded Source

Built Distribution

emark-2.1.3-py3-none-any.whl (24.6 kB view details)

Uploaded Python 3

File details

Details for the file emark-2.1.3.tar.gz.

File metadata

  • Download URL: emark-2.1.3.tar.gz
  • Upload date:
  • Size: 21.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for emark-2.1.3.tar.gz
Algorithm Hash digest
SHA256 1278dc0d9a8e1f584d028484f0e8c925b718813e0224680bb8c9819612911d34
MD5 39f7b54de8dc5b3179cca1959e93659e
BLAKE2b-256 46585175738614f3ffdc94f77db8f1209de40dda903cba9d20031d79b4c80b70

See more details on using hashes here.

File details

Details for the file emark-2.1.3-py3-none-any.whl.

File metadata

  • Download URL: emark-2.1.3-py3-none-any.whl
  • Upload date:
  • Size: 24.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for emark-2.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 77f7aed58e15cb5c1186c18ec249d16dcf3a00e209f8473de768d03de97594c9
MD5 a85533eba8cf239409745bdf69cc2ac6
BLAKE2b-256 a27957282878ac4bba80cc8402710120b5a26b37759fb6f03e934d5bfee49d9b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page