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

# Get Mailing List

> One mailing list with recipient counts by status

Returns a single mailing list with its recipient counts — the quickest way to check that a sync landed (`active_count` went up) without paging through recipients.

## Authentication

This endpoint requires an API token passed as a Bearer token in the `Authorization` header.

```bash theme={null}
Authorization: Bearer YOUR_API_TOKEN
```

## Path Parameters

<ParamField path="list_id" type="string" required>
  The mailing list's unique identifier (UUID).
</ParamField>

## Request

```bash cURL theme={null}
curl "https://api.shipstar.ai/api/v1/email/lists/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Response

<ResponseField name="id" type="string" required>
  The mailing list's unique identifier (UUID)
</ResponseField>

<ResponseField name="name" type="string" required>
  The mailing list's name
</ResponseField>

<ResponseField name="recipient_count" type="integer" required>
  Total recipients on the list, in every status
</ResponseField>

<ResponseField name="active_count" type="integer" required>
  Recipients who will receive the next release email (at most 500)
</ResponseField>

<ResponseField name="removed_count" type="integer" required>
  Recipients you removed. An upsert or add reactivates them.
</ResponseField>

<ResponseField name="unsubscribed_count" type="integer" required>
  Recipients who unsubscribed themselves. Never reactivated by the API.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 creation timestamp
</ResponseField>

```json 200 theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Product updates",
  "recipient_count": 312,
  "active_count": 298,
  "removed_count": 9,
  "unsubscribed_count": 5,
  "created_at": "2026-07-10T09:12:00Z"
}
```

## Errors

| Status | Description |
| - | - |
| 401 | Invalid or expired API token |
| 404 | Mailing list not found in the token's project |

## Rate Limits

This endpoint is limited to 100 requests per minute per IP.