Toggle menu


GOV.UK Notify is a service developed by the Government Digital Service. Registered public bodies create templates (similar to Handlebars templates) which can be used when sending out email, SMS and physical letters.

Worker Configuration Properties

As well as the standard properties set in the API server configuration file sent from iCM, the GovNotify worker supports a single property that holds your GovNotify API keys.

notifyAPIKeysArray, requiredAn array of objects defining a list of named GovNotify API keys
notifyAPIKeys[n].nameString, requiredThe name of the API key. This is used to refer to the API key when making a call to the worker
notifyAPIKeys[n].notifyAPIKeyString, requiredThe API key to use to make calls to the GovNotify service
notifyAPIKeys[n].defaultBoolean, optionalIf true then this notifyAPIKey will be used if no apiKeyName is specified in the call to the worker


    "name": "govnotify",
    "instances": 2,
    "notifyAPIKeys": [{
        "name": "GossTest",
        "notifyAPIKey": "goss_key-00000000-0000-0000-0000",
        "default": true
    }, {
        "name": "AnotherKey",
        "notifyAPIKey": "another_key-00000000-0000-0000-0000"

Personalisation and Templates

Many of the methods make use of templates and personalisation to create messages to send. The template provides the general format of the message while the personalisation provides the values that fit into the template. 

For example, a template may provide the following:

Hello ((name)),
This is an example. The day of the week is ((day)).

You could then provide the following personalisation:

"personalisation": {
    "name": "John",
    "day": "Thursday"

When sending a letter you must also include the delivery address in the personalisation object. The following fields can be included:

"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



Sends an email to the provided email address.


Sends an SMS to the provided number.


Sends an letter to the provided address.


Gets the status of a message as identified by its ID.


Gets the statuses of all messages.


Gets the details of a template.


Gets the details of a specific version of a template.


Gets the details of all of the templates.


Retrieves a template and populates it with the data provided in the personalisation object.


Retrieves the 250 most recent received text messages.

Share this page

Facebook icon Twitter icon email icon


print icon