pip install notifications-python-clientfrom notifications_python_client.notifications import NotificationsAPIClient
notifications_client = NotificationsAPIClient(api_key)Generate an API key by logging in to GOV.UK Notify and going to the API integration page.
response = notifications_client.send_sms_notification(
phone_number='+447900900123',
template_id='ceb50d92-100d-4b8b-b559-14fa3b091cda',
personalisation=None,
reference=None
)Response
If the request is successful, response will be a dict:
{
"id": "bfb50d92-100d-4b8b-b559-14fa3b091cda",
"reference": None,
"content": {
"body": "Some words",
"from_number": "40604"
},
"uri": "https://api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd",
"template": {
"id": "ceb50d92-100d-4b8b-b559-14fa3b091cda",
"version": 1,
"uri": "https://api.notifications.service.gov.uk/v2/template/bfb50d92-100d-4b8b-b559-14fa3b091cda"
}
}Otherwise the client will raise a HTTPError:
| `error.status_code` | `error.message` |
|---|---|
429 |
[{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
|
400 |
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
|
400 |
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode
- see https://www.notifications.service.gov.uk/trial-mode"
}]
|
response = notifications_client.send_email_notification(
email_address='the_email_address@example.com',
template_id='bfb50d92-100d-4b8b-b559-14fa3b091cda'
personalisation=None,
reference=None
)Response
If the request is successful, response will be a dict:
{
"id": "bfb50d92-100d-4b8b-b559-14fa3b091cda",
"reference": None,
"content": {"subject": "Licence renewal",
"body": "Dear Bill, your licence is due for renewal on 3 January 2016.",
"from_email": "the_service@gov.uk"
},
"uri": "https://api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd",
"template": {
"id": "ceb50d92-100d-4b8b-b559-14fa3b091cda",
"version": 1,
"uri": "https://api.notificaitons.service.gov.uk/v2/template/bfb50d92-100d-4b8b-b559-14fa3b091cda"
}
}Otherwise the client will raise a HTTPError:
| `error.status_code` | `error.message` |
|---|---|
429 |
[{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
|
400 |
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
|
400 |
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode
- see https://www.notifications.service.gov.uk/trial-mode"
}]
|
The phone number of the recipient, only required for sms notifications.
The email address of the recipient, only required for email notifications.
Find by clicking API info for the template you want to send.
An optional identifier you generate. The reference can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.
You can omit this argument if you do not require a reference for the notification.
If a template has placeholders, you need to provide their values, for example:
personalisation={
'first_name': 'Amala',
'reference_number': '300241',
}response = notifications_client.get_notification_by_id(notification_id)Response
If the request is successful, response will be a dict:
{
"id": "notify_id", # required
"reference": "client reference", # optional
"email_address": "email address", # required for emails
"phone_number": "phone number", # required for sms
"line_1": "full name of a person or company", # required for letter
"line_2": "123 The Street", # optional
"line_3": "Some Area", # optional
"line_4": "Some Town", # optional
"line_5": "Some county", # optional
"line_6": "Something else", # optional
"postcode": "postcode", # required for letter
"type": "sms|letter|email", # required
"status": "current status", # required
"template": {
"version": 1 # template version num # required
"id": 1 # template id # required
"uri": "/v2/template/{id}/{version}", # required
},
"body": "Body of the notification",
"subject": "Subject of an email notification or None if an sms message"
"created_at": "created at", # required
"sent_at": " sent to provider at", # optional
"completed_at:" "date the notification is delivered or failed" # optional
}Otherwise the client will raise a HTTPError:
| `error.status_code` | `error.message` |
|---|---|
404 |
[{
"error": "NoResultFound",
"message": "No result found"
}]
|
400 |
[{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]
|
This will return one page of notifications (250) per call. Use the get_all_notifications_iterator to retrieve all notifications unpaginated.
response = notifications_client.get_all_notifications(template_type, status, reference, older_than)Response
If the request is successful, response will be a dict:
{"notifications":
[{
"id": "notify_id", # required
"reference": "client reference", # optional
"email_address": "email address", # required for emails
"phone_number": "phone number", # required for sms
"line_1": "full name of a person or company", # required for letter
"line_2": "123 The Street", # optional
"line_3": "Some Area", # optional
"line_4": "Some Town", # optional
"line_5": "Some county", # optional
"line_6": "Something else", # optional
"postcode": "postcode", # required for letter
"type": "sms | letter | email", # required
"status": sending | delivered | permanent-failure | temporary-failure | technical-failure # required
"template": {
"version": 1 # template version num # required
"id": 1 # template id # required
"uri": "/v2/template/{id}/{version}", # required
},
"body": "Body of the notification",
"subject": "Subject of an email notification or None if an sms message"
"created_at": "created at", # required
"sent_at": " sent to provider at", # optional
"completed_at:" "date the notification is delivered or failed" # optional
},
…
],
"links": {
"current": "/notifications?template_type=sms&status=delivered",
"next": "/notifications?other_than=last_id_in_list&template_type=sms&status=delivered"
}
}Otherwise the client will raise a HTTPError:
| `error.status_code` | `error.message` |
|---|---|
400 |
[{
'error': 'ValidationError',
'message': 'bad status is not one of [created, sending, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure]'
}]
|
400 |
[{
"error": "ValidationError",
"message": "Apple is not one of [sms, email, letter]"
}]
|
You can filter by:
emailsmsletter
You can omit this argument to ignore this filter.
You can filter by:
sending- the message is queued to be sent by the provider.delivered- the message was successfully delivered.failed- this will return all failure statusespermanent-failure,temporary-failureandtechnical-failure.permanent-failure- the provider was unable to deliver message, email or phone number does not exist; remove this recipient from your list.temporary-failure- the provider was unable to deliver message, email box was full or the phone was turned off; you can try to send the message again.technical-failure- Notify had a technical failure; you can try to send the message again.
You can omit this argument to ignore this filter.
This is the reference you gave at the time of sending the notification. The reference can be a unique identifier for the notification or an identifier for a batch of notifications.
You can omit this argument to ignore the filter.
You can get the notifications older than a given Notification.notificationId.
You can omit this argument to ignore the filter.
response = get_all_notifications_iterator(status="sending")Response
If the request is successful, response will be a <generator object> that will yield all messages:
<generator object NotificationsAPIClient.get_all_notifications_iterator at 0x1026c7410>Otherwise the client will raise a HTTPError:
| `error.status_code` | `error.message` |
|---|---|
400 |
[{
'error': 'ValidationError',
'message': 'bad status is not one of [created, sending, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure]'
}]
|
400 |
[{
"error": "ValidationError",
"message": "Apple is not one of [sms, email, letter]"
}]
|
You can filter by:
emailsmsletter
You can omit this argument to ignore this filter.
You can filter by:
sending- the message is queued to be sent by the provider.delivered- the message was successfully delivered.failed- this will return all failure statusespermanent-failure,temporary-failureandtechnical-failure.permanent-failure- the provider was unable to deliver message, email or phone number does not exist; remove this recipient from your list.temporary-failure- the provider was unable to deliver message, email box was full or the phone was turned off; you can try to send the message again.technical-failure- Notify had a technical failure; you can try to send the message again.
You can omit this argument to ignore this filter.
This is the reference you gave at the time of sending the notification. The reference can be a unique identifier for the notification or an identifier for a batch of notifications.
This will return the latest version of the template. Use get_template_version to retrieve a specific template version
response = notifications_client.get_template(
'template_id'
)Response
If the request is successful, response will be a dict:
{
"id": "template_id", # required
"type": "sms" | "email", # required
"created_at": "created at", # required
"updated_at": "updated at", # required
"version": "version", # integer required
"created_by": "someone@example.com", # email required
"body": "Body of the notification", # required
"subject": "Subject of an email notification or None if an sms message"
}Otherwise the client will raise a HTTPError:
| `error.status_code` | `error.message` |
|---|---|
404 |
[{
"error": "NoResultFound",
"message": "No result found"
]}
|
response = notifications_client.get_template_version(
'template_id',
1 # integer required for version number
)Response
If the request is successful, response will be a dict:
{
"id": "template_id", # required
"type": "sms" | "email", # required
"created_at": "created at", # required
"updated_at": "updated at", # required
"version": "version", # integer required
"created_by": "someone@example.com", # email required
"body": "Body of the notification", # required
"subject": "Subject of an email notification or None if an sms message"
}Otherwise the client will raise a HTTPError:
| `error.status_code` | `error.message` |
|---|---|
404 |
[{
"error": "NoResultFound",
"message": "No result found"
]}
|
response = notifications_client.get_all_templates(
template_type=None # optional
)This will return the latest version for each template
Response
If the request is successful, response will be a dict:
{
"templates" : [
{
"id": "template_id", # required
"type": "sms" | "email", # required
"created_at": "created at", # required
"updated_at": "updated at", # required
"version": "version", # integer required
"created_by": "someone@example.com", # email required
"body": "Body of the notification", # required
"subject": "Subject of an email notification or None if an sms message"
},
{
... another template
}
]
}If no templates exist for a template type or there no templates for a service, the response will be a dict with an empty templates list element:
{
"templates" : []
}response = notifications_client.post_template_preview(
'template_id',
personalisation={'name': 'chris'}
)
Response
If the request is successful, response will be a dict:
{
"id": "notify_id", # required
"type": "sms" | "email", # required
"version": "version", # integer required
"body": "Body of the notification", # required
"subject": "Subject of an email notification or None if an sms message"
} Otherwise the client will raise a HTTPError:
| `error.status_code` | `error.message` |
|---|---|
400 |
[{
"error": "BadRequestError",
"message": "Missing personalisation: [name]"
]}
|
404 |
[{
"error": "NoResultFound",
"message": "No result found"
]}
|