---
type: API
title: Lists API
description: List CRUD plus subscribe/unsubscribe by email via the memberships sub-resource.
resource: https://euromailing.com/api/v1/lists
tags: [lists, subscriptions, api]
timestamp: 2026-07-06T00:00:00Z
---

# Lists API

Scope: `lists:read` for reads, `lists:write` for writes (including
memberships).

## Endpoints

| Method & path | Purpose |
|---------------|---------|
| `GET /api/v1/lists` | List all lists (id, name, contacts_count, double_optin) |
| `GET /api/v1/lists/:id` | Fetch one |
| `POST /api/v1/lists` | Create (`{ "list": { "name": …, "description": …, "double_optin": bool } }`) |
| `PATCH /api/v1/lists/:id` | Update |
| `DELETE /api/v1/lists/:id` | Delete |
| `POST /api/v1/lists/:id/memberships` | **Subscribe by email** (`{ "email": …, "first_name": …, "last_name": … }`). Creates the contact when unknown. 201 on new subscription, 200 when already subscribed (idempotent). |
| `DELETE /api/v1/lists/:id/memberships` | **Unsubscribe by email** (`{ "email": … }`). Soft-marks the membership (audit trail kept); 404 when never subscribed. |

## Subscribe example

```bash
curl -X POST https://euromailing.com/api/v1/lists/$LIST_ID/memberships \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "email": "jan@example.com", "first_name": "Jan" }'
```