How We Integrated with GOV.UK Notify

Matt Inamdar

Matt Inamdar

It was pleasant. Like a garden tea party with the queen.

Heads up though, this post quickly gets technical.

Back in July last year our Connected Kingston project was granted access to the GOV.UK Notify service.

GOV.UK Notify is a fantastic service offered by the Government Digital Service which allows you to programmatically send transactional emails and SMS messages from your application (there’s also the ability to send physical letters directly to a user’s address, though our use case didn’t need this).

It also offers several SDKs (Software Development Kits) which allow you to easily integrate your application’s backend systems with their API (Application Programming Interface).

Our backend system for Connected Kingston is built using one of our favourite PHP frameworks, Laravel, which has an email engine included out of the box. However it was not as simple as you may expect to integrate this engine with GOV.UK Notify - and that’s to do with the way emails are sent.

01 Templates

GOV.UK Notify takes a different approach to content templates

Most solutions for programmatically sending emails, like SMTP (Simple Mail Transfer Protocol) or even HTTP (HyperText Transfer Protocol) expect you to send the entire email message from your system or application. This means if you want the flexibility of email templates (think mail merge), you must fill in the placeholder values on your own system before sending the entire email.

There’s nothing wrong with this solution, and that’s generally how it’s been done for years. However GOV.UK Notify takes a different approach… They require you to set-up the templates on GOV.UK Notify itself. That way when you want to send an email, you only need to provide values for the placeholders. Then GOV.UK Notify fills in the placeholders before sending the email. The main benefit of this approach is that content templates can be changed by non-tech people via web interface.

GOV.UK Notify keeps a log of all notifications sent through their service within the last seven days for you. This proved very useful when debugging notification issues. GOV.UK Notify also takes care of deliverability, meaning we can just send the emails and SMS messages without concern for the underlying infrastructure. If issues occur on sending, they get logged and flagged on the service for our investigation.

03 Spreadsheet

Our Solution

Since there’s no support for the content template approach that GOV.UK Notify uses with the default Laravel email engine, we had to build our own.

It’s also worth mentioning that Laravel does not have an out of the box SMS engine in the same way it does for emails. It supports sending by SMS but for a specific use case outside our scope.

We therefore developed two engines, one for emails and one for SMS. These use GOV.UK Notify’s SDK to integrate smoothly, and also provide a means to run a fully automated test suite with mock services in place of GOV.UK Notify.

More Learning to Share

You can view the implementation of these engines in the open source Github repository. We’re also looking at open sourcing our solution as a standalone PHP dependency. And as our journey into working to GDS and Better Digital Services standards deepens, we’re keen to share more of our learning and efforts with the wider community.

Overall it’s been a pleasant experience integrating with this GOV.UK Notify, and we would recommend all local governments make use of the service where they can.