This documentation is for developers interested in using this PHP client to integrate their government service with GOV.UK Notify.
- Installation
- Getting started
- Send messages
- Get the status of one message
- Get the status of all messages
- Get a template by ID
- Get a template by ID and version
- Get all templates
- Generate a preview template
- Development
- License
The Notify PHP Client can be installed with Composer. Run this command:
composer require php-http/guzzle6-adapter alphagov/notifications-php-clientThe Notify PHP Client is based on a PSR-7 HTTP model. You therefore need to pick your preferred HTTP Client library to use.
We will show examples here using the Guzzle v6 Adapter.
Setup instructions are also available for Curl and Guzzle v5.
Assuming you’ve installed the package via Composer, the Notify PHP Client will be available via the autoloader.
Create a (Guzzle v6 based) instance of the Client using:
$notifyClient = new \Alphagov\Notifications\Client([
'apiKey' => '{your api key}',
'httpClient' => new \Http\Adapter\Guzzle6\Client
]);Generate an API key by logging in to GOV.UK Notify and going to the API integration page.
Click here to expand for more information.
The method signature is:
sendSms( $phoneNumber, $templateId, array $personalisation = array(), $reference = '', $smsSenderId = NULL )An example request would look like:
try {
$response = $notifyClient->sendSms(
'+447777111222',
'df10a23e-2c6d-4ea5-87fb-82e520cbf93a', [
'name' => 'Betty Smith',
'dob' => '12 July 1968'
],
'unique_ref123',
'862bfaaf-9f89-43dd-aafa-2868ce2926a9'
);
} catch (NotifyException $e){}If the request is successful, response will be an array.
Click here to expand for more information.
[
"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/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda"
]
]Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:
exc->getCode() |
exc->getErrors() |
|---|---|
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"}] |
Click here to expand for more information.
The mobile number the SMS notification is sent to.
Find by clicking API info for the template you want to send.
An optional identifier you generate if you don’t want to use Notify’s id. It can be used to identify a single notification or a batch of notifications.
If a template has placeholders, you need to provide their values, for example:
personalisation = [
'name' => 'Betty Smith',
'dob' => '12 July 1968'
]Otherwise the parameter can be omitted.
Optional. Specifies the identifier of the sms sender to set for the notification. The identifiers are found in your service Settings, when you 'Manage' your 'Text message sender'.
If you omit this argument your default sms sender will be set for the notification.
Click here to expand for more information.
The method signature is:
sendEmail( $emailAddress, $templateId, array $personalisation = array(), $reference = '', $emailReplyToId = NULL )An example request would look like:
try {
$response = $notifyClient->sendEmail(
'[email protected]',
'df10a23e-2c0d-4ea5-87fb-82e520cbf93c', [
'name' => 'Betty Smith',
'dob' => '12 July 1968'
],
'unique_ref123',
'862bfaaf-9f89-43dd-aafa-2868ce2926a9'
);
} catch (NotifyException $e){}If the request is successful, response will be an array.
Click here to expand for more information.
[
"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" => "[email protected]"
],
"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/service/your_service_id/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda"
]
]Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:
exc->getCode() |
exc->getErrors() |
|---|---|
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"}] |
Click here to expand for more information.
The email address the email notification is sent to.
Find by clicking API info for the template you want to send.
If a template has placeholders you need to provide their values. For example:
personalisation = [
'name' => 'Betty Smith',
'dob' => '12 July 1968'
]Otherwise the parameter can be omitted.
An optional identifier you generate if you don’t want to use Notify’s id. It can be used to identify a single notification or a batch of notifications.
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.
Click here to expand for more information.
The method signature is:
sendLetter( $templateId, array $personalisation = array(), $reference = '' )An example request would look like:
try {
$response = $notifyClient->sendEmail(
'df10a23e-2c0d-4ea5-87fb-82e520cbf93c',
[
'name'=>'Fred',
'address_line_1' => 'Foo',
'address_line_2' => 'Bar',
'postcode' => 'Baz'
],
'unique_ref123'
);
} catch (NotifyException $e){}If the request is successful, response will be an array.
Click here to expand for more information.
[
"id" => "bfb50d92-100d-4b8b-b559-14fa3b091cda",
"reference" => "unique_ref123",
"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/ceb50d92-100d-4b8b-b559-14fa3b091cd",
"template" => [
"id" => "ceb50d92-100d-4b8b-b559-14fa3b091cda",
"version" => 1,
"uri" => "https://api.notificaitons.service.gov.uk/service/your_service_id/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda"
],
"scheduled_for" => null
]Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:
exc->getCode() |
exc->getErrors() |
|---|---|
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"}] |
Click here to expand for more information.
Find by clicking API info for the template you want to send.
If a template has placeholders you need to provide their values. For example:
personalisation = [
'name' => 'Betty Smith',
'dob' => '12 July 1968'
]Otherwise the parameter can be omitted.
An optional identifier you generate if you don’t want to use Notify’s id. It can be used to identify a single notification or a batch of notifications.
Click here to expand for more information.
The method signature is:
getNotification( $notificationId )An example request would look like:
try {
$response = $notifyClient->getNotification( 'c32e9c89-a423-42d2-85b7-a21cd4486a2a' );
} catch (NotifyException $e){}If the request is successful, response will be an array .
Click here to expand for more information.
[
"id" => "notify_id",
"body" => "Hello Foo",
"subject" => "null|email_subject",
"reference" => "client reference",
"email_address" => "email address",
"phone_number" => "phone number",
"line_1" => "full name of a person or company",
"line_2" => "123 The Street",
"line_3" => "Some Area",
"line_4" => "Some Town",
"line_5" => "Some county",
"line_6" => "Something else",
"postcode" => "postcode",
"type" => "sms|letter|email",
"status" => "current status",
"template" => [
"version" => 1,
"id" => 1,
"uri" => "/template/{id}/{version}"
],
"created_at" => "created at",
"sent_at" => "sent to provider at",
]Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:
error["status_code"] |
error["message"] |
|---|---|
404 |
[{"error": "NoResultFound","message": "No result found"}] |
400 |
[{"error": "ValidationError","message": "id is not a valid UUID"}] |
Click here to expand for more information.
The method signature is:
listNotifications( array $filters = array() )An example request would look like:
$response = $notifyClient->listNotifications([
'older_than' => 'c32e9c89-a423-42d2-85b7-a21cd4486a2a',
'reference' => 'weekly-reminders',
'status' => 'delivered',
'template_type' => 'sms'
]);If the request is successful, response will be an array.
Click here to expand for more information.
[
"notifications":
[
"id" => "notify_id",
"reference" => "client reference",
"email_address" => "email address",
"phone_number" => "phone number",
"line_1" => "full name of a person or company",
"line_2" => "123 The Street",
"line_3" => "Some Area",
"line_4" => "Some Town",
"line_5" => "Some county",
"line_6" => "Something else",
"postcode" => "postcode",
"type" => "sms | letter | email",
"status" => sending | delivered | permanent-failure | temporary-failure | technical-failure
"template" => [
"version" => 1,
"id" => 1,
"uri" => "/template/{id}/{version}"
],
"created_at" => "created at",
"sent_at" => "sent to provider at",
],
…
],
"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 Alphagov\Notifications\Exception\NotifyException:
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": "Apple is not one of [sms, email, letter]"}] |
Click here to expand for more information.
If omitted all messages are returned. Otherwise you can filter to retrieve all notifications older than the given notification id.
If omitted all messages are returned. Otherwise you can filter by:
emailsmsletter
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 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 statusespermanent-failure,temporary-failureandtechnical-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- Notify is in the process of printing and posting the lettertechnical-failure- Notify had an unexpected error while sending to our printing provider
You can omit this argument to ignore this filter.
This is the reference you gave at the time of sending the notification. This can be omitted to ignore the filter.
Click here to expand for more information.
$response = $notifyClient->getTemplate( 'templateId' );If the request is successful, response will be an array.
Click here to expand for more information.
{
"id" => "template_id",
"type" => "sms|email|letter",
"created_at" => "created at",
"updated_at" => "updated at",
"version" => "version",
"created_by" => "[email protected]",
"body" => "body",
"subject" => "null|email_subject"
}error["status_code"] |
error["errors"] |
|---|---|
404 |
[{"error" => "NoResultFound","message" => "No result found"}] |
Click here to expand for more information.
Find by clicking API info for the template you want to send.
Click here to expand for more information.
$response = $notifyClient->getTemplateVersion( 'templateId', 1 );If the request is successful, response will be an array.
Click here to expand for more information.
[
"id" => "template_id",
"type" => "sms|email|letter",
"created_at" => "created at",
"updated_at" => "updated at",
"version" => "version",
"created_by" => "[email protected]",
"body" => "body",
"subject" => "null|email_subject"
]error["status_code"] |
error["errors"] |
|---|---|
404 |
[{"error" => "NoResultFound","message" => "No result found"}] |
Click here to expand for more information.
Find by clicking API info for the template you want to send.
The version number of the template
Click here to expand for more information.
$this->getAllTemplates(
$template_type // optional
);This will return the latest version for each template
If the request is successful, response will be an array.
Click here to expand for more information.
[
"templates" => [
[
"id" => "template_id",
"type" => "sms|email|letter",
"created_at" => "created at",
"updated_at" => "updated at",
"version" => "version",
"created_by" => "[email protected]",
"body" => "body",
"subject" => "null|email_subject"
],
[
... another template
]
]
]If no templates exist for a template type or there no templates for a service, the response will be a Dictionarywith an emptytemplates` list element:
[
"templates" => []
]Click here to expand for more information.
If omitted all messages are returned. Otherwise you can filter by:
emailsmsletter
Click here to expand for more information.
$personalisation = [ "foo" => "bar" ];
$this->previewTemplate( $templateId, $personalisation );If the request is successful, response will be an array.
Click here to expand for more information.
[
"id" => "notify_id",
"type" => "sms|email|letter",
"version" => "version",
"body" => "Hello bar" // with substitution values,
"subject" => "null|email_subject"
]error["status_code"] |
error["errors"] |
|---|---|
400 |
[{"error" => "BadRequestError","message" => "Missing personalisation => [name]"}] |
404 |
[{"error" => "NoResultFound","message" => "No result found"}] |
Click here to expand for more information.
Find by clicking API info for the template you want to send.
If a template has placeholders you need to provide their values. For example:
$personalisation = [
'first_name' => 'Amala',
'reference_number' => '300241',
];Otherwise the parameter can be omitted or null can be passed in its place.
There are unit and integration tests that can be run to test functionality of the client.
To run the unit tests:
vendor/bin/phpspec run spec/unit/ --format=pretty --verboseTo run the integration tests:
vendor/bin/phpspec run spec/integration/ --format=pretty --verboseTo run both sets of tests:
vendor/bin/phpspec run --format=prettyThe Notify PHP Client is released under the MIT license, a copy of which can be found in LICENSE.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent