Full list of /api/v1/* endpoints grouped by resource, with what each one does in one line.
Every endpoint requires Authorization: Bearer mb_…. read scope is enough for GETs; mutating requests (POST / PATCH / DELETE) need write.
Path placeholders like {id} are UUIDs unless noted.
Workspace
| Method | Path | What it does |
|---|
| GET | /api/v1/me | Return the workspace this key belongs to + its scopes. Use as a connection test. |
Contacts
| Method | Path | What it does |
|---|
| GET | /api/v1/contacts | List contacts. Filter by status (subscribed/unsubscribed/pending) or q (email substring). Paginate with limit + offset. |
| POST | /api/v1/contacts | Upsert a contact by email. Honors double-opt-in if enabled; existing contacts'' names aren''t overwritten unless you pass them. attrs is merged into existing custom fields by default — partial updates do NOT clear unrelated keys. Pass attrs_mode: "replace" to wholesale overwrite when re-syncing from a source of truth. |
| GET | /api/v1/contacts/{id_or_email} | Get one contact, including its tags + lists. The path accepts either a contact UUID or a URL-encoded email (e.g. user%40example.com) — handy when you only have the email. |
| PATCH | /api/v1/contacts/{id_or_email} | Update name / status / attrs. Only fields you pass are changed. attrs is merged into existing custom fields by default; pass attrs_mode: "replace" to wholesale overwrite. Path accepts UUID or URL-encoded email. |
| DELETE | /api/v1/contacts/{id_or_email} | Permanent delete. Prefer POST /unsubscribe for opt-outs. Path accepts UUID or URL-encoded email. |
Tags
| Method | Path | What it does |
|---|
| GET | /api/v1/tags | List all tags in the workspace. |
| POST | /api/v1/tags | Create a tag (idempotent by name per workspace). |
| POST | /api/v1/contacts/{id}/tags | Attach tag names to a contact. Names that don't exist yet are auto-created. |
| DELETE | /api/v1/contacts/{id}/tags/{tagId} | Detach one tag from one contact. |
Lists
| Method | Path | What it does |
|---|
| GET | /api/v1/lists | List static + dynamic lists. |
| POST | /api/v1/lists | Create a list. type='static' (manual) or 'dynamic' (query-driven). |
| POST | /api/v1/contacts/{id}/lists/{listId} | Add a contact to a static list. (400 on dynamic lists.) |
| DELETE | /api/v1/contacts/{id}/lists/{listId} | Remove a contact from a list. |
Sequences
| Method | Path | What it does |
|---|
| GET | /api/v1/sequences | List sequences. |
| POST | /api/v1/sequences | Create a sequence with its steps + email content in one call. |
| GET | /api/v1/sequences/{id} | Get one sequence + its ordered steps. |
| PATCH | /api/v1/sequences/{id} | Update name / description / status / triggers. Pass steps to replace the whole step array. |
| POST | /api/v1/sequences/{id}/enroll | Enroll a contact (by email or contact_id). |
Campaigns
| Method | Path | What it does |
|---|
| GET | /api/v1/campaigns | List campaigns. Filter by status. |
| GET | /api/v1/campaigns/{id} | Get one campaign, including body + stats. |
| PATCH | /api/v1/campaigns/{id} | Update name / subject / from / status / scheduled_at / body / layout. Use status paused / cancelled to halt a scheduled send. |
Automations
| Method | Path | What it does |
|---|
| GET | /api/v1/automations | List automations (metadata only, no graph). |
| POST | /api/v1/automations | Create an automation with an optional full graph. Graph is validated (node types, edges, conditional handles). |
| GET | /api/v1/automations/{id} | Get one automation with full graph. |
| PATCH | /api/v1/automations/{id} | Update name / status / triggers / graph. Graph swap is validated the same way as create. |
| DELETE | /api/v1/automations/{id} | Permanent delete. CASCADE deletes the automation_runs too. |
Events
| Method | Path | What it does |
|---|
| POST | /api/v1/events | Fire a lifecycle event for a contact (by email or contact_id). Auto-creates the contact if needed. Use this for behavioural signals. |
Purchases
| Method | Path | What it does |
|---|
| GET | /api/v1/purchases | List purchases. Filter by email / contact_id / source. |
| POST | /api/v1/purchases | Record a purchase. external_id deduplicates so retries are safe. |
Unsubscribe
| Method | Path | What it does |
|---|
| POST | /api/v1/unsubscribe | Mark an email as unsubscribed. Adds to suppression. Idempotent. |
Response shape
Successful responses return JSON with data (and total / limit / offset for lists). Errors return {"error": "…"} with the appropriate HTTP status.
{
"data": { "id": "uuid", "email": "…", "status": "subscribed", ... }
}
Status codes
| Code | Meaning |
|---|
| 200 | OK |
| 201 | Created |
| 400 | Invalid JSON |
| 401 | Missing / invalid / revoked token |
| 403 | Token lacks required scope |
| 404 | Not found |
| 422 | Validation error — see error for which field |
| 500 | Server error |
