Agent connections and permissions

OAuth connections and agent keys control which mailboxes a client can access and what it can do. MCP clients sign in with OAuth by default. REST automation and clients without OAuth use a separate key for each workflow.

Approve and revoke OAuth connections

Select the permissions your agent needs in the MCP setup instructions, then start sign-in from your MCP client. In the browser, choose one workspace and its mailboxes. If the workspace has one mailbox, it starts selected; otherwise, select the mailboxes to include. Access to all current and future mailboxes you can use in that workspace requires a separate opt-in.

The bare MCP URL requests Full mail access: read, drafts, organize, Trash, and send. Every requested permission starts checked, including Send emails, and you can uncheck any of them before approving. Permanent deletion is excluded from the bare URL and requires an explicit scope selection. Consent can't add a permission the client didn't request. Client names are supplied by the client; a name does not mean Fluxmail has verified the app.

Connections shows each approval's client, mailboxes, permissions, last use, and expiration. Revoke a connection there to stop its access tokens and refreshes. Repeated approvals create independent connections, so revoking one does not disconnect the others. Removing a server from your client does not revoke its Cloud connection.

Access tokens last 15 minutes. Clients rotate refresh tokens, which expire after 30 days without rotation. Each approval has a 90-day absolute limit; sign in and approve access again when it expires. Reuse of an old refresh token revokes that connection. Concurrent refreshes with the same token can also require a new sign-in.

Browser logout leaves approved connections active. Password recovery revokes them. Losing workspace membership or mailbox access stops the corresponding delegated access. Expanding permissions requires fresh consent and new tokens.

Choose the required scopes

Select the mailboxes the client needs, then choose one or more scopes:

The setup and key forms offer Read only (read), Read and write (read, drafts, organize, and Trash), and Full mail access (read, drafts, organize, Trash, and send). Choose Custom to pick individual scopes or enable permanent deletion. OAuth setup defaults to Full mail access. New key forms default to Read only unless you have explicitly selected permissions in agent setup. Permanent deletion stays off in every preset.

These scopes and presets match the capabilities and permission profiles in self-hosted Fluxmail. To narrow an existing authorization, create a replacement with the intended permissions and revoke the old one in Connections or Agent keys.

The MCP URL's scopes query chooses what the client requests at sign-in. Changing or removing it does not change an existing grant. The approved scopes and the user's current mailbox access control every operation.

Scopes are independent. For example, an agent that reads messages and prepares replies needs both mail.read and mail.drafts. Add mail.send if you also want it to send. Sending a saved draft by draftId needs both mail.send and mail.drafts.

When replying with replyToMessageId, Cloud reads the original message, so the connection needs mail.read along with the draft or send scope. See the operation reference for each operation's required scope.

modify_emails checks its action: flags, labels, archive, and move need mail.organize; trash and untrash need mail.trash; delete needs mail.delete. Generic moves cannot target Trash or Archive, or move messages out of Trash. Use the dedicated actions. Gmail does not permit permanent deletion with Cloud's provider OAuth permissions, even with mail.delete.

Provider consent and agent access

Connecting Google, Microsoft, or an IMAP mailbox authorizes Cloud to work with your provider. Provider consent can cover more operations than you want a particular agent to use. The connection's mailbox selection and scopes enforce that agent's access inside Cloud.

An OAuth connection or agent key cannot connect mailboxes, reveal provider credentials, create other keys, change account settings, or delete your Cloud account. Use a signed-in dashboard session for those actions.

Give your agent explicit instructions before it sends or modifies mail. Messages and attachments can contain instructions written by other people; treat their contents as data. For sends, follow the retry rules.

Store and replace keys

Create a separate named key in Agent keys, selecting its mailboxes and scopes. Cloud displays it once and stores only its SHA-256 hash. OAuth connections and keys share a limit of 100 active authorizations per workspace.

When creating a key, choose 7, 30, 90, or 365 days, or select Never to keep it active until you revoke it. The form selects 90 days by default. Cloud stops accepting a key when it expires or is revoked. To change an existing key's expiration, create a replacement.

Keep tokens in a secret store or private client configuration, outside chat, Git, URLs, logs, and screenshots. If you lose a key, create a replacement and revoke the old one.

To replace a key in use:

1. Create a key with the intended mailboxes and scopes.
2. Update your client's secret and reload the connection.
3. Verify access using the new key's permitted tools.
4. Revoke the old key in the dashboard.

If a token is exposed, revoke it immediately. Revocation stops subsequent authenticated calls. Removing a server from your client does not revoke its Cloud key.

Passwords and recovery

See account settings to change your password or recover access.

Delete your account

See delete your account for what deletion removes. To stop one agent, revoke its connection or key instead.