> ## 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.

# List Mailing Lists

> List the mailing lists of your API token's project

Returns an array of the mailing lists belonging to the project your API token is scoped to, with recipient counts by status. Use the returned `id` values with [Upsert Recipients](/api-reference/mailing-lists/upsert-recipients) and the other recipient endpoints, or create a list with [Create Mailing List](/api-reference/mailing-lists/create-mailing-list).

## Authentication

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

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

API tokens are created in the [Dashboard](https://app.shipstar.ai/dashboard) under **API Keys**.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.shipstar.ai/api/v1/email/lists" \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.shipstar.ai/api/v1/email/lists', {
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  });

  const lists = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.shipstar.ai/api/v1/email/lists',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
  )

  lists = response.json()
  ```
</CodeGroup>

## Response

Returns an array of mailing list objects.

<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 number of recipients on the list in every status
</ResponseField>

<ResponseField name="active_count" type="integer" required>
  Recipients who will receive the next release email
</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>
  When the list was created (ISO 8601 timestamp)
</ResponseField>

### Example Response

```json 200 theme={null}
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Release announcements",
    "recipient_count": 240,
    "active_count": 232,
    "removed_count": 3,
    "unsubscribed_count": 5,
    "created_at": "2026-06-15T09:30:00Z"
  }
]
```

## Errors

| Status | Description |
| - | - |
| 401 | Invalid or expired API token |

## Rate Limits

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


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