email-alert-api: Support tasks
Users can manage email subscribers via the administration interface on GOV.UK. Support tickets coming through to 2ndline where the user is unaware of this, or needs guidance, can be assigned to "2nd Line--User Support Escalation".
Note
This applies only to emails sent by GOV.UK. Drug safety updates are sent manually by MHRA, who manage their own service using Govdelivery. We do not have access to this.
If it is not possible for changes to be managed by the user, it is
possible for changes to be made manually. The following rake tasks should be
run using the kubectl command, as described in the EKS documentation. They are split into several sections below:
Individual subscriber tasks
Change a subscriber's email address
This task changes a subscriber's email address.
$ kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:change_email_address[<old_email_address>, <new_email_address>]'
View subscriber's recent emails
This task shows the most recent emails for the given user.
It takes two parameters: email_address (required), and limit (optional).
limit defaults to 10, but you can override this if you need to see more of
the user's history.
$ kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:view_emails[<email_address>,<limit>]'
View subscriber's subscriptions
This task shows you all of the active and inactive subscriptions for a given user.
$ kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:view_subscriptions[<email_address>]'
Unsubscribe a subscriber from a specific subscription
This task unsubscribes one subscriber from a subscription, given an email address and a subscriber list slug. You can find out the slug of the subscriber list by running the view_subscriptions rake task above.
$ kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:unsubscribe_single_subscription[<email_address>,<subscriber_list_slug>]'
Unsubscribe a subscriber from all emails
This task unsubscribes one subscriber from everything they have subscribed to.
$ kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:unsubscribe_all_subscriptions[<email_address>]'
Email confirmations
Send a test email
To send a test email to an email address (doesn't have to be subscribed to anything):
$ kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:send_test_email[<email_address>]'
Note This won't actually send out emails in non-production environments by default. See this doc on receiving emails in Integration and Staging.
Check email(s) have been sent by Notify by email ID
You can check if an email has been successfully sent by Notify by email ID. You can get the email ID via logs, or if you know the email address you can run the support:view_emails rake task first to get the list of most recent emails for a subscriber.
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:get_notifications_from_notify_by_email_id[email_id]'
Get sent/delivered stats for a specific Content ID
This will output information on the number of sent/failed email requests to Notify, and a break down by delivery status from Notify. For more information see the callback statuses from Notify.
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:emails:stats_for_content_id[<CONTENT ID>,<start_date (optional)>,<end_date (optional)>]'
If a start_date and an end_date is not provided, the date range will be a week from today. The date format should be in ISO8601 format (YYYY-MM-DD).
Resend failed emails
There are two Rake tasks available to resend emails which didn't send for whatever reason and ended up in the failed state. This is most useful after an incident to resend all emails that failed with a technical failure.
Using a date range
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:resend_failed_emails:by_date[<from_date>,<to_date>]'
The date format should be in ISO8601 format (YYYY-MM-DD), for example 2020-01-01T10:00:00Z.
Depending on the number of emails to send, the Rake task can take a few minutes to run.
Using email IDs
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:resend_failed_emails:by_id[<email_one_id>,<email_two_id>]'
Bulk subscription tasks
Send a bulk email to all subscribers for a specific subscription
See the bulk email doc.
Unsubscribe all subscribers from a specific subscription
This task unsubscribes all active subscribers from a subscription, given a subscriber list slug.
$ kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'support:unsubscribe_all_subscribers_from_subscription[<subscriber_list_slug>]'
Reports
Get a subscriber list CSV report by slug
To see a csv report for the number of subscribers for a given list:
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake SLUGS=<list_slug> 'report:csv_subscriber_lists[<on_date>] '
The date should be in ISO8601 format (YYYY-MM-DD), for example 2020-01-01.
Find subscriber lists by title match
This will return the full title and slug for each subscriber list that contains the string provided. This can be useful if you need to find out how many subscriber lists there are for a particular organisation, or in preparation of updating a subscriber list.
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:find_subscriber_list_by_title[<title>] '
Get the number of subscribers for a subscriber list by month
This rake task requires a URL to get the subscriber count for the 1st of each month:
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:subscriber_count_list[<path>, <start_date (optional)>, <end_date (optional)>]'
The path should be the full path on gov.uk (for instance /government/statistics/examples if the page you're interested in is https://www.gov.uk/government/statistics/examples)
If the start_date and end_date are not provided it will only get the subscriber count for the current month.
Get a simple count of subscribers to a list
Warning
This is called "simple" because it only gets subscriber lists for a direct path. There may still be subscriptions by topic or link, so finding an empty or missing subcription list does not mean that no-one will receive email updates about that page! See below for a more detailed description of how to get the subscriber list. It also won't work that well if the path is a finder. See below for better tasks for finders or detailed subscriber lists.
To see a simple count of the number of subscribers for a given list by URL:
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:subscriber_list_subscriber_count[<path>,<active_on_date (optional)>]'
To see a simple count of the number of subscribers for a given list by slug:
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:subscriber_list_by_slug_subscriber_count[<path>]'
Both of the rake tasks above will report on the number of active subscriptions for a given path.
The path should be the full path on gov.uk (for instance /government/statistics/examples if the page you're interested in is https://www.gov.uk/government/statistics/examples)
You can also pass it a active_on_date which will count how many active subscriptions there were at the end of the day on a particular date. The active_on_date defaults to today if not specified, and should be in ISO8601 format (YYYY-MM-DD), for example 2022-03-03T12:12:16+00:00. The time will always be rounded to the end of the day, even if that is in the future.
Get stats for subscribers to a finder by its URL
To see a report on the number of subscribers to a finder:
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:finder_statistics[<path>]'
This will report on the number of subscriber lists to the finder on a given path.
The path should be the full path on gov.uk (for instance /cma-cases if the page you're interested in is https://www.gov.uk/cma-cases)
Because finder subscriptions can include the filters active on the finder at the point the subscription was created, there may be more than one subscriber list. Finders require an email_alert_signup item in the links section of their content item to allow alerts, so if there are no subscriptions to a finder it may be because it cannot be signed up to.
Find out how many messages were sent out for a content change
The previous rake task only gets subscriber lists that match a URL. But subscribers can also match on topics/tags/links, so to get a full idea of how many people subscribe to a page:
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:historical_content_change_statistics[<path>]'
This gives you a list of all the content changes that have been registered for that path - this is all the times that email-alert-api actually sent out notifications, with a breakdown for each occurence into the number of people notified immediately, in the next daily digest, and in the weekly digest.
Find out how many messages would be sent if a page were changed
The previous rake task is only useful once emails have gone out. Occasionally you might be asked for details of how many people will be notified if a major change is published to a document. You can find that out with this task:
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:future_content_change_statistics[<path>,<use draft store?>]'
The second parameter should be true or false depending on whether you want to use information from the draft or live content stores (note that the most common thing that will change the number of subscriber lists notified are the links and organisations, and if changed they occur immediately, and do not differ on the draft and live stores).
Get a report of single page notification subscriber lists by active subscriber count
This report provides a count of all subscriber lists with a content ID, followed by individual subscriber lists ordered by active subscriber count.
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:single_page_notifications_top_subscriber_lists'
By default output is limited to only show the top 25 lists by active subscriber count. However that can be overridden to increase or decrease the output number.
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:single_page_notifications_top_subscriber_lists[5]'
Get a report on potentially inactive subscriber lists
kubectl -n apps exec -it deploy/email-alert-api -- bundle exec rake 'report:potentially_dead_lists'