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

# Add Recipients

> Bulk-add email addresses to a mailing list

Bulk-adds email addresses to a mailing list — for example, syncing signups from your own database. Send up to 1000 addresses per request.

Each address is validated individually; invalid entries are reported in the `invalid` array rather than failing the batch. Addresses are deduplicated case-insensitively, and addresses already on the list — including unsubscribed ones — are counted in `skipped_existing`, so re-syncing never resurrects an opt-out. A list holds at most 500 active 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**. The list must belong to the token's project.

## Path Parameters

<ParamField path="list_id" type="string" required>
  The mailing list's unique identifier (UUID). List ids come from [List Mailing Lists](/api-reference/mailing-lists/list-mailing-lists).
</ParamField>

## Body

<ParamField body="emails" type="string[]" required>
  Email addresses to add. Between 1 and 1000 items per request.
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.shipstar.ai/api/v1/email/lists/a1b2c3d4-e5f6-7890-abcd-ef1234567890/recipients" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"emails": ["one@example.com", "two@example.com"]}'
  ```

  ```javascript JavaScript theme={null}
  const listId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
  const response = await fetch(`https://app.shipstar.ai/api/v1/email/lists/${listId}/recipients`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      emails: ['one@example.com', 'two@example.com']
    })
  });

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

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

  list_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  response = requests.post(
      f'https://app.shipstar.ai/api/v1/email/lists/{list_id}/recipients',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
      json={'emails': ['one@example.com', 'two@example.com']}
  )

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

## Response

<ResponseField name="added" type="integer" required>
  Number of addresses added to the list
</ResponseField>

<ResponseField name="skipped_existing" type="integer" required>
  Number of addresses already on the list (including unsubscribed ones, which are never re-activated)
</ResponseField>

<ResponseField name="invalid" type="string[]" required>
  Addresses that failed validation and were not added
</ResponseField>

### Example Response

```json 200 theme={null}
{
  "added": 2,
  "skipped_existing": 1,
  "invalid": ["not-an-email"]
}
```

## Errors

| Status | Description                                                              |
| ------ | ------------------------------------------------------------------------ |
| 400    | Adding the batch would exceed the 500 active recipients per list limit   |
| 401    | Invalid or expired API token                                             |
| 404    | Mailing list not found in the token's project                            |
| 422    | Invalid request body (e.g. empty `emails` array or more than 1000 items) |

## Rate Limits

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