Use GOV.UK Notify to prototype emails and text messages

You can use GOV.UK Notify to send text messages or emails when users interact with your prototype. For example you could send users a confirmation email at the end of a journey.

Sign up for a GOV.UK Notify account

You need an account before you can use GOV.UK Notify to send text messages or emails.

If you have a government email address you can sign up for a GOV.UK Notify account.

Getting an API key

An API key is like a password that lets your prototype talk to Notify. Your prototype sends this key every time it asks Notify to do something.

To get a key:

  • sign into GOV.UK Notify
  • go to the ‘API integration’ page
  • select ‘API keys’
  • select the ‘Create an API’ button
  • choose the ‘Team and guest list’ option
  • copy the key to your clipboard

Saving your key on your computer

This will let your prototype talk to Notify while it’s running on your computer.

  1. Create a file called .env in your prototype folder.

  2. To save the key on your computer, add this line to the end of the .env file in your prototype (where xxxxxxx is the key you’ve copied from Notify):

NOTIFYAPIKEY=xxxxxxx

Your prototype will load the key from your .env file. If you don’t have a .env file then run your prototype (with the npm start command) and it will create one for you.

Saving the key on Heroku

This will let your prototype talk to Notify if it’s running on Heroku.

To save the key on Heroku, go to the settings page of your app, click ‘Reveal config vars’ and fill in the 2 textboxes like this (where xxxxxxx is the key you’ve copied from Notify):

KEY          | VALUE
-------------|----------
NOTIFYAPIKEY | xxxxxxx

Keeping your key safe

It’s important that you keep your key secret. If you put it in the .env file it’s safe – that file isn’t published on GitHub. If you do accidentally publish your key somewhere you will need to sign into Notify and revoke it.

Add the Notify code to your prototype

  1. In the terminal, start your prototype.
  2. In your browser, go to the Plugins section of Manage your prototype (opens in a new tab).
  3. Install Notifications node client from the Available plugins list.
If the Notifications node client plugin is not available
You can update to the latest version of the Prototype Kit or in the terminal run:

npm install notifications-node-client

In your code editor, add this code to the top of routes.js:

var NotifyClient = require('notifications-node-client').NotifyClient,
    notify = new NotifyClient(process.env.NOTIFYAPIKEY);

Sending your first email

Make a page with a form to collect the user’s email address. For example:

{% extends "layouts/main.html" %}

{% block content %}

  <div class="govuk-grid-row">
    <div class="govuk-grid-column-two-thirds">
      <form class="form" method="post">

        {{ govukInput({
          label: {
            text: "Email Address"
          },
          id: "email-address",
          name: "emailAddress",
          type: "email",
          autocomplete: "email",
          spellcheck: false
        }) }}

        {{ govukButton({
          text: "Continue"
        })}}

      </form>
    </div>
  </div>
{% endblock %}

Save this page as email-address-page.html.

Then add this code to app/routes.js at the end of the file.

// The URL here needs to match the URL of the page that the user is on
// when they type in their email address
router.post('/email-address-page', function (req, res) {

  notify.sendEmail(
    // this long string is the template ID, copy it from the template
    // page in GOV.UK Notify. It’s not a secret so it’s fine to put it
    // in your code.
    'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    // `emailAddress` here needs to match the name of the form field in
    // your HTML page
    req.body.emailAddress
  );

  // This is the URL the users will be redirected to once the email
  // has been sent
  res.redirect('/confirmation-page');

});

Testing it out

Now when you type your email address into the page and press the green button you should get an email. You should also be able to see the email you’ve sent on the GOV.UK Notify dashboard.

Because your account is in trial mode you’ll only be able to send emails to yourself. If you’re doing user research you can add the participants email addresses to the ‘guest list’ in GOV.UK Notify. This will let you send them emails too. You’ll need to collect their email addresses and get consent to use them before doing your research.

More things you can do with GOV.UK Notify

Documentation for using the GOV.UK Notify API