Manage subscribers

A subscriber is someone who confirmed an email address on your status page. They get email about the page’s incidents and maintenance, limited to the kinds of update and the components they chose. Subscriptions are email only; visitors who prefer a feed reader can follow the page’s RSS or Atom feed with no sign-up.

Every address confirms from a link we send before it gets any notice, whether the visitor used the public form, you added it, or it came in through an import. There is no way to add or import confirmed subscribers.

When subscribers get email

A page’s subscribers get email when:

An incident goes on the page: it is created there (POST /status_page/{status_page_id}/incident), you publish it (POST /incident/{incident_id}/publish, unless notify_subscribers is false), or a service publishes it automatically. Each page is told once per incident, and never about one that is already resolved.
A public update is posted through the page (POST /status_page/{status_page_id}/incident/{incident_id}/update, unless notify_subscribers is false), or through POST /incident/{incident_id}/update with notify_subscribers: true, which emails every page the incident is on.
The incident is resolved by hand, unless notify_subscribers is false. When its monitors recover and it resolves itself, only pages whose subscribers already heard about it are told.
Maintenance is scheduled on the page, when it starts and when it ends.

Nothing is sent for an internal note, an unpublish, a reopen, a maintenance edit, or an incident that was merged into another.

Who gets which notice

Each subscriber chooses the kinds of update (incidents, maintenance, or both) and the components (every component, or specific ones the page shows). A notice goes to a confirmed subscriber when both choices match:

Notice	Goes to confirmed subscribers who
Incident opened, updated or resolved	take incidents, and chose every component or at least one component the incident affects.
Maintenance scheduled, started or completed	take maintenance, and chose every component or at least one component the maintenance covers.

An incident with no affected components goes to everyone who takes incidents. A maintenance for the whole page goes to everyone who takes maintenance. Set the affected components on an incident, and pick specific monitors for a maintenance that touches only part of your service, so people who follow one part hear only about that part.

Each subscriber gets each notice once, and every update to an incident is its own email.

Choose what to get

The subscribe form on the public page takes only an email address, which subscribes to everything. A Choose what to get link on the form lets the visitor pick incidents, maintenance or both, and every component or only some.

Every notice email has two links:

Manage preferences opens a page at https://statuspageapi.siteqwality.com/subscribe/preferences?token=... where the subscriber changes the kinds of update and the components, or unsubscribes. The page shown after confirming an address links there too.
Unsubscribe stops all mail from your page.

Once an address is confirmed, only that preferences page changes its choices. Submitting the public form again with the same address does not.

See and manage the list

In the dashboard, open the status page and use the Subscribers tab. It shows the count in each state and the places used out of 1,000, filters by state or address, adds an address, imports a CSV, removes an address and exports the list as CSV or JSON.

Through the API, with an API key that has access to status pages, exported as SITEQWALITY_API_KEY, and the page’s id as STATUS_PAGE_ID:

# How many, and in which state
curl -s -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  "https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/subscriber?limit=1" | jq '.counts, .capacity'

# Find an address
curl -s -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  "https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/subscriber?q=ann@"

# List the quarantined addresses
curl -s -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  "https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/subscriber?state=quarantined"

# Download everything as CSV
curl -s -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  "https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/subscriber/export" -o subscribers.csv

# Remove one by its id from the list (an erasure request, or a mistake)
curl -s -X DELETE -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  "https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/subscriber/$SUBSCRIBER_ID"

Fields, states and limits are in the status page reference.

Add one address

In the dashboard, click Add subscriber on the Subscribers tab. Adding an address sends it a confirmation email.

Through the API you can preselect what the person gets with kinds (incident, maintenance) and component_ids (ids of checks on the page). Leave both out for everything.

# Everything
curl -s -X POST -H "Authorization: Bearer $SITEQWALITY_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"ann@example.com"}' "https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/subscriber"

# Only incidents that affect one check
curl -s -X POST -H "Authorization: Bearer $SITEQWALITY_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"ann@example.com","kinds":["incident"],"component_ids":["<http-job-id>"]}' \
  "https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/subscriber"

Nothing is sent when the address is already subscribed or a link went out to it in the last hour.

Import a CSV

Import moves an existing list to Site Qwality, for example from another status page provider. Every new address gets a confirmation email, so tell the people on your list before you import.

Import from the Subscribers tab, or send the file’s contents to the API:

jq -Rs '{csv: .}' subscribers.csv | curl -s -X POST \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" -H "Content-Type: application/json" \
  -d @- "https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/subscriber/import"

The file:

A header row with a column named email, e-mail, email address or e-mail address (in any case) picks that column. Without one, the first cell in each row that contains @ is the address, so a plain list with one address per line works too.
Blank lines are ignored.
At most 1,000 data rows per import. The page still holds at most 1,000 subscribers in total.
The CSV from the Subscribers export can be imported back as it is.

The hourly queue

Confirmation emails are rate limited (limits), so a large import does not go out at once. The first confirmations go out during the import itself. The rest wait in the queued state and go out automatically, oldest first, as room frees up. An import sends at most 25 an hour per page, so 1,000 new addresses take about 40 hours, longer when other pages are sending at the same time. The import reports a result for every row (import results) and the page’s rate as sends_per_hour.

Quarantined addresses

An address is quarantined after a permanent bounce (the mailbox or domain does not exist) or a spam complaint (the person marked the mail as spam) on any mail we send to it. Quarantine takes precedence over every other state, so a confirmed address that bounces shows as quarantined. It applies to the address on every status page it is subscribed to, so an address can be quarantined on your page because of mail from another page. The API and the export give the reason as quarantine_reason (bounce or complaint).

What to do depends on the reason:

Bounce. Usually nothing. If the person fixes their mailbox, they can subscribe again through the page form, or you can add the address again. Either sends a fresh confirmation, and confirming lifts the quarantine (a link sent before the bounce does not). Imports never mail a quarantined address, so re-importing does not help. A bounce quarantine is deleted after 90 days.
Complaint. Never lifted automatically, and the form, adding the address and imports all send nothing to it. Unsubscribing does not remove the address either, so it stays blocked. If the person asks to hear from you again, remove the address in the Subscribers tab. After that it can subscribe again, but only through a fresh confirmation.

Each subscriber keeps a record of how it came to be on your list: how the address came in (consent_source), when it was submitted and confirmed, the version of the confirmation wording the person agreed to (consent_version) and the choices they made. The export includes it. Field details are in the reference.

Remove an address

When someone asks you to delete their data, remove them in the Subscribers tab or with DELETE (above). Removal works in any state, quarantined included, and nothing more is mailed to the address. Delivery records for mail to subscribers are kept 90 days at most, and are cleared within two days after the address is gone.

Best practices

Announce planned work, not the failures it causes. Publish a status page maintenance and cover the monitors with a maintenance window, so a service that publishes its incidents does not also email subscribers about the planned outage.
Keep messages short and actionable. “We’re investigating elevated 500 errors on the API. Affects: checkout. ETA: 30 minutes.” is better than three paragraphs of context.