# 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.8, 3.9, 3.10 and 3.11
- Django 3.2, 4.1 and 4.2
## 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": "",
"docs_url": null,
"requires_python": ">=3.8,<3.12",
"maintainer_email": "",
"keywords": "email,Django",
"author": "Nick Smith",
"author_email": "nick.smith@torchbox.com",
"download_url": "https://files.pythonhosted.org/packages/78/00/9464333cd980ca181d283b7f14f0c4f91ea932126c8a1de6a106aaffb84a/django_gov_notify-0.4.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.8, 3.9, 3.10 and 3.11\n- Django 3.2, 4.1 and 4.2\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.4.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": "1504bee30186627b48685f03b99eab77a958aaaa0f23c8714193e7c53119106d",
"md5": "f1cac89b1280a28b570c6837204ba17b",
"sha256": "228c289f77f8f027b65c52e26bbcbaa856f0ae5e80f7d6b625d7768ddaf33d11"
},
"downloads": -1,
"filename": "django_gov_notify-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f1cac89b1280a28b570c6837204ba17b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.12",
"size": 5908,
"upload_time": "2023-11-13T11:35:02",
"upload_time_iso_8601": "2023-11-13T11:35:02.235665Z",
"url": "https://files.pythonhosted.org/packages/15/04/bee30186627b48685f03b99eab77a958aaaa0f23c8714193e7c53119106d/django_gov_notify-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "78009464333cd980ca181d283b7f14f0c4f91ea932126c8a1de6a106aaffb84a",
"md5": "5b600764976b22c91994e8ce473caccd",
"sha256": "393852a4c4e6223aa07631432b103e42ad2c9765cc7c6069febfb7ba659402bb"
},
"downloads": -1,
"filename": "django_gov_notify-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "5b600764976b22c91994e8ce473caccd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.12",
"size": 4799,
"upload_time": "2023-11-13T11:35:04",
"upload_time_iso_8601": "2023-11-13T11:35:04.056246Z",
"url": "https://files.pythonhosted.org/packages/78/00/9464333cd980ca181d283b7f14f0c4f91ea932126c8a1de6a106aaffb84a/django_gov_notify-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-13 11:35:04",
"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
