# Lists API

Manage audiences and their membership.

## Endpoints

- `GET /v1/lists`
- `POST /v1/lists`
- `GET /v1/lists/{id}`
- `PATCH /v1/lists/{id}`
- `DELETE /v1/lists/{id}`
- `GET /v1/lists/{id}/contacts`
- `POST /v1/lists/{id}/contacts`
- `DELETE /v1/lists/{id}/contacts/{contact_id}`

## Create & manage

```bash
curl -X POST https://emailbump.com/api/v1/lists \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter" }'
```

## Membership

Add a contact by id or email. On an ordinary list the membership is confirmed at once and any list-join automation fires now; on a double-opt-in list it fires only after they confirm (see below). Adding someone who is already a member is a no-op in either case.

```bash
curl -X POST https://emailbump.com/api/v1/lists/LIST_ID/contacts \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jamie@example.com" }'
```

## Double opt-in

Set `double_optin: true` on a list to require confirmed subscription. It is a
**per-list** setting — each list confirms independently; there is no single
global confirmation.

- Adding a contact to a double-opt-in list enrols them as `pending` and emails
  them a confirmation link (subject: *"Please confirm your subscription to
  {list name}"*).
- They become an active member — and the list-join automation fires — only when
  they click the link. Re-adding a contact who is already `pending` or
  `confirmed` does **not** re-send, so re-running a sync is safe.
- Campaigns to the list send only to `confirmed` members; `pending` and per-list
  `unsubscribed` contacts are excluded.
- Confirmation and per-list unsubscribe are hosted pages
  (`/list-confirm/{token}`, `/list-unsubscribe/{token}`) — no extra API calls
  needed.

The confirmation email is queued rather than sent inline, so importing a large
CSV into a double-opt-in list returns immediately and the mail drains in the
background.