GOV.UK Notify PHP client

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

Installation

The Notify PHP Client can be installed with Composer. Run this command:

composer require php-http/guzzle6-adapter alphagov/notifications-php-client

PSR-7 HTTP

The 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.

Getting started

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.

Send messages

Text message

Method

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){}

Response

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"` `}]`

Arguments

Click here to expand for more information.

`$phoneNumber`

The mobile number the SMS notification is sent to.

`$templateId`

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

`$reference`

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.

`$personalisation`

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.

`smsSenderId`

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.

Email

Method

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( 
        'betty@example.com', 
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c', [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968'
        ],
        'unique_ref123',
        '862bfaaf-9f89-43dd-aafa-2868ce2926a9'
        );

} catch (NotifyException $e){}

Response

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" => "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/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"` `}]`

Arguments

Click here to expand for more information.

`$emailAddress`

The email address the email notification is sent to.

`$templateId`

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 = [
    'name' => 'Betty Smith',
    'dob'  => '12 July 1968'
]

Otherwise the parameter can be omitted.

`$reference`

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.

`$emailReplyToId`

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.

Letter

Method

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){}

Response

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"` `}]`

Arguments

Click here to expand for more information.

`templateId`

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 = [
    'name' => 'Betty Smith',
    'dob'  => '12 July 1968'
]

Otherwise the parameter can be omitted.

`reference`

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.

Get the status of one message

Method

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){}

Response

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"` `}]`

Arguments

Click here to expand for more information.

`$notificationId`

The ID of the notification.

Get the status of all messages

Method

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'
    ]);

Response

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]"` `}]`

Arguments

Click here to expand for more information.

`older_than`

If omitted all messages are returned. Otherwise you can filter to retrieve all notifications older than the given notification id.

`template_type`

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

email
sms
letter

`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 - Notify is in the process of printing and posting the letter
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. This can be omitted to ignore the filter.

Get a template by ID

Method

Click here to expand for more information.

    $response = $notifyClient->getTemplate( 'templateId' );

Response

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" => "someone@example.com",
    "body" => "body",
    "subject" => "null|email_subject"
}

`error["status_code"]`	`error["errors"]`
`404`	`[{` `"error" => "NoResultFound",` `"message" => "No result found"` `}]`

Arguments

Click here to expand for more information.

`templateId`

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 = $notifyClient->getTemplateVersion( 'templateId', 1 );

Response

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" => "someone@example.com",
    "body" => "body",
    "subject" => "null|email_subject"
]

`error["status_code"]`	`error["errors"]`
`404`	`[{` `"error" => "NoResultFound",` `"message" => "No result found"` `}]`

Arguments

Click here to expand for more information.

`templateId`

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

`version`

The version number of the template

Get all templates

Method

Click here to expand for more information.

    $this->getAllTemplates(
      $template_type  // optional
    );

This will return the latest version for each template

Response

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" => "someone@example.com",
            "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"  => []
]

Arguments

Click here to expand for more information.

`$templateType`

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.

    $personalisation = [ "foo" => "bar" ];
    $this->previewTemplate( $templateId, $personalisation );

Response

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"` `}]`

Arguments

Click here to expand for more information.

`$templateId`

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',
];

Otherwise the parameter can be omitted or null can be passed in its place.

Development

Tests

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 --verbose

To run the integration tests:

vendor/bin/phpspec run spec/integration/ --format=pretty --verbose

To run both sets of tests:

vendor/bin/phpspec run --format=pretty

License

The Notify PHP Client is released under the MIT license, a copy of which can be found in LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.github		.github
docker		docker
docs		docs
script		script
spec		spec
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE.txt		LICENSE.txt
Makefile		Makefile
README.md		README.md
composer.json		composer.json
phpspec.yml		phpspec.yml

License

dgudgeon/notifications-php-client

Folders and files

Latest commit

History

Repository files navigation

GOV.UK Notify PHP client

Table of Contents

Installation

PSR-7 HTTP

Getting started

Send messages

Text message

Method

Response

Arguments

$phoneNumber

$templateId

$reference

$personalisation

smsSenderId

Email

Method

Response

Arguments

$emailAddress

$templateId

$personalisation

$reference

$emailReplyToId

Letter

Method

Response

Arguments

templateId

personalisation

reference

Get the status of one message

Method

Response

Arguments

$notificationId

Get the status of all messages

Method

Response

Arguments

older_than

template_type

status

reference

Get a template by ID

Method

Response

Arguments

templateId

Get a template by ID and version

Method

Response

Arguments

templateId

version

Get all templates

Method

Response

Arguments

$templateType

Generate a preview template

Method

Response

Arguments

$templateId

$personalisation

Development

Tests

License

About

Resources

License

Stars

Watchers

`$phoneNumber`

`$templateId`

`$reference`

`$personalisation`

`smsSenderId`

`$emailAddress`

`$templateId`

`$personalisation`

`$reference`

`$emailReplyToId`

`templateId`

`personalisation`

`reference`

`$notificationId`

`older_than`

`template_type`

`status`

`reference`

`templateId`

`templateId`

`version`

`$templateType`

`$templateId`

`$personalisation`