REST API

Fluxmail exposes a REST API at /api/v1 alongside its MCP endpoint. It uses the same connected mailboxes, permissions, and plan limits as MCP.

Start locally

Complete the quickstart, then create an API key and start the HTTP server:

fluxmail apikey create \
  --name local-script

fluxmail serve

Copy the fmk_... key when Fluxmail displays it. The local base URL is http://localhost:8977/api/v1.

Pass the key as a bearer token. For example, list the accounts available to the key:

export FLUXMAIL_API_KEY='fmk_...'

curl http://localhost:8977/api/v1/accounts \
  -H "Authorization: Bearer $FLUXMAIL_API_KEY"

Use the returned account ID in mailbox routes. If you expose the HTTP server outside your computer, protect it with HTTPS and a firewall or reverse proxy.

Administrative access

Routes under /api/v1/admin accept a member session or API key. A session must belong to a current administrator. An API key must belong to a current administrator and include the capability for the requested operation:

The first member is the initial administrator. Administrators can use their CLI session directly. Create an administrative API key only when automation needs these routes:

fluxmail apikey create \
  --name instance-admin \
  --profile full \
  --admin admin.accounts \
  --admin admin.api_keys \
  --admin admin.members \
  --admin admin.audit \
  --admin admin.license

Remote administrative requests require HTTPS. Requests from the local computer can use HTTP.

If a reverse proxy terminates TLS and connects to Fluxmail from a non-loopback address, set FLUXMAIL_TRUST_PROXY=1. Enable it only when the proxy overwrites forwarded headers and prevents clients from reaching Fluxmail directly.

Endpoint reference

Common behavior

• JSON responses put results in data. Paginated responses provide meta.nextPageToken.
• Send and forward requests require an Idempotency-Key header. Their endpoint pages explain safe retries.
• API keys use the profiles and capabilities described in Permissions.
• Errors return an error object with a stable code and message.

OpenAPI schema

The OpenAPI 3.1 schema is public:

curl http://localhost:8977/api/v1/openapi.json \
  -H "Authorization: Bearer $FLUXMAIL_API_KEY"

Use the schema or the endpoint pages for request parameters, JSON bodies, and response details.