Upgrade Fluxmail

Before upgrading, check the release notes and the version-specific upgrade guides. Apply every relevant migration guide between your current version and the target version. Clients may need updates before the server, especially when response formats change.

1. Record the current installation

Record your installed package version or Docker image digest, deployment configuration, and data paths. Choose the target release explicitly so you can reproduce the upgrade.

Check for pending scheduled sends and plan the interruption. Sends missed during downtime can run when the server starts again.

2. Back up before changing versions

Stop all processes sharing the data directory and back up the complete installation. Include the matching encryption key and external secrets. Keep the backup outside the data volume you are upgrading.

A database migration can make the store unreadable by an older release. Downgrading the executable or image alone may not restore the previous service.

3. Install the target release

For a global installation, replace <version> with the release you selected:

npm install -g fluxmail@<version>

For Docker, set the selected release tag or digest in the Compose image field, then pull and recreate the service:

docker compose pull fluxmail
docker compose up -d fluxmail

Keep the existing data volume mounted. For local stdio, restart each MCP client so it launches the updated executable. For a local HTTP installation, restart the server.

Scheduled delivery now belongs to serve or scheduled run. Stdio-only installations must start a persistent worker using the same data directory as their MCP clients. See Keep scheduled delivery running. Remote HTTP and standard Docker installations already run the worker through serve.

This change migrates the SQLite store to format 6 to persist retry deadlines. Stop every process sharing the store before the first upgraded process opens it. Existing schedules and delivery records are retained. Existing retry delays cannot be reconstructed, so due schedules may be eligible immediately; subsequent retry delays survive restarts. Queued mail remains stored, and overdue mail may send when a worker starts. Rollback requires the matching pre-upgrade backup.

4. Verify the upgrade

fluxmail status
fluxmail accounts list
fluxmail --mail-account <account-id> folders list

For Docker, prefix each command with docker compose exec fluxmail. Then check your MCP or REST client using its own credentials. Verify that the selected mailboxes and permissions still match the client's intended access. Do not send a test email just to check connectivity.

Keep the backup until these checks pass. If startup fails, inspect Local logs and the upgrade guide for your target release.

If you need to roll back

Stop the new version, preserve its current data for diagnosis, and restore the complete pre-upgrade backup with the matching older release. Do not point an older binary at a migrated store.

A restore loses local changes since the backup. It does not undo mail already sent or changed at the provider. Review delivery and scheduling state before resuming work to avoid repeating an action.