API

LiteMX API

The API backs the CLI and MCP paths. Use it directly to create custom-domain addresses, connect verified destination inboxes, and automate mail 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/* and /mcp requests use LiteMX bearer tokens. Use the founder admin token for operator setup, then create scoped 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. Account-wide address and forwarding configuration also requires an unrestricted mailbox grant.

Dashboard sign-in is a separate trust boundary. POST /dashboard-api/bootstrap accepts a verified Clerk session; Clerk sessions are not accepted by the API or MCP, and LiteMX API tokens are not dashboard sessions.

Address And Forwarding Workflow

The normal setup path is to register a domain, create its mailbox-backed address, provision provider resources, publish the returned DNS plan, and call POST /api/domains/{domain}/verify. The verification call runs live provider checks and persists readiness. A status read reports current setup but does not replace verification.

To connect an existing inbox, create a forwarding destination, verify it with the separately delivered one-time challenge, then enable that destination with PUT /api/mailboxes/{mailboxId}/forwarding. Disabling a destination also disables its mailbox bindings and revokes its reverse-reply aliases.

Destination challenge delivery is not generally available yet. Unless the destination exactly matches the temporary founder allowlist, creation returns a pending destination and verificationDelivery: not_configured. The API never returns raw verification tokens, so a pending destination cannot be enabled until out-of-band delivery is implemented.

Endpoint Groups

Group	Availability	Endpoints
System and dashboard	Public status; authenticated bootstrap	`GET /openapi.json` `GET /api/health` `GET /api/bootstrap` `POST /dashboard-api/bootstrap`
Address setup	Self-serve	`GET /api/domains` `POST /api/domains` `GET /api/domains/{domain}/status` `GET /api/domains/{domain}/dns-plan` `POST /api/domains/{domain}/provision` `POST /api/domains/{domain}/verify` `GET /api/mailboxes` `POST /api/mailboxes` `GET /api/mailboxes/{mailbox}` `DELETE /api/mailboxes/{mailbox}`
Existing-inbox forwarding	Self-serve API; challenge delivery is limited	`GET /api/forwarding-destinations` `POST /api/forwarding-destinations` `POST /api/forwarding-destinations/{id}/verify` `DELETE /api/forwarding-destinations/{id}` `GET /api/mailboxes/{mailboxId}/forwarding` `PUT /api/mailboxes/{mailboxId}/forwarding`
Advanced routing	Self-serve	`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	Self-serve	`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	Self-serve	`GET /api/drafts` `POST /api/drafts` `GET /api/drafts/{id}` `POST /api/drafts/{id}/send` `POST /api/send`
Tokens, audit, and MCP	Self-serve	`GET /api/tokens` `POST /api/tokens` `DELETE /api/tokens/{id}` `GET /api/audit` `GET /mcp` `POST /mcp`
Operator and provider ingress	Not for normal customer setup	`POST /api/inbound/simulate` `POST /api/inbound/ses` `POST /api/retention/run` `POST /webhooks/mailchannels` `POST /webhooks/mailgun`
Compatibility	Advanced or legacy	`PUT /api/domains/{domain}/readiness`

Operator And Compatibility Endpoints

POST /api/inbound/ses, POST /api/inbound/simulate, and POST /api/retention/run require the founder admin token. Provider webhook routes do not accept a customer bearer token; they authenticate provider-signed delivery events.

PUT /api/domains/{domain}/readiness remains for validated provider evidence and the legacy Cloudflare setup path. It is not the normal self-serve verification shortcut. Use provision, publish the DNS plan, and then call verify for current integrations.

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.