Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 10 Jan 2022

Email notifications: how they work

High-level overview

The purpose of the email notifications system is to inform users when content they are interested in is added to or changed on GOV.UK. Users can subscribe to receive updates for an area of interest, such as a topic, government department, or a set of search results. Current subscriptions to individual content items are not supported.

Update September 2019: the email system also now supports highly customised subscriptions for users completing the Brexit Checker, which operates in isolation from the rest of GOV.UK, and specifies its own notifications. More information can be found in the ADR for these changes.

Types of email

The email notification system generates 3 different types of email. These are transactional, immediate and digest.

Transactional emails are sent to confirm a new subscription, and to authenticate an existing subscriber so they can manage their subscriptions.

Immediate emails are generated shortly after the email system receives a content change, or a message, that corresponds to a user’s immediate subscription. It’s worth noting that “immediate” is a somewhat misleading name as these emails can sometimes take a long time (hours) to be sent when the system is busy.

Digest emails are generated daily and weekly for subscribers who have opted to have their updates sent to them in batches. These collate all of a subscriber’s subscriptions into a single summary of all the relevant content changes and messages that occurred over the preceding day or week.

Useful resources

Email system apps

  • Finder Frontend

    • Provides a UI to sign up to filterable search results.
  • Travel Advice Publisher / Specialist Publisher

    • Use Email Alert API directly to send email (tech debt).
  • Email Alert Frontend

    • Provides a UI to sign up to static pages e.g. a taxon.
    • Provides a UI for a user to manage their subscriptions.
    • Communicates with Email Alert API to make changes.
  • Email Alert Service

    • Listens to the Publishing API message queue for major changes to content.
    • Communicates with Email Alert API API to trigger sending emails.
  • Email Alert API

    • Stores data about subscribers and the emails we send to them.
    • Provides APIs for working with subscriptions and sending emails.
    • Sends email using GOV.UK Notify, and deals with spam reports.

Communication from Email Alert API to Notify is done via a HTTP API which is authenticated by an API key. Communication from Notify to Email Alert API is authenticated with Signon and a bearer token. Email Alert API is an internal application, so to enable callbacks two endpoints are exposed publicly through (similarly for Integration and Staging).