> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senderz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Lists

> List your segments and manage static list membership.

In the public API, "lists" are your **segments**. You can enumerate them and add/remove members on **static** lists. Dynamic segments compute their own membership and can't be mutated. All endpoints use the [`X-Sender-Tenant` + `X-API-Key`](/en/api-reference/authentication) headers.

## List all lists

```http theme={null}
GET /api/v1/public/lists
```

<ParamField query="limit" type="integer" default="50">Page size 1–100.</ParamField>
<ParamField query="offset" type="integer" default="0">Records to skip.</ParamField>

Returns a [paginated](/en/api-reference/pagination) array of:

<ResponseField name="id" type="string">Segment UUID.</ResponseField>
<ResponseField name="name" type="string">Segment name.</ResponseField>
<ResponseField name="type" type="string">`static` or `dynamic`.</ResponseField>
<ResponseField name="profiles" type="integer">Estimated member count.</ResponseField>

<Info>
  The member count is the cached estimated size (fast), not a live recount.
  The tenant-facing Segments screen refreshes it.
</Info>

## Add members

```http theme={null}
POST /api/v1/public/lists/:id/members
```

<ParamField body="emails" type="string[]">Up to 100 emails. Unknown emails create contacts.</ParamField>
<ParamField body="contactIds" type="string[]">Up to 100 contact UUIDs.</ParamField>

### Response

<ResponseField name="added" type="integer">Members added this call.</ResponseField>
<ResponseField name="count" type="integer">Total members after the add.</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.senderz.app/api/v1/public/lists/SEGMENT_ID/members \
    -H "X-Sender-Tenant: your-workspace-slug" \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{ "emails": ["dana@example.com", "noa@example.com"] }'
  ```

  ```json Response theme={null}
  { "success": true, "data": { "added": 2, "count": 342 } }
  ```
</CodeGroup>

<Note>
  Adding members fires the `list.subscribed` outbound webhook; removing fires
  `list.unsubscribed`.
</Note>

## Remove members

```http theme={null}
DELETE /api/v1/public/lists/:id/members
```

<ParamField body="email" type="string">A single email.</ParamField>
<ParamField body="emails" type="string[]">Up to 100 emails.</ParamField>
<ParamField body="contactIds" type="string[]">Up to 100 contact UUIDs.</ParamField>

Returns `{ removed, count }`.

### Remove a single member by ID

```http theme={null}
DELETE /api/v1/public/lists/:id/members/:contactId
```

Returns `{ count }`.

<Warning>
  Only **static** lists can be mutated. Attempting to add or remove on a
  dynamic segment returns `400`.
</Warning>