Troubleshooting

Start by checking the service and connected mailboxes:

fluxmail status
fluxmail accounts list

For Docker, prefix each command with docker compose exec fluxmail.

The fluxmail command is not found

Check whether your shell can find the command:

which fluxmail

If that prints nothing, install Fluxmail globally or run it through npx:

npm install -g fluxmail
npx -y fluxmail@latest status

Some apps use a limited PATH. Run which fluxmail in your terminal and use the returned absolute path in the app's configuration.

The browser cannot finish connecting a mailbox

Local OAuth connections expect the browser and Fluxmail to run on the same computer. Check that port 8976 is available.

A remote server needs FLUXMAIL_PUBLIC_URL set to its public HTTPS address. Gmail also needs a Google Web client, and Outlook needs a Microsoft Entra client secret. Follow Deploy with Docker and the setup guide for Gmail or Outlook.

A mailbox needs to be reconnected

Run fluxmail status to confirm which mailbox needs attention. Then follow the reconnection steps for Gmail, Outlook, or IMAP/SMTP.

Reconnecting updates the saved credentials without changing the mailbox owner or access rules.

MCP or REST returns 401

HTTP clients must send the API key as a bearer token:

Authorization: Bearer fmk_...

Fluxmail shows an API key only when you create it. If the key was lost or revoked, create a new one and update the client.

MCP or REST returns 403

The API key does not have permission for the requested operation or mailbox. Check its permission profile and mailbox allowlist:

fluxmail apikey list

See Permissions to change the profile or mailbox scope.

A Docker server does not respond

Check the container status and recent logs:

docker compose ps
docker compose logs --tail=100 fluxmail

Confirm that port 8977 is reachable and that your reverse proxy forwards requests to it. See Deploy with Docker for the expected public URL and authentication settings.