---
title: "List Recipients"
method: GET
path: "/api/v1/internal/release-email/recipients/list"
tags: ["internal", "release-email"]
---

# List Recipients

`GET /api/v1/internal/release-email/recipients/list`

The audience roll-call, so a send is never confirmed against a number
nobody can inspect.

``internal`` switches to the staff audience an internal test broadcast
reaches, which the same rule covers.

Carries each recipient's product-updates consent so a delivered count lower
than the audience count is explainable here. Read-only: no route on this
router writes a subscription field.

## Query parameters

- `internal` boolean

## Response `200`

Successful Response

- ReleaseEmailRecipientResponse[]
  - `email` string, required
  - `display_name` string, nullable, required
  - `workspace_name` string, required
  - `status` 'active' | 'suspended', required — Whether a recipient's account is suspended, at either level. ``SUSPENDED`` means the user is suspended or their workspace is — it is a statement about account state, not about whether someone is still a customer, which is a fact this system never holds. Pushed to Resend as a contact property, so the values are visible outside this codebase and are hashed into the contact-sync fingerprint: changing one re-pushes every contact on the next sync. Renaming a value is safe only while segment membership stays explicit — the sync adds and removes contacts by API call. A filter-based segment keyed on this property would make a rename empty the audience silently.
  - `plan_type` string, required
  - `is_excluded` boolean, required
  - `is_internal` boolean, required
  - `opt_out_state` 'subscribed' | 'opted_out' | 'unknown', required — Whether a recipient still consents to product updates. ``UNKNOWN`` is a real answer, not a placeholder: opt-out lives only in Resend and a failed read must not be reported as consent. Distinct from exclusion, which is ours to set and ours to lift — this one never is.

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-08** `ba2b8d962161` — 2 warning, 2 info
  - added the new `active` enum value to the `items/status` response property for the response status `200`
  - added the new `suspended` enum value to the `items/status` response property for the response status `200`
  - added the required property `items/is_internal` to the response with the `200` status
  - added the required property `items/opt_out_state` to the response with the `200` status

[Change history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/internal/release-email/recipients/list/get.md)

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/maia-analytics/maia-api/revisions/d0e2bf840dfc/schema)