# django-gov-notify, a GOV.UK Notify flavoured Django email backend
django-gov-notify provides Django integration with the [GOV.UK Notify](https://www.notifications.service.gov.uk/) service for sending emails and SMS messages. [Python Client Documentation](https://docs.notifications.service.gov.uk/python.html).
This is implemented as a custom Django email backend. It presents a similar internal API to standard Django email backends, but with some restrictions:
- GOV.UK Notify emails are sent to one recipient each. CC: and BCC: fields are not supported.
- A single email 'message' with multiple recipients will result in multiple individual API calls to GOV.UK Notify, each message being sent to a single recipient. The backend will still report back `1`, as per Django's default behaviour.
- Attachments are not (at the moment) supported.
- Custom headers are not supported.
- To configure a 'reply-to' address, you must first configure such an address in the GOV.UK Notify admin interface.
- The 'from' address field is not supported. This must be configured within the GOV.UK Notify admin interface.
- Preformatted emails are expected to be configured in the service admin dashboard as Markdown templates with placeholders.
- The email body is interpreted as very limited Markdown. On testing, it seems that variables are not interpreted as markdown, or maybe mangled, e.g. `_test_` was emailed as `*test*`.
## Compatibility
django-gov-notify supports:
- Python 3.9, 3.10, 3.11 and 3.12
- Django 4.2, 5.0 and 5.1
## Installation
Using [pip](https://pip.pypa.io/en/stable/):
```bash
$ pip install django-gov-notify
```
Using [Poetry](https://python-poetry.org/)
```bash
$ poetry add django-gov-notify
```
## Configuration
In your Django project's settings:
```python
EMAIL_BACKEND = "django_gov_notify.backends.NotifyEmailBackend"
```
You will need at least one email template ID, with a plain template:
> Subject: ((subject))
> Body: ((body))
Set the Django settings:
- `GOVUK_NOTIFY_API_KEY` (NB _not_ GOV_UK…)
- `GOVUK_NOTIFY_PLAIN_EMAIL_TEMPLATE_ID`
This plain template ID setting, and template IDs passed to the NotifyEmailMessage class, use string representations of the UUID keys.
## Usage
### Sending an email using a template
Configure the template in the [GOV.UK Notify dashboard](https://www.notifications.service.gov.uk/):
> Subject: Message about ((topic))
> Body: Hello ((first name)), your reference is ((ref number))
Create an email message, supplying the template ID and a `personalisation` dictionary (this should also include any variables defined in the template subject):
```python
from django_gov_notify.message import NotifyEmailMessage
message = NotifyEmailMessage(
to=["recipient@example.com"],
template_id="43573f75-80e7-402f-b308-e5f1066fbd6f",
personalisation={
"topic": "The Prisoner",
"first name": "Patrick",
"ref number": "6",
},
)
message.send()
```
Note that in this case a subject and body are not required, nor permitted, because the personalisation dict won't know how to do anything with them.
### Sending an email using the default (blank) template
This assumes you have configured a blank template with the parameters
> Subject: ((subject))
> Body: ((body))
```python
from django_gov_notify.message import NotifyEmailMessage
message = NotifyEmailMessage(
subject="Test subject", body="Test message content", to=["recipient@example.com"]
)
message.send()
```
Note that in this case a subject and body are required, and you must not pass the `template_id` or `personalisation` kwargs.
### Sending an email using the `send_mail` shortcut function
Use it in the normal fashion, including a 'from' address that will be discarded:
```python
from django.utils.mail import send_mail
send_mail("Subject", "Message content", "from@example.com", ["recipient@example.com"])
```
This will use the blank template ID configured as `settings.GOVUK_NOTIFY_PLAIN_EMAIL_TEMPLATE_ID`. Attachments, custom headers, and BCC recipients are not supported.
## Contributing
To work on this repository locally:
- install: `poetry install`
- run tests: `poetry run python runtests.py`
Raw data
{
"_id": null,
"home_page": "https://github.com/nimasmi/django-gov-notify",
"name": "django-gov-notify",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "email, Django",
"author": "Nick Smith",
"author_email": "nick.smith@torchbox.com",
"download_url": "https://files.pythonhosted.org/packages/62/8f/72d44b7a48617ca2d11a4b68a6f091a997e7dd3ad97b2bd5336e316d8b65/django_gov_notify-0.6.0.tar.gz",
"platform": null,
"description": "# django-gov-notify, a GOV.UK Notify flavoured Django email backend\n\n\n\ndjango-gov-notify provides Django integration with the [GOV.UK Notify](https://www.notifications.service.gov.uk/) service for sending emails and SMS messages. [Python Client Documentation](https://docs.notifications.service.gov.uk/python.html).\n\nThis is implemented as a custom Django email backend. It presents a similar internal API to standard Django email backends, but with some restrictions:\n\n- GOV.UK Notify emails are sent to one recipient each. CC: and BCC: fields are not supported.\n- A single email 'message' with multiple recipients will result in multiple individual API calls to GOV.UK Notify, each message being sent to a single recipient. The backend will still report back `1`, as per Django's default behaviour.\n- Attachments are not (at the moment) supported.\n- Custom headers are not supported.\n- To configure a 'reply-to' address, you must first configure such an address in the GOV.UK Notify admin interface.\n- The 'from' address field is not supported. This must be configured within the GOV.UK Notify admin interface.\n- Preformatted emails are expected to be configured in the service admin dashboard as Markdown templates with placeholders.\n- The email body is interpreted as very limited Markdown. On testing, it seems that variables are not interpreted as markdown, or maybe mangled, e.g. `_test_` was emailed as `*test*`.\n\n## Compatibility\n\ndjango-gov-notify supports:\n\n- Python 3.9, 3.10, 3.11 and 3.12\n- Django 4.2, 5.0 and 5.1\n\n## Installation\n\nUsing [pip](https://pip.pypa.io/en/stable/):\n\n```bash\n$ pip install django-gov-notify\n```\n\nUsing [Poetry](https://python-poetry.org/)\n\n```bash\n$ poetry add django-gov-notify\n```\n\n## Configuration\n\nIn your Django project's settings:\n\n```python\nEMAIL_BACKEND = \"django_gov_notify.backends.NotifyEmailBackend\"\n```\n\nYou will need at least one email template ID, with a plain template:\n\n> Subject: ((subject)) \n> Body: ((body))\n\nSet the Django settings:\n\n- `GOVUK_NOTIFY_API_KEY` (NB _not_ GOV_UK\u2026)\n- `GOVUK_NOTIFY_PLAIN_EMAIL_TEMPLATE_ID`\n\nThis plain template ID setting, and template IDs passed to the NotifyEmailMessage class, use string representations of the UUID keys.\n\n## Usage\n\n### Sending an email using a template\n\nConfigure the template in the [GOV.UK Notify dashboard](https://www.notifications.service.gov.uk/):\n\n> Subject: Message about ((topic)) \n> Body: Hello ((first name)), your reference is ((ref number))\n\nCreate an email message, supplying the template ID and a `personalisation` dictionary (this should also include any variables defined in the template subject):\n\n```python\nfrom django_gov_notify.message import NotifyEmailMessage\n\nmessage = NotifyEmailMessage(\n to=[\"recipient@example.com\"],\n template_id=\"43573f75-80e7-402f-b308-e5f1066fbd6f\",\n personalisation={\n \"topic\": \"The Prisoner\",\n \"first name\": \"Patrick\",\n \"ref number\": \"6\",\n },\n)\nmessage.send()\n```\n\nNote that in this case a subject and body are not required, nor permitted, because the personalisation dict won't know how to do anything with them.\n\n### Sending an email using the default (blank) template\n\nThis assumes you have configured a blank template with the parameters\n\n> Subject: ((subject)) \n> Body: ((body))\n\n```python\nfrom django_gov_notify.message import NotifyEmailMessage\n\nmessage = NotifyEmailMessage(\n subject=\"Test subject\", body=\"Test message content\", to=[\"recipient@example.com\"]\n)\nmessage.send()\n```\n\nNote that in this case a subject and body are required, and you must not pass the `template_id` or `personalisation` kwargs.\n\n### Sending an email using the `send_mail` shortcut function\n\nUse it in the normal fashion, including a 'from' address that will be discarded:\n\n```python\nfrom django.utils.mail import send_mail\n\nsend_mail(\"Subject\", \"Message content\", \"from@example.com\", [\"recipient@example.com\"])\n```\n\nThis will use the blank template ID configured as `settings.GOVUK_NOTIFY_PLAIN_EMAIL_TEMPLATE_ID`. Attachments, custom headers, and BCC recipients are not supported.\n\n## Contributing\n\nTo work on this repository locally:\n\n- install: `poetry install`\n- run tests: `poetry run python runtests.py`\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "A GOV.UK Notify flavoured Django email backend",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/nimasmi/django-gov-notify",
"Repository": "https://github.com/nimasmi/django-gov-notify"
},
"split_keywords": [
"email",
" django"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c4cb160e87337261952666f83b724be7df1829bcf6d85e6fb828df4b70d6066",
"md5": "f0418ce92899c01cdfa72acf78057d69",
"sha256": "eba507a740d709ed8cffcd2d7599b40bca08b9078dc9a53cf4029a8f95bc6789"
},
"downloads": -1,
"filename": "django_gov_notify-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f0418ce92899c01cdfa72acf78057d69",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 6830,
"upload_time": "2024-10-25T12:39:49",
"upload_time_iso_8601": "2024-10-25T12:39:49.222135Z",
"url": "https://files.pythonhosted.org/packages/2c/4c/b160e87337261952666f83b724be7df1829bcf6d85e6fb828df4b70d6066/django_gov_notify-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "628f72d44b7a48617ca2d11a4b68a6f091a997e7dd3ad97b2bd5336e316d8b65",
"md5": "14c9df7ad6e3095a56efc4d4271b5564",
"sha256": "989368bc13eb1db59ed39354525a039bd6078312ec6510cfa6d2d123de68c2eb"
},
"downloads": -1,
"filename": "django_gov_notify-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "14c9df7ad6e3095a56efc4d4271b5564",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 5706,
"upload_time": "2024-10-25T12:39:50",
"upload_time_iso_8601": "2024-10-25T12:39:50.436625Z",
"url": "https://files.pythonhosted.org/packages/62/8f/72d44b7a48617ca2d11a4b68a6f091a997e7dd3ad97b2bd5336e316d8b65/django_gov_notify-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 12:39:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nimasmi",
"github_project": "django-gov-notify",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-gov-notify"
}
JSON
