django-mail-analytics 1.0.0__py3-none-any.whl

django_mail_analytics/__init__.py

@@ -0,0 +1,17 @@
+from django_mail_analytics.metadata import (
+    __author__,
+    __copyright__,
+    __description__,
+    __license__,
+    __title__,
+    __version__,
+)
+
+__all__ = [
+    "__author__",
+    "__copyright__",
+    "__description__",
+    "__license__",
+    "__title__",
+    "__version__",
+]

django_mail_analytics/admin.py

@@ -0,0 +1,158 @@
+from django.contrib import admin
+from django.db.models import Count, Q
+from django.utils.safestring import mark_safe
+
+from .models import Mail, MailRecipient, MailRecipientAction
+
+
+class MailRecipientActionInline(admin.TabularInline):
+    model = MailRecipientAction
+    fields = ("pk", "created", "action")
+    readonly_fields = ("pk", "created", "action")
+    can_delete = False
+    extra = 0
+    max_num = 0
+    show_change_link = True
+
+
+@admin.register(MailRecipientAction)
+class MailRecipientActionAdmin(admin.ModelAdmin):
+    """Define admin model for MailRecipientAction model."""
+
+    list_display = ("id", "created", "action", "recipient_email", "recipient_mail_key")
+    readonly_fields = ("id", "created", "recipient", "action")
+
+
+class MailRecipientInline(admin.TabularInline):
+    model = MailRecipient
+    fields = ("pk", "created", "email", "sent", "opened", "openings", "clicks")
+    readonly_fields = ("pk", "created", "email", "sent", "opened", "openings", "clicks")
+    can_delete = False
+    extra = 0
+    max_num = 0
+    show_change_link = True
+
+    def get_queryset(self, request):
+        opening = Q(actions__action="")
+        hasAction = Q(actions__isnull=False)
+        qs = super().get_queryset(request)
+        qs = qs.annotate(opened=Count("id", filter=hasAction & opening, distinct=True))
+        qs = qs.annotate(sent=Count("id", distinct=True))
+        qs = qs.annotate(openings=Count("actions", filter=opening))
+        qs = qs.annotate(clicks=Count("actions", filter=~opening))
+        return qs
+
+    @admin.display(description="Opened")
+    def opened(self, instance):
+        return instance.opened
+
+    @admin.display(description="Sent")
+    def sent(self, instance):
+        return instance.sent
+
+    @admin.display(description="Openings")
+    def openings(self, instance):
+        return instance.openings
+
+    @admin.display(description="Clicks")
+    def clicks(self, instance):
+        return instance.clicks
+
+
+@admin.register(MailRecipient)
+class MailRecipientAdmin(admin.ModelAdmin):
+    """Define admin model for MailRecipient model."""
+
+    def get_queryset(self, request):
+        opening = Q(actions__action="")
+        hasAction = Q(actions__isnull=False)
+
+        qs = super().get_queryset(request)
+        qs = qs.annotate(opened=Count("id", filter=hasAction & opening, distinct=True))
+        qs = qs.annotate(sent=Count("id", distinct=True))
+        qs = qs.annotate(openings=Count("actions", filter=opening))
+        qs = qs.annotate(clicks=Count("actions", filter=~opening))
+        return qs
+
+    @admin.display(description="Success Rate")
+    def rate(self, instance):
+        return f"{int(100*(instance.opened/instance.sent))}%"
+
+    @admin.display(description="Opened")
+    def opened(self, instance):
+        return instance.opened
+
+    @admin.display(description="Sent")
+    def sent(self, instance):
+        return instance.sent
+
+    @admin.display(description="Openings")
+    def openings(self, instance):
+        return instance.openings
+
+    @admin.display(description="Clicks")
+    def clicks(self, instance):
+        return instance.clicks
+
+    list_display = ("id", "created", "mail_key", "email", "rate", "opened", "sent", "openings", "clicks")
+    readonly_fields = (
+        "id",
+        "mail",
+        "recipient",
+    )
+    inlines = [
+        MailRecipientActionInline,
+    ]
+
+
+@admin.register(Mail)
+class MailAdmin(admin.ModelAdmin):
+    """Define admin model for Mail model."""
+
+    def get_queryset(self, request):
+        opening = Q(recipients__actions__action="")
+        hasAction = Q(recipients__actions__isnull=False)
+
+        qs = super().get_queryset(request)
+        qs = qs.annotate(opened=Count("recipients", filter=hasAction & opening, distinct=True))
+        qs = qs.annotate(sent=Count("recipients", distinct=True))
+        qs = qs.annotate(openings=Count("recipients__actions", filter=opening))
+        qs = qs.annotate(clicks=Count("recipients__actions", filter=~opening))
+        return qs
+
+    def body_html(self, obj):
+        return mark_safe(obj.body)
+
+    @admin.display(description="Success Rate")
+    def rate(self, instance):
+        return f"{int(100*(instance.opened/instance.sent))}%"
+
+    @admin.display(description="Opened")
+    def opened(self, instance):
+        return instance.opened
+
+    @admin.display(description="Sent")
+    def sent(self, instance):
+        return instance.sent
+
+    @admin.display(description="Openings")
+    def openings(self, instance):
+        return instance.openings
+
+    @admin.display(description="Clicks")
+    def clicks(self, instance):
+        return instance.clicks
+
+    exclude = ("body",)
+    readonly_fields = (
+        "id",
+        "key",
+        "sender",
+        "subject",
+        "body_html",
+    )
+
+    list_display = ("id", "created", "key", "subject", "rate", "opened", "sent", "openings", "clicks")
+    inlines = [
+        MailRecipientInline,
+    ]

django_mail_analytics/apps.py

@@ -0,0 +1,14 @@
+from django.apps import AppConfig
+
+
+class DjangoMailAnalyticsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_mail_analytics"
+
+    def ready(self):
+        # pylint: disable=import-outside-toplevel
+
+        # monky patch mail functions
+        from .mail import send
+
+        _ = send  # just there to avoid autoremoval of the import

django_mail_analytics/mail.py

@@ -0,0 +1,135 @@
+# import django.core.mail as mail
+import logging
+import re
+from datetime import datetime
+from functools import cache
+
+import wrapt
+from django.conf import settings
+from django.urls import reverse
+from django.utils.http import urlencode
+from hashids import Hashids
+
+from .models import Mail, MailRecipient, MailRecipientAction
+
+logger = logging.getLogger(__name__)
+
+
+@cache
+def mail_settings() -> dict:
+    default_settings = getattr(settings, "MAIL_ANALYTICS", {})
+    if "SALT" not in default_settings:
+        default_settings["SALT"] = getattr(settings, "SECRET_KEY", "salt")
+    if "LENGTH" not in default_settings:
+        default_settings["LENGTH"] = 6
+    return default_settings
+
+
+@cache
+def get_hasher():
+    salt = mail_settings()["SALT"]
+    length = mail_settings()["LENGTH"]
+    return Hashids(salt=salt, min_length=length)
+
+
+def get_pixel_tag(q):
+    scheme = mail_settings()["SCHEME"]
+    domain = mail_settings()["DOMAIN"]
+    uri = reverse("mail_pixel")
+    qp = urlencode({"q": get_hasher().encode(q)})
+    url = f"{scheme}://{domain}{uri}?{qp}"
+    return f"""<img src="{url}" height="0px" width="0px"/>"""
+
+
+def get_proxy_url(q, url):
+    scheme = mail_settings()["SCHEME"]
+    domain = mail_settings()["DOMAIN"]
+    if url.startswith(f"{scheme}://{domain}"):
+        url = url.replace(f"{scheme}://{domain}", "")
+
+    uri = reverse("mail_proxy")
+    qp = urlencode({"q": get_hasher().encode(q), "u": url})
+    return f"{scheme}://{domain}{uri}?{qp}"
+
+
+def replace_href_by_proxy(q, href_match):
+    url = href_match.group(1)
+    proxy = get_proxy_url(q, url)
+    return f'href="{proxy}"'
+
+
+@wrapt.patch_function_wrapper("django.core.mail", "EmailMessage.send")
+def send(wrapped, instance, args, kwargs):
+    def get_mailId(instance, html_message, tracker):
+        subject = instance.subject
+        from_email = instance.from_email
+        recipient_list = instance.recipients()
+
+        mail, _ = Mail.objects.update_or_create(
+            key=tracker or subject[:25],
+            date=datetime.now().date(),
+            create_defaults=dict(
+                sender=from_email,
+                subject=subject[:2048],
+                body=html_message,
+            ),
+        )
+
+        mailRecipient, _ = MailRecipient.objects.update_or_create(
+            mail=mail, recipient=",".join(recipient_list)
+        )
+        return mail.id, mailRecipient.id
+
+    mailId, mailRId = 0, 0
+
+    # check for tracker code from email recipent list
+    trackers = [x.rsplit("@", 1)[0] for x in instance.to if x.lower().endswith("@dma")]
+    instance.to = [x for x in instance.to if not x.lower().endswith("@dma")]
+
+    tracker = trackers[-1] if trackers else None
+    if hasattr(instance, "alternatives"):
+        for I, x in enumerate(instance.alternatives):
+            alternative, mime_type = x
+            if mime_type == "text/html" and alternative:
+                html_message = alternative
+
+                if not mailId or not mailRId:
+                    mailId, mailRId = get_mailId(instance, html_message, tracker)
+
+                if "</body>" in html_message:
+                    html_message = html_message.replace(
+                        "</body>", f"{get_pixel_tag(mailRId)}\n</body>"
+                    )
+
+                # check if there tags with href attributes and replace them by a proxy
+                def sub_replacor(href_match, mailRId=mailRId):
+                    return replace_href_by_proxy(mailRId, href_match)
+
+                html_message, _ = re.subn(
+                    '''href="(.*?)"''', sub_replacor, html_message
+                )
+
+                instance.alternatives[I] = (html_message, mime_type)
+
+    return wrapped(*args, **kwargs)
+
+
+async def register_action(q, url=""):
+    if q is None:
+        return
+
+    try:
+        # decode query
+        decoded = get_hasher().decode(q)
+        assert decoded
+        q = decoded[0]
+
+        exists = await MailRecipient.objects.filter(id=q).aexists()
+        if not exists:
+            logging.warning(f"ignoring unexistant recipient_id {q}")
+            return
+
+        await MailRecipientAction.objects.acreate(recipient_id=q, action=url)
+
+    except Exception as e:
+        logging.error("ERROR", type(e), e.__dict__)

django_mail_analytics/metadata.py

@@ -0,0 +1,10 @@
+__author__ = "Loic Quertenmont"
+__copyright__ = "Copyright (c) 2014-present Loic Quertenmont"
+__description__ = (
+    "django package adding email tracking features."
+    "Both email opening and link clicking are tracked."
+)
+__email__ = "loic@deeperanalytics.be"
+__license__ = "MIT"
+__title__ = "django-mail-analytics"
+__version__ = "1.0.0"

django_mail_analytics/migrations/0001_initial.py

@@ -0,0 +1,44 @@
+# Generated by Django 5.1 on 2024-10-03 14:41
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Mail',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False)),
+                ('key', models.CharField(db_index=True, max_length=128)),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('sender', models.CharField(max_length=2048, null=True)),
+                ('subject', models.CharField(max_length=2048, null=True)),
+                ('body', models.TextField(blank=True, null=True)),
+                ('date', models.DateField(editable=False)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='MailRecipient',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False)),
+                ('recipient', models.CharField(max_length=2048)),
+                ('mail', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='recipients', to='django_mail_analytics.mail')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='MailRecipientAction',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False)),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('action', models.CharField(max_length=2048)),
+                ('recipient', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='actions', to='django_mail_analytics.mailrecipient')),
+            ],
+        ),
+    ]

django_mail_analytics/models.py

@@ -0,0 +1,53 @@
+from django.db import models
+
+
+class Mail(models.Model):
+    id = models.AutoField(primary_key=True, auto_created=True)
+    key = models.CharField(null=False, max_length=128, db_index=True)
+    date = models.DateField(null=False, editable=False)
+    created = models.DateTimeField(auto_now_add=True, editable=False)
+    sender = models.CharField(null=True, max_length=2048)  # noqa: DJ001
+    subject = models.CharField(null=True, max_length=2048)  # noqa: DJ001
+    body = models.TextField(null=True, blank=True)  # noqa: DJ001
+
+    def __str__(self):
+        return f"Mail-{self.pk}"
+
+
+class MailRecipient(models.Model):
+    id = models.AutoField(primary_key=True, auto_created=True)
+    mail = models.ForeignKey(Mail, on_delete=models.CASCADE, null=False, related_name="recipients")
+    recipient = models.CharField(null=False, max_length=2048)
+
+    def __str__(self):
+        return f"MailRecipient-{self.pk}"
+
+    @property
+    def email(self):
+        return self.recipient
+
+    @property
+    def created(self):
+        return self.mail.created
+
+    @property
+    def mail_key(self):
+        return self.mail.key
+
+
+class MailRecipientAction(models.Model):
+    id = models.AutoField(primary_key=True, auto_created=True)
+    recipient = models.ForeignKey(MailRecipient, on_delete=models.CASCADE, null=False, related_name="actions")
+    created = models.DateTimeField(auto_now_add=True, editable=False)
+    action = models.CharField(null=False, max_length=2048)
+
+    def __str__(self):
+        return f"MailRecipientAction-{self.pk}"
+
+    @property
+    def recipient_email(self):
+        return self.recipient.recipient
+
+    @property
+    def recipient_mail_key(self):
+        return self.recipient.mail.key

django_mail_analytics/templates/django_mail_analytics/mail_list.html

@@ -0,0 +1,52 @@
+    <style type="text/css">
+tr:first-child > th {
+  border-bottom: 1px solid black;
+}
+{% comment %} tr:last-child > td {
+  border-bottom: 1px solid black;
+} {% endcomment %}
+    </style>
+
+
+
+<table width="100%" style="text-align:right; padding-inline:2em; border-spacing: 0.9em; ">
+  <tr width="100%">
+    <th>Date</th>
+    <th>Key</th>
+    <th>Subject</th>
+    <th>Success Rate</th>
+    <th>#Opened</th>
+    <th>#Openings</th>
+    <th>#Clicks</th>
+  </tr>
+{% for mail in page_obj %}
+  <tr>
+    <td>{{ mail.created }}</td>
+    <td>{{ mail.key|upper }}</td>
+    <td>{{ mail.subject }}</td>
+    <td>{{ mail.rate|stringformat:"d%%" }}</td>
+    <td>{{ mail.opened }} / {{ mail.sent }}</td>
+    <td>{{ mail.openings }}</td>
+    <td>{{ mail.clicks }}</td>
+  </tr>
+{% endfor %}
+</table>
+
+<br/>
+<div class="pagination" style="text-align:center;">
+  <span class="step-links">
+    {% if page_obj.has_previous %}
+    <a href="?page=1">&laquo; first</a>
+    <a href="?page={{ page_obj.previous_page_number }}">previous</a>
+    {% endif %}
+
+    <span class="current">
+      Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}.
+    </span>
+
+    {% if page_obj.has_next %}
+    <a href="?page={{ page_obj.next_page_number }}">next</a>
+    <a href="?page={{ page_obj.paginator.num_pages }}">last &raquo;</a>
+    {% endif %}
+  </span>
+</div>

django_mail_analytics/tests.py

@@ -0,0 +1,3 @@
+# from django.test import TestCase
+
+# Create your tests here.

django_mail_analytics/urls.py

@@ -0,0 +1,13 @@
+"""
+This module define url patterns for this app
+"""
+
+from django.urls import re_path
+
+from . import views
+
+urlpatterns = [
+    re_path(r"^i$", views.pixel, name="mail_pixel"),
+    re_path(r"^p$", views.proxy, name="mail_proxy"),
+    re_path(r"^l$", views.MailListView.as_view(), name="mail_list"),
+]

django_mail_analytics/views.py

@@ -0,0 +1,67 @@
+# Create your views here.
+
+
+from django.contrib.auth.mixins import PermissionRequiredMixin
+from django.db.models import Count, F, Q
+from django.http import HttpResponse, HttpResponseRedirect
+from django.views.generic import ListView
+
+from .mail import mail_settings, register_action
+from .models import Mail
+
+
+#def generate_pixel_bytes(request):
+#    # generate the pixel bytes from scratch
+#    import io
+#
+#    from PIL import Image
+#
+#    pixel = Image.new("RGBA", (1, 1), (255, 255, 255, 0))
+#    content = io.BytesIO()
+#    pixel.save(content, "PNG")
+#    pixel_bytes = content.getvalue()
+#    return pixel_bytes
+
+
+async def proxy(request):
+    q = request.GET.get("q", None)
+    url = request.GET.get("u", None)
+    if not url:
+        scheme = mail_settings()["SCHEME"]
+        domain = mail_settings()["DOMAIN"]
+        HttpResponseRedirect(f"{scheme}://{domain}/")
+
+    await register_action(q, url)
+    return HttpResponseRedirect(url)
+
+
+async def pixel(request):
+    q = request.GET.get("q", None)
+
+    # hardcode pixel value to save time, it never changes, use generate_pixel_bytes if you need to update
+    pixel_bytes = (
+        b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00"
+        b"\x00\x00\rIDATx\x9cc\xf8\xff\xff?\x03\x00\x08\xfc\x02\xfe\xa7\x9a\xa0\xa0\x00\x00\x00\x00IEND\xaeB`\x82"
+    )
+
+    await register_action(q)
+    return HttpResponse(content=pixel_bytes, content_type="image/png")
+
+
+class MailListView(PermissionRequiredMixin, ListView):
+    permission_required = ["is_staff"]
+
+    paginate_by = 25
+    model = Mail
+
+    def get_queryset(self):
+        opening = Q(recipients__actions__action="")
+        hasAction = Q(recipients__actions__isnull=False)
+        qs = Mail.objects.all()
+        qs = qs.annotate(opened=Count("recipients", filter=hasAction & opening, distinct=True))
+        qs = qs.annotate(sent=Count("recipients", distinct=True))
+        qs = qs.annotate(openings=Count("recipients__actions", filter=opening))
+        qs = qs.annotate(clicks=Count("recipients__actions", filter=~opening))
+        qs = qs.annotate(rate=(F("opened") / F("sent")) * 100)
+        qs = qs.order_by("-created")
+        return qs

django_mail_analytics-1.0.0.dist-info/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Loic Quertenmont
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_mail_analytics-1.0.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.1
+Name: django-mail-analytics
+Version: 1.0.0
+Summary: django package adding email tracking features.  Both email opening and link clicking are tracked.
+Author-email: Loic Quertenmont <loic@deeperanalytics.be>
+Maintainer-email: Loic Quertenmont <loic@deeperanalytics.be>
+License: MIT License
+        
+        Copyright (c) 2024-present Loic Quertenmont
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/quertenmont/django-mail-analytics
+Project-URL: Download, https://github.com/quertenmont/django-mail-analytics/releases
+Project-URL: Documentation, https://github.com/quertenmont/django-mail-analytics#readme
+Project-URL: Issues, https://github.com/quertenmont/django-mail-analytics/issues
+Project-URL: Funding, https://github.com/sponsors/quertenmont/
+Project-URL: Twitter, https://twitter.com/LoicQuertenmont
+Keywords: django,mail,analytics,tracking,tracker,python
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+
+[![](https://img.shields.io/pypi/pyversions/django-mail-analytics.svg?color=3776AB&logo=python&logoColor=white)](https://www.python.org/)
+[![](https://img.shields.io/pypi/djversions/django-mail-analytics?color=0C4B33&logo=django&logoColor=white&label=django)](https://www.djangoproject.com/)
+
+[![](https://img.shields.io/pypi/v/django-mail-analytics.svg?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/django-mail-analytics/)
+[![](https://static.pepy.tech/badge/django-mail-analytics/month)](https://pepy.tech/project/django-mail-analytics)
+[![](https://img.shields.io/github/stars/quertenmont/django-mail-analytics?logo=github&style=flat)](https://github.com/quertenmont/django-mail-analytics/stargazers)
+[![](https://img.shields.io/pypi/l/django-mail-analytics.svg?color=blue)](https://github.com/quertenmont/django-mail-analytics/blob/main/LICENSE.txt)
+
+[![](https://results.pre-commit.ci/badge/github/quertenmont/django-mail-analytics/main.svg)](https://results.pre-commit.ci/latest/github/quertenmont/django-mail-analytics/main)
+[![](https://img.shields.io/github/actions/workflow/status/quertenmont/django-mail-analytics/test-package.yml?branch=main&label=build&logo=github)](https://github.com/quertenmont/django-mail-analytics)
+[![](https://img.shields.io/codecov/c/gh/quertenmont/django-mail-analytics?logo=codecov)](https://codecov.io/gh/quertenmont/django-mail-analytics)
+[![](https://img.shields.io/codacy/grade/194566618f424a819ce43450ea0af081?logo=codacy)](https://www.codacy.com/app/quertenmont/django-mail-analytics)
+[![](https://img.shields.io/badge/code%20style-black-000000.svg?logo=python&logoColor=black)](https://github.com/psf/black)
+[![](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+
+
+# django-mail-analytics
+
+Simple python module that add email tracking features for both mail opening (via a hidden pixel) and for link clicks (via a redirecting proxy)
+-  This works only for email with an html body
+-  The changes to your code is minimal as we monkey patch the standard django.core.mail.EmailMessage object
+-  Three new models are added to save mail sent, mail recipients and mail recipient's action such as opening and link clicking
+
+---
+
+## Installation
+-   Run `pip install django-mail-analytics`
+-   Add `django_mail_analytics` to your installed INSTALLED_APPS
+-   Add `re_path(r"^m/", include("django_mail_analytics.urls"))` to your urls
+-   Add this to your settings:
+```
+MAIL_ANALYTICS = {
+    "DOMAIN": "localhost", #add the domain of your app to be used in the pixel/proxy url of your mail sent
+    "SCHEME": "http", #http or https
+  # "SALT": "my-salt", #comment to use global SECRET_KEY instead
+    "LENGTH": 6,  # minimal length of encoded id
+}
+```
+
+---
+
+## Usage
+
+All email sent with an html body will be modified on the fly to incorporate a pixel tracking and to rewrite link urls:
+
+```
+from django.core.mail import send_mail
+
+send_mail(
+    "Subject here",
+    "Here is the message.",
+    "from@example.com",
+    ["to@example.com"],
+    fail_silently=False,
+    html_message="""
+    <body>
+    <a href="https://google.com">link</a>
+    </body>
+    """,
+)
+```
+The above code will actually send an html body email that is rewritten like this:
+```
+<body>
+    <a href="http://localhost/m/p?q=OJe2wr&u=https%3A%2F%2Fgoogle.com">link</a>
+    <img src="http://localhost/m/i?q=OJe2wr" height="0px" width="0px"/>
+</body>
+```
+There is no perciple change for the user that receive the email.
+But as soon as it opens (or reopens) the email, we create a MailRecipientAction with an empty action.
+If the user clicks on the link we would create another MailRecipientAction with an action equal to the link url: "https://google.com" in this example.
+
+
+Every email send trigger the creation of a Mail object.
+In addition, a MailRecipient object is also created for every recipients of the email.
+
+Note, that multiple emails sharing the same "key" and sending "date" are merged together into a single Mail Object.
+So no need to worry about sending mass emails (they will only create one single Mail object).
+The email "key" is either the email subject OR the first recipient with a "@DMA" email address.  This recipient is ignored from the sending list, it's just an easy way to track mails of a given category.
+
+So typical usage is like this:
+```
+send_mail(
+    subject="subject",
+    message="message",
+    html_message="html_message,
+    from_email=None,
+    recipient_list=[user.email, f"EMAIL_KEY@DMA"],
+)
+```
+
+---
+
+## Admin
+
+There is a django admin for the three added models that can easilly be used to monitor your email success rate and typical use behaviour.
+
+---
+
+## Remarks
+
+Email were not developped for tracking in the first place.
+So adding a pixel tracking and link proxy is just a workaround to add tracking capabilities to email.
+One of the limitation of this workaround is that sending the email to multiple recipients doesn't allow to distinguish who among the recipients is currently opening the email... just that someone did it.
+Similarly if the email is forwarded to somebody else, we can only know that the email was opened a second time, but not that it's from a different people.
+
+---
+
+## Testing
+```bash
+# clone repository
+git clone https://github.com/quertenmont/django-mail-analytics.git && cd django_mail_analytics
+
+# create virtualenv and activate it
+python -m venv venv && . venv/bin/activate
+
+# upgrade pip
+python -m pip install --upgrade pip
+
+# install requirements
+pip install -r requirements.txt -r requirements-test.txt
+
+# install pre-commit to run formatters and linters
+pre-commit install --install-hooks
+
+# run tests
+tox
+# or
+python runtests.py
+# or
+python -m django test --settings "tests.settings"
+```
+---
+
+## License
+Released under [MIT License](LICENSE.txt).
+
+---
+
+## Supporting
+
+- :star: Star this project on [GitHub](https://github.com/quertenmont/django-mail-analytics)
+- :octocat: Follow me on [GitHub](https://github.com/quertenmont)
+- :blue_heart: Follow me on [Twitter](https://twitter.com/LoicQuertenmont)
+- :moneybag: Sponsor me on [Github](https://github.com/sponsors/quertenmont)

django_mail_analytics-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+django_mail_analytics/__init__.py,sha256=Rw7KzEMSJIlkafzbNsOa7qg9rZWLz8_fPtNefHRAVQ0,284
+django_mail_analytics/admin.py,sha256=6TH4jzxnW_XQ3q-sznleoX0DGPXXxQe60lI2Ba60jbo,4910
+django_mail_analytics/apps.py,sha256=4IBQdU2vWSLd5-LxuowZ6UNXcQIjcWoo4K94H2FKx40,380
+django_mail_analytics/mail.py,sha256=Fvltx0Nm-HkykmhqNDJz4oBf6reoxf_AueoWLkPSVck,4226
+django_mail_analytics/metadata.py,sha256=0ICHrRT1CdR0K9u7sjSDdlv6CRHfLVQjtwJodAMPkOU,341
+django_mail_analytics/models.py,sha256=6vU5gqO16HB7AQ7_slg70GMvjLEFLa6EXbSGRvEvsxo,1711
+django_mail_analytics/tests.py,sha256=oGgalLR6qiJdN-bHSH1ZLbRNhJHX_MyZtKsaR4jRy_Q,62
+django_mail_analytics/urls.py,sha256=7Co-SXyJLXgEnIEFyjt3qQYGwCRot2JuxtaMezFpI8E,301
+django_mail_analytics/views.py,sha256=z4buoekc0XaX3kq_xxCPVpTzjXqNti_YVibepNSvmII,2221
+django_mail_analytics/migrations/0001_initial.py,sha256=P7PBN9ygPdNa1yWfDDMqFASlwrWMSi87nki4IJiEZaA,1790
+django_mail_analytics/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_mail_analytics/templates/django_mail_analytics/mail_list.html,sha256=v6fx59myjzq4j8ocr4cTdkQfJ2aQQSMnYDDIloz1bXQ,1336
+django_mail_analytics-1.0.0.dist-info/LICENSE.txt,sha256=CJM8-vNzIH7SamshwlaQibTv41ZXEqGSwABj1uLM0tg,1081
+django_mail_analytics-1.0.0.dist-info/METADATA,sha256=D2KaeLIAiFgpVVxfkGFnghf7B4lWQY5RFEzmUaiwcV4,8812
+django_mail_analytics-1.0.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+django_mail_analytics-1.0.0.dist-info/top_level.txt,sha256=-HR_aWNYYGqN9ByZJK9ia9VfSEZ6C8ANeCiVE7kUYf0,22
+django_mail_analytics-1.0.0.dist-info/RECORD,,

django_mail_analytics-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_mail_analytics-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+django_mail_analytics