> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uptimeio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#list-subscribers) | `GET /api/projects/{projectId}/status-pages/{statusPageId}/subscribers` |
| [Update preferences](#update-subscriber-preferences) | `PATCH /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/{subscriberId}` |
| [Delete](#delete-a-subscriber) | `DELETE /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/{subscriberId}` |
| [Bulk delete](#bulk-delete) | `POST /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/bulk-delete` |
| [Bulk notify](#bulk-notify) | `POST /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/bulk-notify` |
| [Export CSV](#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)

```json theme={null}
{
  "success": true,
  "data": {
    "subscribers": [
      {
        "id": "d4c3b2a1-f0e9-4d8c-b7a6-5f4e3d2c1b0a",
        "status_page_id": "0b7c3a52-7d57-4c35-9f0e-5a3b6f1f2a10",
        "email": "jane@example.com",
        "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.

```bash cURL theme={null}
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" } }`

```bash cURL theme={null}
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" } }`

```bash cURL theme={null}
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):

```json theme={null}
{
  "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.

```bash cURL theme={null}
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`.

```bash cURL theme={null}
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`.

```bash cURL theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.