Fluxmail

REST API

Use Fluxmail from local scripts and applications through the versioned JSON 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:

CapabilityAccess
admin.accountsConnect or reauthorize mailboxes, update IMAP settings, and configure Outlook or IMAP sender addresses.
admin.api_keysList, create, update, and revoke API keys.
admin.membersManage members, invitations, roles, statuses, and sessions.
admin.auditRead security audit events.
admin.licenseRead license status and activate a license key.

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

Accounts

EndpointDescription
GET /api/v1/accountsList the email accounts available to the API key.
GET /api/v1/admin/accountsList mailbox metadata across the instance without granting access to private mail. Requires admin.accounts.
POST /api/v1/accounts/connectionsConnect a Gmail, Outlook or IMAP mailbox, or reauthorize a mailbox you own.
POST /api/v1/admin/connectionsConnect a Gmail, Outlook, or IMAP mailbox for any active or invited member, or reauthorize a mailbox you own. Requires admin.accounts.
POST /api/v1/admin/imap/testsTest IMAP and SMTP settings without saving an account. Requires admin.accounts.
PATCH /api/v1/accounts/{accountId}/accessShare a mailbox you own with every member or with selected members, make it private, or hand it to another member.
PATCH /api/v1/admin/accounts/{accountId}Change ownership or sharing of a mailbox you own. Requires admin.accounts. To move another member's mailboxes, remove the member with a new owner for their mailboxes.
DELETE /api/v1/accounts/{accountId}/connectionDisconnect a mailbox you own or administer and remove its stored credentials.
DELETE /api/v1/admin/accounts/{accountId}Disconnect a mailbox and remove its stored credentials. Requires admin.accounts.

API keys

EndpointDescription
GET /api/v1/admin/api-keysList API key metadata without returning plaintext secrets. Requires admin.api_keys.
GET /api/v1/me/api-keysList your API key metadata without returning plaintext secrets.
POST /api/v1/admin/api-keysCreate an API key and return its plaintext secret once. A key you create for another member reaches only mailboxes you both can read. Requires admin.api_keys.
POST /api/v1/me/api-keysCreate an API key for yourself and return its secret once.
PATCH /api/v1/admin/api-keys/{keyId}Update the permissions or mailbox scope of an API key. Requires admin.api_keys.
DELETE /api/v1/admin/api-keys/{keyId}Revoke an API key. Requires admin.api_keys.
DELETE /api/v1/me/api-keys/{keyId}Revoke an API key you own.

Attachments

EndpointDescription
GET /api/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId}Download one attachment as raw bytes.

Audit events

EndpointDescription
GET /api/v1/admin/audit-eventsList recent security audit events. Requires admin.audit.

Authentication

EndpointDescription
GET /api/v1/me/sessionsList your member sessions and identify the current session.
POST /api/v1/auth/enrollSet your first password with an enrollment code and receive a member session.
POST /api/v1/auth/loginSign in with a member email and password and receive a member session.
POST /api/v1/auth/logoutRevoke the session used for this request.
POST /api/v1/auth/password-resetSet a new password with a reset code and receive a member session.
PUT /api/v1/me/passwordChange your password and revoke your other sessions and OAuth connections.
DELETE /api/v1/me/sessions/{sessionId}Revoke one of your member sessions.

Delivery operations

EndpointDescription
GET /api/v1/accounts/{accountId}/delivery-operations/{operationId}Check whether a send or forward succeeded, failed or has an uncertain outcome. Requires mail.send.

Drafts

EndpointDescription
GET /api/v1/accounts/{accountId}/drafts/{draftId}Read an existing draft by its provider ID. Requires mail.drafts.
POST /api/v1/accounts/{accountId}/draftsCreate a new draft or a reply draft in an email account.
PUT /api/v1/accounts/{accountId}/drafts/{draftId}Replace the full content of an existing draft.
DELETE /api/v1/accounts/{accountId}/drafts/{draftId}Delete an existing draft from an email account.

Folders

EndpointDescription
GET /api/v1/accounts/{accountId}/foldersList folders in an email account.
PATCH /api/v1/accounts/{accountId}/imap/foldersUpdate special-folder overrides for an IMAP mailbox you own or administer.
PATCH /api/v1/admin/accounts/{accountId}/imap/foldersUpdate the folder overrides for an IMAP account. Requires admin.accounts.

Labels

EndpointDescription
GET /api/v1/accounts/{accountId}/labelsList Gmail user labels or Outlook categories in an email account.

License

EndpointDescription
GET /api/v1/admin/licenseGet license status and usage without returning the configured license key. Requires admin.license.
POST /api/v1/admin/license/activateValidate and activate a Fluxmail license key. Requires admin.license.
DELETE /api/v1/admin/licenseRelease the stored license and return this instance to Personal limits. Requires admin.license.

Members

EndpointDescription
GET /api/v1/admin/membersList members with their roles, status and mailbox and API key counts. Requires admin.members.
GET /api/v1/admin/members/{memberId}/sessionsList a member's sessions. Requires admin.members.
GET /api/v1/meGet the name, role and status of the authenticated member.
POST /api/v1/admin/membersCreate a pending member and return a one-time enrollment code. Requires admin.members.
POST /api/v1/admin/members/{memberId}/invitationIssue a new one-time enrollment code for a pending member. Requires admin.members.
POST /api/v1/admin/members/{memberId}/password-resetIssue a one-time password reset code for a member. Requires admin.members.
PATCH /api/v1/admin/members/{memberId}Change a member's name, email, role or status. Requires admin.members.
PATCH /api/v1/meChange the name of the signed-in member.
DELETE /api/v1/admin/members/{memberId}Remove a member permanently. Their mailboxes go to the member named in reassignTo; without it, they must own no mailboxes. Their API keys, and keys they created for others, are revoked. Requires admin.members.
DELETE /api/v1/admin/members/{memberId}/sessions/{sessionId}Revoke one of a member's sessions. Requires admin.members.

Messages

EndpointDescription
GET /api/v1/accounts/{accountId}/messagesList and filter messages in an email account.
GET /api/v1/accounts/{accountId}/messages/{messageId}Get one message by its provider ID.
POST /api/v1/accounts/{accountId}/messages/actionsApply one mailbox action to a batch of messages.
POST /api/v1/messages/searchSearch up to 20 email accounts with one portable query.

OAuth applications

EndpointDescription
GET /api/v1/admin/oauth-appsGet safe OAuth application metadata without returning client secrets. Requires admin.accounts.
PUT /api/v1/admin/oauth-apps/{provider}Save an OAuth application in encrypted instance settings. Requires admin.accounts.
DELETE /api/v1/admin/oauth-apps/{provider}Remove a stored OAuth application. Requires admin.accounts.

OAuth connections

EndpointDescription
GET /api/v1/admin/oauth-connectionsList OAuth connections for all members or one member. Requires admin.api_keys.
GET /api/v1/me/oauth-connectionsList the MCP clients you have connected with OAuth.
PATCH /api/v1/me/oauth-connections/{grantId}Replace or clear the mailbox allowlist for an OAuth connection you own.
DELETE /api/v1/admin/oauth-connections/{grantId}Disconnect a member's MCP client and revoke its OAuth tokens. Requires admin.api_keys.
DELETE /api/v1/me/oauth-connections/{grantId}Disconnect one of your MCP clients and revoke its OAuth tokens.

Scheduled sends

EndpointDescription
GET /api/v1/accounts/{accountId}/scheduled-sendsList scheduled messages in an email account.
DELETE /api/v1/accounts/{accountId}/scheduled-sends/{scheduleId}Cancel a pending scheduled send and keep its provider draft.

Sender addresses

EndpointDescription
GET /api/v1/accounts/{accountId}/send-asList sender addresses available for an email account.
PUT /api/v1/accounts/{accountId}/send-asReplace the configured Outlook or IMAP aliases for an email account.

Sending

EndpointDescription
POST /api/v1/accounts/{accountId}/messages/{messageId}/forwardForward a message to one or more recipients now, or schedule the forward for a specified time.
POST /api/v1/accounts/{accountId}/sendSend a message now or schedule it for a specified time.
POST /api/v1/accounts/{accountId}/send/previewResolve the sender, recipients and attachments without sending mail. Requires mail.send, plus mail.drafts for an existing draft or mail.read for a reply.

Server

EndpointDescription
GET /api/v1Return the Fluxmail version and the URL of the OpenAPI document.
GET /api/v1/statusReturn provider and mailbox status for the accounts available to the API key.

Threads

EndpointDescription
GET /api/v1/accounts/{accountId}/threads/{threadId}Get a complete email thread by its provider ID.

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.

Last updated