django package adding email tracking features. Both email opening and link clicking are tracked.

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

loic.quertenmont

These details have not been verified by PyPI

Project links

Project description

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

# 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.

Supporting

:star: Star this project on GitHub
:octocat: Follow me on GitHub
:blue_heart: Follow me on Twitter
:moneybag: Sponsor me on Github

Project details

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

loic.quertenmont

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

1.0.3

Nov 26, 2024

1.0.2

Oct 4, 2024

1.0.1

Oct 4, 2024

1.0.0

Oct 4, 2024

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_mail_analytics-1.0.3.tar.gz (15.4 kB view details)

Uploaded Nov 26, 2024 Source

Built Distribution

django_mail_analytics-1.0.3-py3-none-any.whl (13.3 kB view details)

Uploaded Nov 26, 2024 Python 3

File details

Details for the file django_mail_analytics-1.0.3.tar.gz.

File metadata

Download URL: django_mail_analytics-1.0.3.tar.gz
Upload date: Nov 26, 2024
Size: 15.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for django_mail_analytics-1.0.3.tar.gz
Algorithm	Hash digest
SHA256	`1c5bcdbedd355f99a057e1d859ec650e507d1d2dc80324503a991b58558b48b4`
MD5	`da6eedcc964ac10c7bacd3f76a6618cd`
BLAKE2b-256	`e243df0de6e272f595eeef476ac57e7dd63b3671ad83bc86b4ded581e219387f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_mail_analytics-1.0.3.tar.gz:

Publisher: create-release.yml on quertenmont/django-mail-analytics

Attestations:

Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: django_mail_analytics-1.0.3.tar.gz
- Subject digest: 1c5bcdbedd355f99a057e1d859ec650e507d1d2dc80324503a991b58558b48b4
- Sigstore transparency entry: 151681866
- Sigstore integration time: Nov 26, 2024

File details

Details for the file django_mail_analytics-1.0.3-py3-none-any.whl.

File metadata

Download URL: django_mail_analytics-1.0.3-py3-none-any.whl
Upload date: Nov 26, 2024
Size: 13.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for django_mail_analytics-1.0.3-py3-none-any.whl
Algorithm	Hash digest
SHA256	`045dde8e39ead1fae6c12fe14a3bbef8a8900435c3e63ba39f801a3bbba13c0e`
MD5	`7e08426b6b90e0b974271bd742715ab5`
BLAKE2b-256	`b1cf05dac9e35add8d97f69ab5c4d0688b36f76f60b5746b1454109b7ae6184f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_mail_analytics-1.0.3-py3-none-any.whl:

Publisher: create-release.yml on quertenmont/django-mail-analytics

Attestations:

Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: django_mail_analytics-1.0.3-py3-none-any.whl
- Subject digest: 045dde8e39ead1fae6c12fe14a3bbef8a8900435c3e63ba39f801a3bbba13c0e
- Sigstore transparency entry: 151681868
- Sigstore integration time: Nov 26, 2024