pip install notifications-python-client
from 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='f33517ff-2a88-4f6e-b855-c550268ce08a',
personalisation=None,
reference=None
)
Response
If the request is successful, response
will be a dict
:
{
"id": "740e5834-3a29-46b4-9a6f-16142fde533a",
"reference": None,
"content": {
"body": "Some words",
"from_number": "40604"
},
"uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
"template": {
"id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
"version": 1,
"uri": "https://api.notifications.service.gov.uk/v2/template/ceb50d92-100d-4b8b-b559-14fa3b091cd"
}
}
Otherwise the client will raise a HTTPError
:
`error.status_code` | `error.message` |
---|---|
429 |
[{ "error": "RateLimitError", "message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds" }] |
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='[email protected]',
template_id='f33517ff-2a88-4f6e-b855-c550268ce08a'
personalisation=None,
reference=None
)
Response
If the request is successful, response
will be a dict
:
{
"id": "740e5834-3a29-46b4-9a6f-16142fde533a",
"reference": None,
"content": {
"subject": "Licence renewal",
"body": "Dear Bill, your licence is due for renewal on 3 January 2016.",
"from_email": "[email protected]"
},
"uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
"template": {
"id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
"version": 1,
"uri": "https://api.notifications.service.gov.uk/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
}
}
Otherwise the client will raise a HTTPError
:
`error.status_code` | `error.message` |
---|---|
429 |
[{ "error": "RateLimitError", "message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds" }] |
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_letter_notification(
template_id='f33517ff-2a88-4f6e-b855-c550268ce08a'
personalisation={
'address_line_1': 'Her Majesty The Queen', # required
'address_line_2': 'Buckingham Palace', # required
'address_line_3': 'London',
'postcode': 'SW1 1AA', # required
... # any other personalisation found in your template
},
reference=None
)
Response
If the request is successful, response
will be a dict
:
{
"id": "740e5834-3a29-46b4-9a6f-16142fde533a",
"reference": None,
"content": {
"subject": "Licence renewal",
"body": "Dear Bill, your licence is due for renewal on 3 January 2016.",
},
"uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
"template": {
"id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
"version": 1,
"uri": "https://api.notifications.service.gov.uk/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
}
"scheduled_for": None
}
Otherwise the client will raise a HTTPError
:
`error.status_code` | `error.message` |
---|---|
429 |
[{ "error": "RateLimitError", "message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds" }] |
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" }] |
400 |
[{ "error": "ValidationError", "message": "personalisation address_line_1 is a required property" }] |
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',
}
If you are sending a letter, you will need to provide the letter fields in the format "address_line_#"
, for example:
personalisation={
'address_line_1': 'The Occupier',
'address_line_2': '123 High Street',
'address_line_3': 'London',
'postcode': 'SW14 6BH',
'first_name': 'Amala',
'reference_number': '300241',
}
The fields "address_line_1"
, "address_line_2"
and "postcode"
are required.
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:
email
sms
letter
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-failure
andtechnical-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:
email
sms
letter
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-failure
andtechnical-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": "[email protected]", # 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": "[email protected]", # 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": "[email protected]", # 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" ]} |