> ## 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. Use the returned `id` values with [Add Recipients](/api-reference/mailing-lists/add-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
```

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://app.shipstar.ai/api/v1/email/lists" \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.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://app.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, including unsubscribed ones
</ResponseField>

<ResponseField name="active_count" type="integer" required>
  Number of active (not unsubscribed) recipients
</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,
    "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.