Admin REST API

The REST API under /admin/v1 is the operational surface: the endpoints scripts and monitoring call — deploy verification, bans, the queue, config overrides. Administrative data objects (organizations, audit log, journaling rules, admin principal management) live on admin-over-JMAP instead (urn:oximail:params:jmap:v2:admin, ADR-075) — new admin objects are added there, not here.

Authentication

Every endpoint requires the admin bearer token from [admin] token:

curl -H "Authorization: Bearer $ADMIN_TOKEN" https://mail.example.com/admin/v1/version

Bind the admin surface to a separate local port with [server] admin_bind if you prefer it off the public listener.

Endpoint map

Deploy & health

Endpoint	Purpose
`GET /admin/v1/version`	Version and `migrations_applied` — the post-deploy check.
`GET /admin/v1/stats`	Instance statistics.
`GET /admin/v1/logs/summary`	Aggregated recent-log summary.
`GET /metrics`	Prometheus metrics (operations).

Accounts and organizations

Endpoint	Purpose
`GET/POST /admin/v1/accounts`, `POST …/batch`	List and provision accounts.
`GET/PUT/DELETE /admin/v1/accounts/{id}`	Inspect, update, delete (delete enqueues the erasure phase machine).
`POST …/{id}/enable`, `…/disable`, `PUT …/{id}/role`	Lifecycle and role.
`GET …/{id}/capabilities`	Effective capability set.
`GET …/{id}/mailboxes`, `emails`, `identities`, `sieve` (+`/{name}/activate`), `calendars`, `events`, `contacts`, `tasks`, `files`	Per-account data views for support tooling.
`GET/POST /admin/v1/tenants`, `GET/PUT /admin/v1/tenants/{id}`	Organizations.
`PUT …/{id}/branding`, `…/{id}/plan`, `GET …/{id}/capabilities`, `…/capabilities-matrix`	Per-organization branding, plan, and capability toggles.

Security

Endpoint	Purpose
`GET/DELETE /admin/v1/bans`, `DELETE /admin/v1/bans/{ip}`	The in-binary fail2ban’s ban list.
`GET/POST/DELETE /admin/v1/whitelist(/{ip})`	The trust whitelist.

Mail operations

Endpoint	Purpose
`GET /admin/v1/queue`, `GET/DELETE …/{id}`, `POST …/{id}/retry`, `POST …/flush`	The outbound delivery queue.
`GET /admin/v1/spam/stats`, `POST …/test`, `POST …/feedback/{tenant}`, `POST …/retrain/{tenant}`, `GET/PUT …/blocklist`, `GET …/model`	The spam pipeline’s corpus and model.
`POST /admin/v1/reindex-blobs`	Blob-related reindex maintenance.

Configuration

Endpoint	Purpose
`PUT /admin/v1/config`	Set runtime config overrides (`{"overrides": {"key": value}}`) — see configuration. `GET` returns a usage hint, not a dump, at v0.30.0.

Conventions

Responses are JSON; errors carry a machine-readable reason and an HTTP status that means what it says.
Everything here is also reachable from the CLI — both are thin adapters over the same orchestration, so behaviour is identical.
The API is per organization where data is organization-scoped; there is deliberately no cross-tenant data view.

Get Started

Operator Manual

Developer / JMAP API

Architecture Reference

Reference

Authentication

Endpoint map

Deploy & health

Accounts and organizations

Security

Mail operations

Configuration

Conventions

​Authentication

​Endpoint map

​Deploy & health

​Accounts and organizations

​Security

​Mail operations

​Configuration

​Conventions

Authentication

Endpoint map

Deploy & health

Accounts and organizations

Security

Mail operations

Configuration

Conventions