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

# Create Mailing List

> Create a named mailing list in your API token's project

Creates a mailing list in the project your API token is scoped to. A project holds at most 20 lists and names are unique within a project. Use the returned `id` with the recipient endpoints.

## Authentication

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

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

## Body

<ParamField body="name" type="string" required>
  The list name, 1–100 characters. Shown in the dashboard and the send dialog.
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.shipstar.ai/api/v1/email/lists" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "Product updates"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.shipstar.ai/api/v1/email/lists', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: 'Product updates' })
  });

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

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

  response = requests.post(
      'https://api.shipstar.ai/api/v1/email/lists',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
      json={'name': 'Product updates'},
  )

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

## Response

Returns the created list in the same shape as [List Mailing Lists](/api-reference/mailing-lists/list-mailing-lists).

```json 201 theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Product updates",
  "recipient_count": 0,
  "active_count": 0,
  "removed_count": 0,
  "unsubscribed_count": 0,
  "created_at": "2026-09-28T10:00:00Z"
}
```

## Errors

| Status | Description |
| - | - |
| 400 | The project already has 20 mailing lists, or the name is blank |
| 401 | Invalid or expired API token |
| 409 | A list with this name already exists in the project |
| 422 | Invalid request body |

## Rate Limits

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