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 serveCopy 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:
| Capability | Access |
|---|---|
admin.accounts | Connect or reauthorize mailboxes, update IMAP settings, and configure Outlook or IMAP sender addresses. |
admin.api_keys | List, create, update, and revoke API keys. |
admin.members | Manage members, invitations, roles, statuses, and sessions. |
admin.audit | Read security audit events. |
admin.license | Read 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.licenseRemote 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
| Endpoint | Description |
|---|---|
GET /api/v1/accounts | List the email accounts available to the API key. |
GET /api/v1/admin/accounts | List mailbox metadata across the instance without granting access to private mail. Requires admin.accounts. |
POST /api/v1/accounts/connections | Connect a Gmail, Outlook or IMAP mailbox, or reauthorize a mailbox you own. |
POST /api/v1/admin/connections | Connect 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/tests | Test IMAP and SMTP settings without saving an account. Requires admin.accounts. |
PATCH /api/v1/accounts/{accountId}/access | Share 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}/connection | Disconnect 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
| Endpoint | Description |
|---|---|
GET /api/v1/admin/api-keys | List API key metadata without returning plaintext secrets. Requires admin.api_keys. |
GET /api/v1/me/api-keys | List your API key metadata without returning plaintext secrets. |
POST /api/v1/admin/api-keys | Create 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-keys | Create 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
| Endpoint | Description |
|---|---|
GET /api/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId} | Download one attachment as raw bytes. |
Audit events
| Endpoint | Description |
|---|---|
GET /api/v1/admin/audit-events | List recent security audit events. Requires admin.audit. |
Authentication
| Endpoint | Description |
|---|---|
GET /api/v1/me/sessions | List your member sessions and identify the current session. |
POST /api/v1/auth/enroll | Set your first password with an enrollment code and receive a member session. |
POST /api/v1/auth/login | Sign in with a member email and password and receive a member session. |
POST /api/v1/auth/logout | Revoke the session used for this request. |
POST /api/v1/auth/password-reset | Set a new password with a reset code and receive a member session. |
PUT /api/v1/me/password | Change your password and revoke your other sessions and OAuth connections. |
DELETE /api/v1/me/sessions/{sessionId} | Revoke one of your member sessions. |
Delivery operations
| Endpoint | Description |
|---|---|
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
| Endpoint | Description |
|---|---|
GET /api/v1/accounts/{accountId}/drafts/{draftId} | Read an existing draft by its provider ID. Requires mail.drafts. |
POST /api/v1/accounts/{accountId}/drafts | Create 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
| Endpoint | Description |
|---|---|
GET /api/v1/accounts/{accountId}/folders | List folders in an email account. |
PATCH /api/v1/accounts/{accountId}/imap/folders | Update special-folder overrides for an IMAP mailbox you own or administer. |
PATCH /api/v1/admin/accounts/{accountId}/imap/folders | Update the folder overrides for an IMAP account. Requires admin.accounts. |
Labels
| Endpoint | Description |
|---|---|
GET /api/v1/accounts/{accountId}/labels | List Gmail user labels or Outlook categories in an email account. |
License
| Endpoint | Description |
|---|---|
GET /api/v1/admin/license | Get license status and usage without returning the configured license key. Requires admin.license. |
POST /api/v1/admin/license/activate | Validate and activate a Fluxmail license key. Requires admin.license. |
DELETE /api/v1/admin/license | Release the stored license and return this instance to Personal limits. Requires admin.license. |
Members
| Endpoint | Description |
|---|---|
GET /api/v1/admin/members | List members with their roles, status and mailbox and API key counts. Requires admin.members. |
GET /api/v1/admin/members/{memberId}/sessions | List a member's sessions. Requires admin.members. |
GET /api/v1/me | Get the name, role and status of the authenticated member. |
POST /api/v1/admin/members | Create a pending member and return a one-time enrollment code. Requires admin.members. |
POST /api/v1/admin/members/{memberId}/invitation | Issue a new one-time enrollment code for a pending member. Requires admin.members. |
POST /api/v1/admin/members/{memberId}/password-reset | Issue 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/me | Change 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
| Endpoint | Description |
|---|---|
GET /api/v1/accounts/{accountId}/messages | List 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/actions | Apply one mailbox action to a batch of messages. |
POST /api/v1/messages/search | Search up to 20 email accounts with one portable query. |
OAuth applications
| Endpoint | Description |
|---|---|
GET /api/v1/admin/oauth-apps | Get 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
| Endpoint | Description |
|---|---|
GET /api/v1/admin/oauth-connections | List OAuth connections for all members or one member. Requires admin.api_keys. |
GET /api/v1/me/oauth-connections | List 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
| Endpoint | Description |
|---|---|
GET /api/v1/accounts/{accountId}/scheduled-sends | List 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
| Endpoint | Description |
|---|---|
GET /api/v1/accounts/{accountId}/send-as | List sender addresses available for an email account. |
PUT /api/v1/accounts/{accountId}/send-as | Replace the configured Outlook or IMAP aliases for an email account. |
Sending
| Endpoint | Description |
|---|---|
POST /api/v1/accounts/{accountId}/messages/{messageId}/forward | Forward a message to one or more recipients now, or schedule the forward for a specified time. |
POST /api/v1/accounts/{accountId}/send | Send a message now or schedule it for a specified time. |
POST /api/v1/accounts/{accountId}/send/preview | Resolve 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
| Endpoint | Description |
|---|---|
GET /api/v1 | Return the Fluxmail version and the URL of the OpenAPI document. |
GET /api/v1/status | Return provider and mailbox status for the accounts available to the API key. |
Threads
| Endpoint | Description |
|---|---|
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 providemeta.nextPageToken. - Send and forward requests require an
Idempotency-Keyheader. Their endpoint pages explain safe retries. - API keys use the profiles and capabilities described in Permissions.
- Errors return an
errorobject with a stablecodeandmessage.
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
update_draft
Replace the content of an existing draft. This is a full replacement, not a patch. To keep the quoted original in a reply draft, pass its replyToMessageId again. A quote Fluxmail added earlier is replaced, not repeated.
GET /api/v1/accounts
List the email accounts available to the API key.