REST API

Everything the Mankomail web interface does goes through an HTTP API that speaks JSON. The same API is open to your own tools: a script, a CRM or a management system can create workflows, publish them, trigger runs, read executions, send mail or write to Tables on your behalf.

This section is in two parts: the guides below describe what is common to every route; the reference lists each route, family by family, generated from the OpenAPI document of the instance.

Base path

Routes live under <PUBLIC_BASE_URL>/api/v1, for example <PUBLIC_BASE_URL>/api/v1/workflows. Request and response bodies are JSON (Content-Type: application/json), except for a few downloads (attachments, CSV exports) that say so in the reference.

A few entry points live outside this prefix:

• /healthz and /readyz, the health checks (see Monitoring);
• /hooks/…, the entry points other systems call: the webhook trigger of a workflow, POST /hooks/wf/<token>, and the push notifications of mail providers. They are authorised by the token in their URL, not by a session or a key.

The web interface also receives real-time updates over a WebSocket at /api/v1/ws. The WebSocket is reserved to the interface: it is not open to API keys.

Two ways to authenticate

	Session cookie	API key
For	The web interface, a browser	A script, a server, an integration
How	POST /api/v1/auth/login sets a cookie named session	Authorization: Bearer mk_… on every request
Acts as	The signed-in member	The member who created the key, within the key's scopes
Reaches	Every route	Every route that declares a scope; a handful of routes are session-only
Rate limit	Sign-in attempts, per IP address	600 requests per minute, per key

A key never does more than its member could do in the interface: it sees the same workflows, the same mailboxes, and administration routes still require the member to be an administrator. What a key adds is a restriction, its scopes. Authentication explains how to create and use a key; Scopes lists what each scope covers.

Conventions shared by every route

• Errors always have the shape { "code": "domain.code", "message": "…", "details": { … } }. Test the code, never the message. See Errors and the list of error codes.
• Lists are paginated by an opaque cursor: send cursor and limit, read nextCursor. Tables rows are the exception and use offset. See Pagination.
• Creating and triggering routes accept an Idempotency-Key header, so a request replayed after a network failure does not create or send twice. See Idempotency.
• Limits: the rate limit per key, the 5 MB request body, the bounds of each list. See Limits.
• Identifiers are opaque strings; dates are ISO 8601 in UTC (2026-10-04T09:00:00.000Z).

Guides

• Authentication — creating a key, sending it, expiry, revocation, what refuses keys.
• Scopes — the domain:verb grammar and the table of domains.
• Pagination — cursors, limits, and the Tables exception.
• Idempotency — the Idempotency-Key header, replays and conflicts.
• Errors — the error shape, HTTP status classes and the common codes.
• Limits — every bound a client should know.
• Examples — an end-to-end curl walkthrough, from the key to the first execution.
• OpenAPI document — where it is, how to import it, the x- extensions.
• Reference — every route, generated from the OpenAPI document.

An AI assistant can also drive the instance through its MCP server, which uses the same API keys and scopes: see MCP.