Status Page Subscribers

List, update, remove, notify and export the email subscribers of a status page

Overview

Visitors can subscribe to a status page by email to receive incident and maintenance notifications. These endpoints let you manage that list.

Action	Endpoint
List	GET /api/projects/{projectId}/status-pages/{statusPageId}/subscribers
Update preferences	PATCH /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/{subscriberId}
Delete	DELETE /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/{subscriberId}
Bulk delete	POST /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/bulk-delete
Bulk notify	POST /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/bulk-notify
Export CSV	GET /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/export

Authentication

Header	Required	Description
X-API-Key	Yes	Your API key (Authorization: Bearer {jwt} also works). Write requests need the read_write scope.
Content-Type	Yes (when sending a body)	application/json

Required access: project viewer or higher to list; project admin for everything else, including export. No X-Project-ID header is needed.

Path parameters

Parameter	Type	Description
projectId	UUID	The project
statusPageId	UUID	The status page
subscriberId	UUID	The subscriber

List subscribers

Query parameters

Parameter	Type	Default	Description
status	string	all	verified, unverified, unsubscribed or all
preference	string	-	Only subscribers with this preference on: critical_incidents, all_incidents or maintenance
search	string	-	Search by email
sort	string	subscribed_at	email, subscribed_at or verified_at
order	string	desc	asc or desc
page	integer	1	Page number, 1 or greater
limit	integer	50	Page size, 10-1000

Response (200)

{
  "success": true,
  "data": {
    "subscribers": [
      {
        "id": "d4c3b2a1-f0e9-4d8c-b7a6-5f4e3d2c1b0a",
        "status_page_id": "0b7c3a52-7d57-4c35-9f0e-5a3b6f1f2a10",
        "email": "[e-mail]",
        "webhook_url": null,
        "is_verified": true,
        "verification_expires_at": null,
        "preferences": {
          "critical_incidents": true,
          "all_incidents": false,
          "maintenance": true,
          "frequency": "immediate"
        },
        "unsubscribed_at": null,
        "subscribed_at": "2026-09-01T09:00:00.000Z",
        "verified_at": "2026-09-01T09:02:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total_count": 1,
      "has_more": false
    }
  }
}

Subscriber objects never include verification or unsubscribe tokens. Those are only sent to the subscriber in their own email links. Subscriber email addresses are still personal data, so treat list responses as sensitive.

cURL

curl "https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers?status=verified&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

Update subscriber preferences

Field	Type	Required	Description
preferences	object	Yes	At least this wrapper object
preferences.critical_incidents	boolean	No	Notify about critical incidents
preferences.all_incidents	boolean	No	Notify about all incidents
preferences.maintenance	boolean	No	Notify about maintenance
preferences.frequency	string	No	immediate, hourly or daily

Response (200): { "success": true, "data": { "subscriber": { ... }, "message": "Subscriber preferences updated successfully" } }

cURL

curl -X PATCH https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/YOUR_SUBSCRIBER_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preferences": { "all_incidents": true, "frequency": "daily" } }'

Delete a subscriber

Response (200): { "success": true, "data": { "message": "Subscriber deleted successfully" } }

cURL

curl -X DELETE https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/YOUR_SUBSCRIBER_ID \
  -H "X-API-Key: YOUR_API_KEY"

Bulk delete

Field	Type	Required	Description
subscriber_ids	UUID[]	Yes	At least one subscriber

Response (200):

{
  "success": true,
  "data": {
    "result": {
      "success_count": 2,
      "failed_count": 0,
      "errors": []
    },
    "message": "Successfully deleted 2 of 2 subscribers"
  }
}

errors contains { "subscriber_id", "error" } entries for any that failed.

cURL

curl -X POST https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/bulk-delete \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subscriber_ids": ["YOUR_SUBSCRIBER_ID_1", "YOUR_SUBSCRIBER_ID_2"] }'

Bulk notify

Sends a custom email to the selected subscribers. Only verified subscribers who have not unsubscribed receive it; others are skipped.

Field	Type	Required	Description
subscriber_ids	UUID[]	Yes	At least one subscriber
subject	string	Yes	1-200 characters
message	string	Yes	1-5000 characters

Response (200): same shape as bulk delete, with message reading Successfully notified {n} of {total} subscribers.

cURL

curl -X POST https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/bulk-notify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_ids": ["YOUR_SUBSCRIBER_ID"],
    "subject": "Planned maintenance on Saturday",
    "message": "We will be performing maintenance from 02:00 to 03:00 UTC."
  }'

Export CSV

Returns up to 10,000 subscribers as a CSV file (Content-Type: text/csv). It accepts the status, preference and search filters from the list endpoint. Columns: Email, Status, Subscribed At, Verified At, Critical Incidents, All Incidents, Maintenance, Frequency, Webhook URL.

cURL

curl "https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/export?status=verified" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o subscribers.csv

Errors

Status	Code	Cause
400	VALIDATION_ERROR	Invalid body or query parameter
401	AUTHENTICATION_REQUIRED	Missing or invalid credentials
403	INSUFFICIENT_PERMISSIONS	Write or export without project admin access
403	ACCESS_DENIED	No access to the project, or the page belongs to another project
403	API_KEY_ORGANIZATION_MISMATCH	The API key belongs to a different organization than the project
403	READ_ONLY_API_KEY	The API key has the read scope and the request writes data
404	RESOURCE_NOT_FOUND	The status page or subscriber does not exist