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

email-alert-api: Send a bulk email

Sometimes it may be necessary to send a bulk email to many subscribers at once. There is a Rake task in email-alert-api to perform this task and it's available as a job in Jenkins.

1. Prepare the content

You'll need:

  • Email subject line
  • Email body text

The body text can contain a limited subset of markdown. A footer will be automatically appended to the body text. The footer will have links to unsubscribe and manage subscriptions. We should always provide users with these options, to help avoid our emails being marked as spam.

Any occurrence of %LISTURL% in the body text will be substituted with the URL of the subscriber list, or an empty string if it has none. This is useful when sending the same email across many lists, where the content of the email needs to link to the specific page on GOV.UK associated with the list. You should check the lists you want to send a bulk email for, to see if they have a URL populated (it's a recent addition).

2. Get the subscriber lists

Next you'll need to get the IDs of all the subscriber lists to send the email out to. This will require querying the email-alert-api SubscriberList model.

If you have the mailing list's slug (e.g. from the query string on the email signup pages):

> SubscriberList.find_by(slug: "your-slug").id

For a more complex query, for example to get the IDs of all the subscriber lists for travel advice, you could use the following query:

> SubscriberList.where("links->'countries' IS NOT NULL").pluck(:id)

3. Send a test email

Use the Send bulk emails job in Staging to send the email.

Make sure you know how to receive emails in Staging.

4. Send the real email

Use the Send bulk emails job in Production to send the email.