| Name | django-mail-analytics JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | django package adding email tracking features. Both email opening and link clicking are tracked. |
| upload_time | 2024-10-04 09:51:17 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| 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. |
| keywords |
django
mail
analytics
tracking
tracker
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://www.python.org/)
[](https://www.djangoproject.com/)
[](https://pypi.org/project/django-mail-analytics/)
[](https://pepy.tech/project/django-mail-analytics)
[](https://github.com/quertenmont/django-mail-analytics/stargazers)
[](https://github.com/quertenmont/django-mail-analytics/blob/main/LICENSE.txt)
[](https://results.pre-commit.ci/latest/github/quertenmont/django-mail-analytics/main)
[](https://github.com/quertenmont/django-mail-analytics)
[](https://codecov.io/gh/quertenmont/django-mail-analytics)
[](https://www.codacy.com/app/quertenmont/django-mail-analytics)
[](https://github.com/psf/black)
[](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)
Raw data
{
"_id": null,
"home_page": null,
"name": "django-mail-analytics",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": "Loic Quertenmont <loic@deeperanalytics.be>",
"keywords": "django, mail, analytics, tracking, tracker, python",
"author": null,
"author_email": "Loic Quertenmont <loic@deeperanalytics.be>",
"download_url": "https://files.pythonhosted.org/packages/c7/00/62cfbc6889d3fb457bd42a465a493f3c138c27b3c30f705ebe3f1180616e/django_mail_analytics-1.0.2.tar.gz",
"platform": null,
"description": "[](https://www.python.org/)\n[](https://www.djangoproject.com/)\n\n[](https://pypi.org/project/django-mail-analytics/)\n[](https://pepy.tech/project/django-mail-analytics)\n[](https://github.com/quertenmont/django-mail-analytics/stargazers)\n[](https://github.com/quertenmont/django-mail-analytics/blob/main/LICENSE.txt)\n\n[](https://results.pre-commit.ci/latest/github/quertenmont/django-mail-analytics/main)\n[](https://github.com/quertenmont/django-mail-analytics)\n[](https://codecov.io/gh/quertenmont/django-mail-analytics)\n[](https://www.codacy.com/app/quertenmont/django-mail-analytics)\n[](https://github.com/psf/black)\n[](https://github.com/astral-sh/ruff)\n\n\n\n# django-mail-analytics\n\nSimple python module that add email tracking features for both mail opening (via a hidden pixel) and for link clicks (via a redirecting proxy)\n- This works only for email with an html body\n- The changes to your code is minimal as we monkey patch the standard django.core.mail.EmailMessage object\n- Three new models are added to save mail sent, mail recipients and mail recipient's action such as opening and link clicking\n\n---\n\n## Installation\n- Run `pip install django-mail-analytics`\n- Add `django_mail_analytics` to your installed INSTALLED_APPS\n- Add `re_path(r\"^m/\", include(\"django_mail_analytics.urls\"))` to your urls\n- Add this to your settings:\n```\nMAIL_ANALYTICS = {\n \"DOMAIN\": \"localhost\", #add the domain of your app to be used in the pixel/proxy url of your mail sent\n \"SCHEME\": \"http\", #http or https\n # \"SALT\": \"my-salt\", #comment to use global SECRET_KEY instead\n \"LENGTH\": 6, # minimal length of encoded id\n}\n```\n\n---\n\n## Usage\n\nAll email sent with an html body will be modified on the fly to incorporate a pixel tracking and to rewrite link urls:\n\n```\nfrom django.core.mail import send_mail\n\nsend_mail(\n \"Subject here\",\n \"Here is the message.\",\n \"from@example.com\",\n [\"to@example.com\"],\n fail_silently=False,\n html_message=\"\"\"\n <body>\n <a href=\"https://google.com\">link</a>\n </body>\n \"\"\",\n)\n```\nThe above code will actually send an html body email that is rewritten like this:\n```\n<body>\n <a href=\"http://localhost/m/p?q=OJe2wr&u=https%3A%2F%2Fgoogle.com\">link</a>\n <img src=\"http://localhost/m/i?q=OJe2wr\" height=\"0px\" width=\"0px\"/>\n</body>\n```\nThere is no perciple change for the user that receive the email.\nBut as soon as it opens (or reopens) the email, we create a MailRecipientAction with an empty action.\nIf 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.\n\n\nEvery email send trigger the creation of a Mail object.\nIn addition, a MailRecipient object is also created for every recipients of the email.\n\nNote, that multiple emails sharing the same \"key\" and sending \"date\" are merged together into a single Mail Object.\nSo no need to worry about sending mass emails (they will only create one single Mail object).\nThe 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.\n\nSo typical usage is like this:\n```\nsend_mail(\n subject=\"subject\",\n message=\"message\",\n html_message=\"html_message,\n from_email=None,\n recipient_list=[user.email, f\"EMAIL_KEY@DMA\"],\n)\n```\n\n---\n\n## Admin\n\nThere is a django admin for the three added models that can easilly be used to monitor your email success rate and typical use behaviour.\n\n---\n\n## Remarks\n\nEmail were not developped for tracking in the first place.\nSo adding a pixel tracking and link proxy is just a workaround to add tracking capabilities to email.\nOne 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.\nSimilarly 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.\n\n---\n\n## Testing\n```bash\n# clone repository\ngit clone https://github.com/quertenmont/django-mail-analytics.git && cd django_mail_analytics\n\n# create virtualenv and activate it\npython -m venv venv && . venv/bin/activate\n\n# upgrade pip\npython -m pip install --upgrade pip\n\n# install requirements\npip install -r requirements.txt -r requirements-test.txt\n\n# install pre-commit to run formatters and linters\npre-commit install --install-hooks\n\n# run tests\ntox\n# or\npython runtests.py\n# or\npython -m django test --settings \"tests.settings\"\n```\n---\n\n## License\nReleased under [MIT License](LICENSE.txt).\n\n---\n\n## Supporting\n\n- :star: Star this project on [GitHub](https://github.com/quertenmont/django-mail-analytics)\n- :octocat: Follow me on [GitHub](https://github.com/quertenmont)\n- :blue_heart: Follow me on [Twitter](https://twitter.com/LoicQuertenmont)\n- :moneybag: Sponsor me on [Github](https://github.com/sponsors/quertenmont)\n",
"bugtrack_url": null,
"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. ",
"summary": "django package adding email tracking features. Both email opening and link clicking are tracked.",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://github.com/quertenmont/django-mail-analytics#readme",
"Download": "https://github.com/quertenmont/django-mail-analytics/releases",
"Funding": "https://github.com/sponsors/quertenmont/",
"Homepage": "https://github.com/quertenmont/django-mail-analytics",
"Issues": "https://github.com/quertenmont/django-mail-analytics/issues",
"Twitter": "https://twitter.com/LoicQuertenmont"
},
"split_keywords": [
"django",
" mail",
" analytics",
" tracking",
" tracker",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6841d9aa78461fce84ae3d58b45acd1c2c4af84ae105fe0c1c2ca5b1230e00e5",
"md5": "a97a171b0801d8c10403e5e92e515674",
"sha256": "027543270410c445f18b7c2caba78cf58c604361ff43b44d275172d7a46f2223"
},
"downloads": -1,
"filename": "django_mail_analytics-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a97a171b0801d8c10403e5e92e515674",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13274,
"upload_time": "2024-10-04T09:51:15",
"upload_time_iso_8601": "2024-10-04T09:51:15.516188Z",
"url": "https://files.pythonhosted.org/packages/68/41/d9aa78461fce84ae3d58b45acd1c2c4af84ae105fe0c1c2ca5b1230e00e5/django_mail_analytics-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c70062cfbc6889d3fb457bd42a465a493f3c138c27b3c30f705ebe3f1180616e",
"md5": "f1f885c4a34c024134b1d4849dab10aa",
"sha256": "1a43022ac83d9f0187db909b235aaf9ca2fdc84839553fea73a0b1547e9dc85c"
},
"downloads": -1,
"filename": "django_mail_analytics-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "f1f885c4a34c024134b1d4849dab10aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15300,
"upload_time": "2024-10-04T09:51:17",
"upload_time_iso_8601": "2024-10-04T09:51:17.030493Z",
"url": "https://files.pythonhosted.org/packages/c7/00/62cfbc6889d3fb457bd42a465a493f3c138c27b3c30f705ebe3f1180616e/django_mail_analytics-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-04 09:51:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quertenmont",
"github_project": "django-mail-analytics#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "django-mail-analytics"
}
