# LiteMX API

The API backs the LiteMX CLI and MCP paths. Use it directly to create custom-domain addresses, connect verified destination inboxes, and automate mail operations.

Human-friendly route: https://litemx.com/docs/api

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

## Authentication

`/api/*` and `POST /mcp` use LiteMX bearer tokens:

```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 inventory changes require 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 `/api/*` or `/mcp`, and LiteMX API tokens do not become dashboard sessions.

## Address And Forwarding Workflow

The normal API path is:

1. Register a domain and create its mailbox-backed address.
2. Provision provider resources and publish the returned DNS plan.
3. Call `POST /api/domains/{domain}/verify`; a status read does not persist readiness.
4. Create a forwarding destination.
5. Verify it with the separately delivered one-time challenge.
6. Enable it with `PUT /api/mailboxes/{mailboxId}/forwarding`.

Disabling a destination disables its mailbox bindings and revokes its reverse-reply aliases. General challenge delivery is not available yet: unless the address exactly matches the temporary founder allowlist, creation returns `verificationDelivery: not_configured`. Raw verification tokens are never returned by the API.

## Endpoint Groups

### System And Dashboard

- `GET /openapi.json`
- `GET /api/health`
- `GET /api/bootstrap`
- `POST /dashboard-api/bootstrap`

### Address Setup

- `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

- `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`

### Messages, Threads, Drafts, And Sending

- `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`
- `GET /api/drafts`
- `POST /api/drafts`
- `GET /api/drafts/{id}`
- `POST /api/drafts/{id}/send`
- `POST /api/send`

### Tokens, Audit, And MCP

- `GET /api/tokens`
- `POST /api/tokens`
- `DELETE /api/tokens/{id}`
- `GET /api/audit`
- `GET /mcp`
- `POST /mcp`

Advanced alias, catchall, retention, and compatibility endpoints remain documented in OpenAPI.

## Operator And Provider Ingress

`POST /api/inbound/ses`, `POST /api/inbound/simulate`, and `POST /api/retention/run` require the founder admin token. `POST /webhooks/mailchannels` and `POST /webhooks/mailgun` authenticate provider-signed events rather than customer bearer tokens.

`PUT /api/domains/{domain}/readiness` remains for validated provider evidence and a legacy setup path. It is not a normal self-serve verification shortcut.

## Errors And Send Preflight

Error responses carry structured codes and next actions used by the CLI. Send endpoints share provider-readiness checks, explicit send scope, recipient caps, plan limits, policy checks, suppression checks, and provider approval with CLI and MCP sends.