# List email subscribers

Retrieve a paginated list of email subscribers for the organization.

Source: https://statusdashboard.com/docs/api/subscriptions/email/subscribers/list

`GET /app/subscribers/email/subscribers`

Returns a paginated list of email subscription records for the organization (one row per dashboard + email). Includes org-wide unique subscriber quota usage.

Requires the `admin` or `subscriber` role and the **Email notifications** feature entitlement.

***

## Request
See [API Basics](/docs/api) for required headers.

### Query parameters
| Parameter   | Type    | Required | Description                                                                                             |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `limit`     | integer | No       | Max items per page. Range: 1–100. Default: `10`.                                                        |
| `nextToken` | string  | No       | Next-page bookmark from the previous response — pass unchanged. See [Pagination](/docs/api#pagination). |
| `email`     | string  | No       | Filter to an exact subscriber email address (case-insensitive). Must be a valid email when provided.    |

Omit `email` to list subscribers across all addresses (paginated).

***

## Sample request
```bash
curl "https://api.statusdashboard.com/app/subscribers/email/subscribers?limit=10&email=alice%40acme.com" \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

## Sample response
**Status: `200 OK`**

```json
{
  "subscribers": [
    {
      "email": "alice@acme.com",
      "dashboardId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "dashboardName": "Acme Status",
      "verified": true,
      "verifiedAt": "2026-06-01T14:22:00.000Z",
      "createdAt": "2026-06-01T14:20:00.000Z",
      "updatedAt": "2026-06-01T14:22:00.000Z",
      "componentIds": ["b2c3d4e5-f6a7-8901-bcde-f12345678901", "c3d4e5f6-a7b8-9012-cdef-123456789012"],
      "paused": false,
      "locked": false
    }
  ],
  "nextToken": null,
  "usage": {
    "uniqueEmails": 42,
    "limit": 1000
  }
}
```

***

## Response fields
| Field                  | Description                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| `subscribers`          | Page of subscription records                                                                                   |
| `subscribers[].locked` | `true` when admin-managed (blocks dashboard self-service subscribe/manage; still receives event notifications) |
| `subscribers[].paused` | Derived: `true` when verified and `componentIds` is empty (notifications off; subscription remains)            |
| `nextToken`            | See [Pagination](/docs/api#pagination). `null` when there are no more pages.                                   |
| `usage.uniqueEmails`   | Unique email addresses org-wide (pending and verified)                                                         |
| `usage.limit`          | Plan `emailSubscribers` quota                                                                                  |

***

## Pagination
See [Pagination](/docs/api#pagination) in API Basics. Re-send the same query parameters on every page request.

***

## Error responses
| Status | When                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------- |
| `400`  | Invalid query parameters                                                                          |
| `403`  | Requires admin or subscriber role, or the Email notifications feature is not enabled on your plan |