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
- Technical dashboard
- Product dashboard
- How content is matched to subscriber lists
- Courtesy copies Google group
- Provides a way to view replicas of every immediate email notification generated in production.
- Works by the group being subscribed to the “all-government-publishing-updates” list (here).
- How to receive emails in Integration and Staging
Email system apps
-
- 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).
-
- 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.
-
- Listens to the Publishing API message queue for
majorchanges to content. - Communicates with Email Alert API API to trigger sending emails.
- Listens to the Publishing API message queue for
-
- 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 https://email-alert-api-public.publishing.service.gov.uk (similarly for Integration and Staging).