Overview
How Fluxmail connects agents and apps to Gmail, Outlook, and IMAP through MCP, REST API, and CLI.
Fluxmail is self-hosted email infrastructure for agents and apps. It connects to Gmail, Microsoft 365, Outlook.com, and IMAP/SMTP mailboxes, then provides one service for working with them.
Features
- 📬 Connect Gmail, Google Workspace, Microsoft 365, Outlook.com, and IMAP/SMTP mailboxes to one instance.
- 🤖 Give agents MCP tools to list, search, read, draft, reply, forward, send, schedule, and organize email.
- 🔌 Use the same mailbox operations from the versioned REST API and CLI.
- 🧵 Fetch complete messages and threads, work across several mailboxes, and download attachments.
- 🗂️ Mark mail as read, star or archive it, move it between folders, send it to Trash, and manage Gmail labels or Outlook categories.
- 🔐 Limit each client to selected mailboxes and actions with permission profiles or custom policies.
- 👥 Add members and share selected mailboxes on Team and Enterprise plans.
- 🏠 Run Fluxmail locally or in Docker while keeping its database and encrypted provider credentials on your infrastructure.
Choose an interface
| Interface | Use it for |
|---|---|
| MCP | Give AI agents tools to read, search, draft, send, and organize email. |
| REST API | Add email to apps, internal tools, and backend workflows through a versioned JSON API. |
| CLI | Install and run Fluxmail, connect mailboxes, manage members and access, and create API keys. |
MCP and REST use the same mailbox operations, permissions, and provider integrations. The CLI configures and runs that service. You do not need a separate Gmail, Microsoft Graph, or IMAP integration for each client.
How it works
You run Fluxmail on your computer or on a server you control. Agents connect over MCP, apps use the REST API, and the CLI manages either a local or remote named instance. The CLI signs in as a Fluxmail member. Local MCP clients use that member session over stdio, while remote MCP clients use a scoped API key over Streamable HTTP.
Local agents -> authenticated MCP stdio session -> Fluxmail -> Gmail API
Remote agents -> scoped MCP HTTP API key ---------> -> Microsoft Graph
Apps and jobs -> REST API ------------------------> -> IMAP and SMTP
CLI operators -> authenticated control plane ---->Fluxmail stores its SQLite database and encrypted provider credentials on the machine where it runs. It does not copy email content to a service operated by Fluxmail. An MCP client may send content returned by Fluxmail to its model provider, depending on how that client works.
Supported mailboxes
| Provider | Connection method | Notes |
|---|---|---|
| Gmail and Google Workspace | Gmail API with OAuth | Fluxmail includes an OAuth app for local connections. Hosted connections need your own Google Cloud app. |
| Microsoft 365 and Outlook.com | Microsoft Graph with OAuth | You create and control the Microsoft Entra app registration. |
| Other email providers | IMAP for reading and SMTP for sending | The provider must allow IMAP and SMTP access. Some providers require an app password. |
These guides use mailbox for a connected email address. The CLI and API call the same resource an account, so commands such as fluxmail accounts list and fields such as accountId keep that name.
You can connect several mailboxes to one Fluxmail instance. Members and mailbox access rules decide which mailboxes each person can reach. Permission profiles separately control whether a client can only read mail, manage drafts and folders, or send and permanently delete messages.
Choose where to run it
| Setup | Best for | Available interfaces |
|---|---|---|
| Local process | One person using an agent on the same computer | MCP over stdio, plus the CLI |
| Local HTTP server | Local apps, scripts, or MCP clients that connect by URL | REST API, MCP over Streamable HTTP, plus the CLI |
| Docker server | Remote access, shared instances, or several clients | REST API, MCP over Streamable HTTP, plus the CLI |
The Quickstart installs Fluxmail and connects the first mailbox. See Deploy with Docker for a remote or shared server. Authentication and instances explains member sessions, remote CLI profiles, and API keys. For provider-specific steps, see Connect Gmail / Google Workspace, Connect Outlook / Exchange, or Connect IMAP/SMTP.
Read next
- Connect an MCP client covers stdio and Streamable HTTP setup for supported clients.
- MCP tools lists the email operations available to agents.
- Build with REST walks through common app and backend requests.
- Use the CLI covers common administrative workflows.
- CLI reference lists every command and option.
- Permissions explains profiles, custom policies, and mailbox scope.
- Configuration covers server settings, storage paths, and telemetry.
- Teams and plans covers members, shared mailboxes, and plan limits.
- Authentication and instances covers login, enrollment, sessions, and remote CLI profiles.
- Architecture explains data storage and the server's internal structure.
Last updated