Skip to content

Latest commit

 

History

History
872 lines (627 loc) · 23.5 KB

python.md

File metadata and controls

872 lines (627 loc) · 23.5 KB

GOV.UK Notify Python client

This documentation is for developers interested in using this python client to integrate their government service with GOV.UK Notify.

Installation

pip install notifications-python-client

Getting started

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.

Send messages

Text message

Method

Click here to expand for more information. 
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.

Click here to expand for more information. 
{
  "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"
}]

Arguments

Click here to expand for more information.
phone_number

The phone number of the recipient, only required for sms notifications.

template_id

Find by clicking API info for the template you want to send.

reference

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.

personalisation

If a template has placeholders, you need to provide their values, for example:

personalisation={
    'first_name': 'Amala',
    'reference_number': '300241',
}

Email

Method

Click here to expand for more information. 
response = notifications_client.send_email_notification(
    email_address='the_email_address@example.com',
    template_id='f33517ff-2a88-4f6e-b855-c550268ce08a'
    personalisation=None,
    reference=None,
    email_reply_to_id=None
)

Response

If the request is successful, response will be a dict.

Click here to expand for more information. 
{
  "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": "the_service@gov.uk"
  },
  "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"
}]

Arguments

Click here to expand for more information
email_address

The email address of the recipient, only required for email notifications.

template_id

Find by clicking API info for the template you want to send.

reference

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.

email_reply_to_id

Optional. Specifies the identifier of the email reply-to address to set for the notification. The identifiers are found in your service Settings, when you 'Manage' your 'Email reply to addresses'.

If you omit this argument your default email reply-to address will be set for the notification.

personalisation

If a template has placeholders, you need to provide their values, for example:

personalisation={
    'first_name': 'Amala',
    'application_number': '300241',
}

Letter

Method

Click here to expand for more information. 
response = notifications_client.send_letter_notification(
    template_id='f33517ff-2a88-4f6e-b855-c550268ce08a',
    personalisation={
      'address_line_1': 'The Occupier',  # required
      'address_line_2': '123 High Street', # required
      'address_line_3': 'London',
      'postcode': 'SW14 6BH',  # required

      ... # any other optional address lines, or personalisation fields found in your template
    },
    reference=None
)

Response

If the request is successful, response will be a dict.

Click here to expand for more information. 
{
  "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 live of 10 requests per 20 seconds"
}]
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
400 [{
"error": "BadRequestError",
"message": "Cannot send letters with a team api key"
]}
400 [{
"error": "BadRequestError",
"message": "Cannot send letters 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"
}]

Arguments

Click here to expand for more information.
template_id

Find by clicking API info for the template you want to send.

reference

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.

personalisation

The letter must contain:

  • mandatory address fields
  • optional address fields if applicable
  • fields from template
personalisation={
    'address_line_1': 'The Occupier', 		# mandatory address field
    'address_line_2': 'Flat 2', 		# mandatory address field
    'address_line_3': '123 High Street', 	# optional address field
    'address_line_4': 'Richmond upon Thames', 	# optional address field
    'address_line_5': 'London', 		# optional address field
    'address_line_6': 'Middlesex', 		# optional address field
    'postcode': 'SW14 6BH', 			# mandatory address field
    'application_id': '1234', 			# field from template
    'application_date': '2017-01-01', 		# field from template
}

Get the status of one message

Method

Click here to expand for more information. 
response = notifications_client.get_notification_by_id(notification_id)

Response

If the request is successful, response will be a dict.

Click here to expand for more information. 
{
  "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", # required for letter
  "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"
}]

Get the status of all messages (with pagination)

Method

This will return one page of notifications (250) per call. Use the get_all_notifications_iterator to retrieve all notifications unpaginated.

Click here to expand for more information. 
response = notifications_client.get_all_notifications(template_type, status, reference, older_than)

Response

If the request is successful, response will be a dict.

Click here to expand for more information. 
{"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", # required for letter
      "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]"
}]

Arguments

Click here to expand for more information.
template_type

You can filter by:

  • email
  • sms
  • letter

You can omit this argument to ignore this filter.

status

email

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 statuses permanent-failure, temporary-failure and technical-failure.
  • permanent-failure - the provider was unable to deliver message, email does not exist; remove this recipient from your list.
  • temporary-failure - the provider was unable to deliver message, email box was full; 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.

text message

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 statuses permanent-failure, temporary-failure and technical-failure.
  • permanent-failure - the provider was unable to deliver message, phone number does not exist; remove this recipient from your list.
  • temporary-failure - the provider was unable to deliver message, 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.

letter

You can filter by:

  • accepted - the letter has been generated.
  • technical-failure - Notify had an unexpected error while sending to our printing provider

You can omit this argument to ignore this filter.

reference

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.

olderThanId

You can get the notifications older than a given Notification.notificationId.

You can omit this argument to ignore the filter.

Get the status of all messages (without pagination)

Method

Click here to expand for more information. 
response = get_all_notifications_iterator(status="sending")

Response

If the request is successful, response will be a <generator object> that will yield all messages.

Click here to expand for more information. 
<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]"
}]

Arguments

Click here to expand for more information.
template_type

You can filter by:

  • email
  • sms
  • letter

You can omit this argument to ignore this filter.

status

email

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 statuses permanent-failure, temporary-failure and technical-failure.
  • permanent-failure - the provider was unable to deliver message, email does not exist; remove this recipient from your list.
  • temporary-failure - the provider was unable to deliver message, email box was full; 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.

text message

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 statuses permanent-failure, temporary-failure and technical-failure.
  • permanent-failure - the provider was unable to deliver message, phone number does not exist; remove this recipient from your list.
  • temporary-failure - the provider was unable to deliver message, 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.

letter

You can filter by:

  • accepted - the letter has been generated.
  • technical-failure - Notify had an unexpected error while sending to our printing provider

You can omit this argument to ignore this filter.

reference

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.

Get a template by ID

Method

This will return the latest version of the template. Use get_template_version to retrieve a specific template version.

Click here to expand for more information. 
response = notifications_client.get_template(
    'template_id'
)

Response

If the request is successful, response will be a dict.

Click here to expand for more information. 
{
    "id": "template_id", # required
    "type": "sms" | "email" | "letter", # 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 or letter 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"
}]

Arguments

Click here to expand for more information.
template_id

Find by clicking API info for the template you want to send.

Get a template by ID and version

Method

Click here to expand for more information. 
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.

Click here to expand for more information. 
{
    "id": "template_id", # required
    "type": "sms" | "email" | "letter", # 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 or letter 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"
}]

Arguments

Click here to expand for more information.
template_id

Find by clicking API info for the template you want to send.

version

The version number of the template.

Get all templates

Method

This will return the latest version for each template.

Click here to expand for more information. 
response = notifications_client.get_all_templates(
    template_type=None # optional
)

See available template types

Response

If the request is successful, response will be a dict.

Click here to expand for more information. 
{
    "templates" : [
        {
            "id": "template_id", # required
            "type": "sms" | "email" | "letter", # 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 or letter 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" : []
}

Arguments

Click here to expand for more information.
template_type

If omitted all messages are returned. Otherwise you can filter by:

  • email
  • sms
  • letter

Generate a preview template

Method

Click here to expand for more information. 
response = notifications_client.post_template_preview(
    'template_id',
    personalisation={'name': 'chris'}
)

Response

If the request is successful, response will be a dict.

Click here to expand for more information. 
{
    "id": "notify_id", # required
    "type": "sms" | "email" | "letter", # required
    "version": "version", # integer required
    "body": "Body of the notification", # required
    "subject": "Subject of an email or letter 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]"
}]
400 [{
"error": "NoResultFound",
"message": "No result found"
}]

Arguments

Click here to expand for more information.
template_id

Find by clicking API info for the template you want to send.

personalisation

If a template has placeholders, you need to provide their values, for example:

personalisation={
    'first_name': 'Amala',
    'reference_number': '300241',
}