{"id":19166967,"url":"https://github.com/voiio/emark","last_synced_at":"2025-05-12T14:45:06.057Z","repository":{"id":60632043,"uuid":"543487848","full_name":"voiio/emark","owner":"voiio","description":"eMark↓ – Markdown template based HTML and text emails for Django.","archived":false,"fork":false,"pushed_at":"2025-05-05T15:54:14.000Z","size":284,"stargazers_count":30,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-05T16:53:50.198Z","etag":null,"topics":["django","email","email-template","hacktoberfest","html","markdown","python","template","templates"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voiio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["amureki","codingjoe"]}},"created_at":"2022-09-30T07:49:04.000Z","updated_at":"2025-05-05T15:54:17.000Z","dependencies_parsed_at":"2023-09-29T11:20:04.627Z","dependency_job_id":"8338f127-7fc3-4d91-aeb7-d905099ea8bf","html_url":"https://github.com/voiio/emark","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voiio%2Femark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voiio%2Femark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voiio%2Femark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voiio%2Femark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voiio","download_url":"https://codeload.github.com/voiio/emark/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253757464,"owners_count":21959406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","email","email-template","hacktoberfest","html","markdown","python","template","templates"],"created_at":"2024-11-09T09:35:08.856Z","updated_at":"2025-05-12T14:45:06.025Z","avatar_url":"https://github.com/voiio.png","language":"Python","funding_links":["https://github.com/sponsors/amureki","https://github.com/sponsors/codingjoe"],"categories":[],"sub_categories":[],"readme":"# Django eMark↓\n\n\u003cimg alt=\"emark logo: envelope with markdown stamp\" src=\"https://raw.githubusercontent.com/voiio/emark/main/emark-logo.svg\" width=\"320\" height=\"170\" align=\"right\"\u003e\n\nMarkdown template based HTML and text emails for Django.\n\n* simple email templates with markdown\n* support for HTML and text emails\n* i18n support\n* built-in UTM tracking\n* built-in sent, open and click tracking\n* automatic CSS inliner via [premailer](https://github.com/peterbe/premailer/)\n\n[![PyPi Version](https://img.shields.io/pypi/v/emark.svg)](https://pypi.python.org/pypi/emark/)\n[![Test Coverage](https://codecov.io/gh/voiio/emark/branch/main/graph/badge.svg)](https://codecov.io/gh/voiio/emark)\n[![GitHub License](https://img.shields.io/github/license/voiio/emark)](https://raw.githubusercontent.com/voiio/emark/master/LICENSE)\n\n## Setup\n\n```ShellSession\npython3 -m pip install emark\n```\n\n```python\n# settings.py\nINSTALLED_APPS = [\n    'emark',\n    # ...\n]\n```\n\n```ShellSession\npython3 manage.py migrate\n```\n\n## Usage\n\n```markdown\n\u003c!-- myapp/my_message.md --\u003e\n# Hello World\n\nHi {{ user.short_name }}!\n```\n\n```python\n# myapp/emails.py\nfrom emark.message import MarkdownEmail\n\nclass MyMessage(MarkdownEmail):\n    subject = \"Hello World\"\n    template_name = \"myapp/my_message.md\"\n```\n\n```python\n# myapp/views.py\nfrom . import emails\n\ndef my_view(request):\n    message = emails.MyMessage.to_user(request.user)\n    message.send()\n```\n\n### Templates\n\nYou can use Django's template engine, just like you usually would.\nYou can use translations, template tags, filters, blocks, etc.\n\nYou may also have a base template, that you inherit form in your individual\nemails to provide a consistent salutation and farewell.\n\n```markdown\n\u003c!-- base.md --\u003e\n{% load static i18n %}\n{% block salutation %}Hi {{ user.short_name }}!{% endblock %}\n\n{% block content %}{% endblock %}\n\n{% block farewell %}\n{% blocktrans trimmed %}\nBest regards,\n{{ site_admin }}\n{% endblocktrans %}\n{% endblock %}\n\n{% block footer %}\nLegal footer.\n{% endblock %}\n```\n\n```markdown\n\u003c!-- myapp/email.md --\u003e\n{% extends \"base.md\" %}\n\n{% block content %}\nThis is the content of the email.\n{% endblock %}\n```\n\n### Context\n\nThe context is passed to the template as a dictionary. Furthermore, you may\noverride the `get_context_data` method to add additional context variables.\n\n```python\n# myapp/emails.py\nfrom emark.message import MarkdownEmail\n\nclass MyMessage(MarkdownEmail):\n    subject = \"Hello World\"\n    template_name = \"myapp/email.md\"\n\n    def get_context_data(self):\n        context = super().get_context_data()\n        context[\"my_variable\"] = \"Hello World\"\n        return context\n```\n\n### Tracking\n\n#### Sent, Open \u0026 Click Tracking\n\nDjango eMark comes with built-in tracking for sent, open and click events.\nThe tracking is done via a tracking pixel and a redirect view.\n\nAs an added bonus, this feature also comes with an open-in-browser link that\nallows the user to view the email in their browser if their email client does\nnot support HTML emails.\n\nThis feature is disabled by default. To enable it, you need to use a separate email\nbackend. This backend will send the email via SMTP and also add the tracking\npixel and redirect view. However, it will send a separate email for each\nrecipient, which may not be desirable in all cases.\n\n```python\n# settings.py\nEMAIL_BACKEND = \"emark.backends.TrackingSMTPEmailBackend\"\n```\n\nFurthermore, you need to add the tracking view to your `urls.py`:\n\n```python\n# urls.py\nfrom django.urls import include, path\n\nurlpatterns = [\n    # … other urls\n    path(\"emark/\", include(\"emark.urls\")),\n]\n```\n\nYou will need to provide a domain name for the tracking pixel and redirect view.\nThis can be done via the `DOMAIN` setting:\n\n```python\n# settings.py\nEMARK = {\n    \"DOMAIN\": \"example.com\"\n}\n```\n\nIf the site framework is installed and no settings are provided,\nthe domain will be automatically set to the current site's domain.\n\nThe tracking data is stored in the database. You need to run migrations to\ncreate the necessary tables:\n\n```ShellSession\npython3 manage.py migrate\n```\n\nYou can analyze the tracking data via the tables `emark_sent`, `emark_open` and\n`emark_click`.\n\n#### UTM Tracking\n\nEvery `MarkdownEmail` subclass comes with automatic UTM tracking.\nUTM parameters are added to all links in the email. Existing UTM params on link\nthat have been explicitly set, are not overridden. The default parameters are:\n\n* `utm_source`: `website`\n* `utm_medium`: `email`\n* `utm_campaign`: `{{ EMAIL_CLASS_NAME }}`\n\nThe global UTM parameters can be overridden via the `EMARK_UTM_PARAMS` setting,\nwhich is a dictionary of parameters:\n\n```python\n# settings.py\nEMARK = {\n  \"UTM_PARAMS\": {\n      \"utm_source\": \"website\",  # default\n      \"utm_medium\": \"email\",  # default\n  }\n}\n```\n\nYou may also change the UTM parameters by overriding the `get_utm_params`\nor passing a `utm_params` dictionary to class constructor.\n\n```python\n# myapp/emails.py\nfrom emark.message import MarkdownEmail\n\n\nclass MyMessage(MarkdownEmail):\n  subject = \"Hello World\"\n  template_name = \"myapp/email.md\"\n\n  # override the parameters for this email class\n  def get_utm_params(self):\n    return {\n      \"utm_source\": \"myapp\",\n      \"utm_medium\": \"email\",\n      \"utm_campaign\": \"my-campaign\",\n    }\n\n\n# or alternatively during instantiation\nMyMessage(utm_params={\"utm_campaign\": \"my-other-campaign\"}).send()\n```\n\n## Development\n\nPretty HTML emails are great, unless they spam your console during development.\nTo prevent this, you can use the `ConsoleEmailBackend`:\n\n```python\n# settings.py\nEMAIL_BACKEND = \"emark.backends.ConsoleEmailBackend\"\n```\n\nThe `ConsoleEmailBackend` will only print the plain text version of the email.\n\n### Email Dashboard\n\nDjango eMark comes with a simple email dashboard to preview your templates.\n\nTo enable the dashboard, add the app to your `INSTALLED_APPS` setting\n\n```python\n# settings.py\nINSTALLED_APPS = [\n    # ...\n    \"emark\",\n    \"emark.contrib.dashboard\",  # needs to be added before Django's admin app\n    # ...\n    \"django.contrib.admin\",  # required for the dashboard\n    # ...\n]\n```\n\nand add the following to your `urls.py`:\n\n```python\n# urls.py\nfrom django.urls import include, path\n\n\nurlpatterns = [\n    # … other urls\n    path(\"emark/\", include([\n        path(\"\", include(\"emark.urls\")),\n        path(\"dashboard/\", include(\"emark.contrib.dashboard.urls\")),\n    ])),\n]\n```\n\nNext you need to register the email classes you want to preview in the dashboard:\n\n```python\n# myapp/emails.py\nfrom emark.message import MarkdownEmail\nfrom emark.contrib import dashboard\n\n@dashboard.register\nclass MyMessage(MarkdownEmail):\n    subject = \"Hello World\"\n    template_name = \"myapp/email.md\"\n```\n\n## Credits\n\n- Django eMark uses modified version of [Responsive HTML Email Template](https://github.com/leemunroe/responsive-html-email-template/) as a base template\n- For CSS inlining, Django eMark uses [premailer](https://github.com/peterbe/premailer/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoiio%2Femark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoiio%2Femark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoiio%2Femark/lists"}