Upgrade to 0.7.0

Migrate search filters, typed search strings, provider capabilities, and page tokens.

Fluxmail 0.7.0 gives the CLI, MCP, REST API, and email providers the same portable search contract. Existing mailbox data and credentials do not need a database migration, but search clients and custom providers must update before upgrading.

Find your migration

Only follow the rows for interfaces you use. If you do not call search from scripts or custom clients, you do not need to migrate mailbox data, configuration, or credentials.

Interface	Required changes
CLI	Replace `--unread-only` with `--read false`, replace `--starred-only` with `--starred true`, pass a boolean to `--has-attachment`, and use typed syntax for `emails search`.
MCP	Replace the `unreadOnly` and `starredOnly` arguments with `read` and `starred`. Convert `after` and `before` timestamps to `YYYY-MM-DD` calendar dates. Treat `list_emails.text` as literal text and use typed syntax for `search_emails.query`.
REST	Replace the `unreadOnly` and `starredOnly` query parameters with `read` and `starred`. Treat `text` as literal text. The new `query` parameter accepts typed syntax.
Custom providers	Handle `EmailQuery.read` and `EmailQuery.starred` instead of `unreadOnly` and `starredOnly`. Add `Capabilities.search` and advertise both values for each supported boolean filter.

Clients that paginate through any of these interfaces must discard tokens issued before 0.7.0 and restart without a token.

Query changes

Replace unreadOnly with read and replace starredOnly with starred. The new fields accept both boolean values:

{
  "read": false,
  "starred": true,
  "hasAttachment": false
}

hasAttachment is also a true tri-state filter. An omitted value does not filter messages, true requires a non-inline attachment, and false excludes messages with a non-inline attachment.

The text field is now literal. Gmail and Outlook operators inside text no longer reach the provider as operators. Move Gmail search syntax or Outlook KQL to rawProviderQuery.

Dates now require YYYY-MM-DD. Fluxmail treats after as inclusive and before as exclusive UTC boundaries over the received or provider internal time. A query fails when after is not earlier than before.

CLI and MCP search strings

The positional value for fluxmail emails search and the MCP search_emails.query field now use typed portable syntax:

from:ann@example.com is:unread after:2026-07-01 quarterly report

See Email search for the grammar. Use rawProviderQuery through a structured list request when an integration needs Gmail or Outlook syntax.

The CLI search flags now accept explicit boolean values:

fluxmail emails list --read false --starred true --has-attachment false

Capability changes for custom providers

Capabilities has a required search field. It lists portable filters, folder-role availability, and native query support. serverSearch remains deprecated throughout 0.7.x so clients have time to migrate.

Custom providers must implement both values of every boolean filter they advertise. Omit a filter from search.filters when the provider cannot implement both values correctly.

Fluxmail returns unsupported_capability without running the search when an account reports that a filter or native query is unavailable. Capabilities marked unknown are checked when the request runs.

Custom folders do not participate in portable capability intersection. Discover them on the selected account with listFolders().

Page tokens

All page tokens issued before 0.7.0 are invalid immediately. Start each paginated search again without a token.

New tokens are signed by the Fluxmail server and expire after one hour. A continuation request must use the same account, normalized query, and page size. Replacing the instance encryption key invalidates outstanding tokens.

Custom clients

Custom clients should send typed searches through the REST query parameter or MCP search_emails.query. Do not import Fluxmail's internal packages directly. Remove autocomplete entries for unsupported boolean expressions and relative dates. Keep provider-native queries limited to one account.

An incomplete page may be empty even when more candidates exist. Follow a small number of empty incomplete pages automatically, then let the person choose whether to continue.