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

Append-only bulk add: up to 1000 entries per request, each a plain email address or an object with `email` plus optional `name`, `external_id` and `attributes`.

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 — active, removed or unsubscribed — are counted in `skipped_existing` and left untouched, so re-syncing never resurrects an opt-out. A list holds at most 500 active recipients.

<Note>
  To keep a list in sync with another system (update names, reactivate removed contacts, change an address by `external_id`), use [Upsert Recipients](/api-reference/mailing-lists/upsert-recipients) instead. This endpoint never modifies an existing recipient.
</Note>

## 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 | object)[]" required>
  Between 1 and 1000 entries. A plain string is an email address; an object carries `email` (required) plus optional `name`, `external_id` and `attributes` — the same shape as [Upsert Recipients](/api-reference/mailing-lists/upsert-recipients).
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.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", {"email": "two@example.com", "name": "Sam", "external_id": "usr_42"}]}'
  ```

  ```javascript JavaScript theme={null}
  const listId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
  const response = await fetch(`https://api.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://api.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 entries already on the list in any status (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.


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