API

LiteMX API

The API backs the CLI and MCP paths. Use it directly when automation needs mailbox, domain, message, draft, token, audit, or retention operations.

OpenAPI

The machine-readable OpenAPI document is served by the API Worker at https://litemx-api-worker.litemx.workers.dev/openapi.json.

https://litemx-api-worker.litemx.workers.dev/openapi.json

Authentication

API requests use bearer tokens. Use the founder admin token for operator setup, then create scoped LiteMX tokens for agents, scripts, and mailbox-specific automation.

api-auth.sh

curl -H "Authorization: Bearer <token>" \
  https://litemx-api-worker.litemx.workers.dev/api/messages?mailbox=support@example.com

Scoped tokens can limit mailbox access and separate read, search, draft, send, and audit actions. Read scope does not imply send scope.

Endpoint Groups

Group	Endpoints
System	`GET /openapi.json` `GET /api/health` `GET /api/bootstrap`
Domains	`GET /api/domains` `POST /api/domains` `GET /api/domains/{domain}/status` `GET /api/domains/{domain}/dns-plan` `PUT /api/domains/{domain}/readiness`
Mailboxes and routing	`GET /api/mailboxes` `POST /api/mailboxes` `GET /api/mailboxes/{mailbox}` `DELETE /api/mailboxes/{mailbox}` `GET /api/mailboxes/{mailbox}/retention` `PUT /api/mailboxes/{mailbox}/retention` `GET /api/aliases` `POST /api/aliases` `DELETE /api/aliases/{alias}` `GET /api/catchalls/{domain}` `PUT /api/catchalls/{domain}`
Messages and threads	`GET /api/messages` `GET /api/messages/search` `GET /api/messages/{id}` `POST /api/messages/{id}/reply` `GET /api/threads` `GET /api/threads/{id}` `POST /api/threads/{id}/reply` `POST /api/threads/{id}/drafts`
Drafts and sending	`GET /api/drafts` `POST /api/drafts` `GET /api/drafts/{id}` `POST /api/drafts/{id}/send` `POST /api/send`
Tokens, audit, retention, MCP	`GET /api/tokens` `POST /api/tokens` `DELETE /api/tokens/{id}` `GET /api/audit` `POST /api/retention/run` `GET /mcp` `POST /mcp`
Inbound	`POST /api/inbound/simulate` `POST /api/inbound/ses`

Errors And Send Preflight

Error responses include structured fields used by the CLI for operator output. Treat domain readiness errors, outbound-disabled errors, send-limit errors, and provider production-access failures as hard stops.

Send endpoints share the same outbound preflight as the CLI and MCP: verified provider readiness, explicit send scope for scoped tokens, per-message recipient caps, plan limits, policy checks, and provider approval.