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

# Export Recipients

> Download a mailing list as CSV

Returns the list's recipients as a CSV attachment — every status unless you filter — with the columns:

```
email,name,external_id,status,created_at,status_changed_at,attributes
```

`attributes` is compact JSON (empty when the recipient has none). The same file is what the dashboard's **Export CSV** button downloads, and its columns are accepted back by the dashboard's **Import CSV**.

## Authentication

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

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

## Path Parameters

<ParamField path="list_id" type="string" required>
  The mailing list's unique identifier (UUID).
</ParamField>

## Query Parameters

<ParamField query="status" type="string">
  Only recipients in this status: `active`, `removed` or `unsubscribed`.
</ParamField>

## Request

```bash cURL theme={null}
curl -o recipients.csv \
  "https://api.shipstar.ai/api/v1/email/lists/a1b2c3d4-e5f6-7890-abcd-ef1234567890/recipients/export.csv?status=active" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Response

`200 OK` with `Content-Type: text/csv; charset=utf-8` and a `Content-Disposition: attachment; filename="<list-name>-recipients.csv"` header.

```csv theme={null}
email,name,external_id,status,created_at,status_changed_at,attributes
sam@example.com,Sam Lee,usr_42,active,2026-09-01T08:00:00+00:00,,"{""plan"":""pro""}"
casey@example.com,,,removed,2026-09-02T08:00:00+00:00,2026-09-20T09:30:00+00:00,
```

## Errors

| Status | Description |
| - | - |
| 400 | Unknown `status` value |
| 401 | Invalid or expired API token |
| 404 | Mailing list not found in the token's project |

## Rate Limits

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