# comail > comail is an authorization layer between a Gmail mailbox and the AI agents that read and write it over MCP. What an agent can read is determined by two Gmail labels belonging to that agent. comail checks those labels against the thread on every request before it calls the Gmail API. comail supports Gmail and Google Workspace accounts. It is in private beta. ## Architecture The mailbox owner grants comail an OAuth authorization on their Google account, once, from the web dashboard. Installing the Gmail add-on is optional and grants nothing extra. comail holds that grant. Agents do not. Each agent is issued its own MCP endpoint URL and its own bearer key, and authenticates to comail rather than to Google. comail calls the Gmail API on the agent's behalf, and only on threads that agent's labels permit. Revoking an agent invalidates its key. It does not affect any other agent, and it does not require the owner to re-authorize the mailbox. ## Objects **Agent** — a named identity that may access the mailbox. Has a status (active, suspended, revoked, pending setup), two Gmail labels, a default `view` policy, agent-wide `draft` / `send` / `modify` defaults, an MCP endpoint, and a key. **Ruleset** — optional, one per agent. An ordered list of rules that keep the agent's labels applied on the owner's behalf. Rules never grant access directly; they only write labels. **Rule** — a `(policy, target)` pair. `policy` is `allow` or `deny`. `target` is a participant email address, a participant domain, one of the owner's own Gmail labels, or a single thread. **Pending action** — an action an agent requested that requires owner approval before it takes effect. Currently: sending a message. ## Access model Every agent owns exactly two Gmail labels: - `co:` — grants a thread to that agent - `no-co:` — withholds a thread from that agent and one default policy, `allow` or `deny`, for threads carrying neither. For a given agent and thread, `view` resolves in this order, first match winning: 1. The thread carries `no-co:` — denied. 2. The thread carries `co:` — allowed. 3. Otherwise — the agent's default policy. Two setups follow from the default: - **Allow-list** (default `deny`) — the agent reads only threads carrying its `co:` label. - **Deny-list** (default `allow`) — the agent reads the mailbox except threads carrying its `no-co:` label. `no-co:` outranks `co:` in both, so a label applied by hand always withholds a thread, including one a rule granted. This is evaluated against the thread's current labels on every request. There is no snapshot and no separate index. Applying a label grants a thread on the agent's next call; removing it revokes the thread on the agent's next call. ## Applying the labels Four equivalent ways, because the label is the only thing comail reads: - by hand, in any Gmail client, including mobile - by a Gmail filter the owner already wrote - from the comail web dashboard, or from the optional Gmail add-on - by a comail rule, which comail evaluates against arriving and changing threads and uses to keep the agent's labels applied Rules are automation, not a second source of truth. Their only effect is to write labels. Gmail can hide a label from the label list and from the message list, independently. comail's labels are hidden on creation. The owner may show either label for any agent. ## Permissions | Permission | Grants | Scoped by | Approval gate | | --- | --- | --- | --- | | `view` | Search, list and read threads | The agent's `co:` and `no-co:` labels, and its default policy | none | | `draft` | Create and edit drafts | Agent-wide default | none | | `send` | Deliver mail from the owner's address | Agent-wide default | optional: hold every send | | `modify` | Apply labels, archive, mark read | Agent-wide default | optional | `view` is the only permission scoped per thread. The others are agent-wide switches. An agent cannot draft, send or modify a thread it cannot view, so the labels bound everything else. An agent holding `modify` may write labels on threads it can already view. It cannot write any label beginning `co:` or `no-co:`. ## How rules write labels A rule is matched against a thread when the thread arrives and when it changes. Rules are ordered and the first match wins. An `allow` match applies `co:` to the thread. A `deny` match applies `no-co:`. A thread matching no rule is left alone and falls to the agent's default policy. A rule matches a thread when its target matches any participant on that thread (for address and domain targets), any label on that thread (for label targets), or the thread's id (for thread targets). Order matters. `deny label:Board` placed above `allow domain:acme.com` withholds a board thread whose participants are on the company domain. Reversing the two shares it. Because participants can be added to a thread after it arrives, a rule can withdraw a thread the agent could previously read. A label the owner set by hand is never overwritten by a rule. ## Inspecting an agent's scope Searching `label:"co:"` in any Gmail client returns exactly the set of threads that agent can read, if it is an allow-list agent. For a deny-list agent, searching `-label:"no-co:"` returns the same. This requires no comail surface and works on mobile. It is the intended way to audit an agent. ## MCP interface Standard Model Context Protocol over HTTP. Any MCP client can connect: Claude, Cursor, or a custom agent. There is no comail SDK. ```json { "mcpServers": { "inbox-investors": { "url": "https://mcp.comail.io/a/investor-relations", "headers": { "Authorization": "Bearer cml_live_..." } } } } ``` | Tool | Effect | Requires | | --- | --- | --- | | `search_threads` | Search the mailbox | `view` | | `get_thread` | Read a thread and its messages | `view` | | `create_draft` | Create a draft or a reply | `draft` | | `update_draft` | Revise a draft the agent created | `draft` | | `send_message` | Send a draft | `send`, or enqueued as a pending action | | `modify_labels` | Apply labels, archive, mark read | `modify` | Threads an agent cannot view are absent from its search results. Fetching one by id returns an authorization error, not a redacted document. If `send` is gated on approval, `send_message` creates a pending action and returns without delivering. The owner approves, edits or rejects it. Revoking an agent cancels its pending actions. ## Control surfaces There are three, and the first is Gmail. **Gmail.** Adding or removing an agent's `co:` or `no-co:` label on a thread grants or withholds that thread, from any Gmail client, including mobile. Gmail filters can apply the labels on delivery. Gmail's label visibility settings control whether the owner sees them. No comail surface is involved. **The web dashboard.** Agents, keys, default policies, `draft` / `send` / `modify` defaults, rules, the approval queue, the full audit log with search and filters, and billing. Everything Gmail has nowhere to put. **The Gmail add-on.** Optional. A contextual surface for the thread the owner is reading: why an agent can or cannot see this thread, the approval queue, and internal messages between the owner and an agent. It shows recent activity only. Every access decision is recorded: the agent, the action, the target, the result, and which label or default policy produced it. ## Pricing $99 per month, per inbox, for up to 10 agents. This is the early-bird rate for the private beta. Beta users keep $99 per month after general launch, for as long as the subscription stays active. Billing starts when the inbox is provisioned. ## Access Private beta, onboarding in batches. Applications are taken at and require an email address and, optionally, a description of the intended use. ## History comail launched in 2015 as a shared-inbox tool. It let a mailbox owner give another person scoped access to their mail, using allow/deny rules over senders, domains and labels, and an approval queue for outbound mail. The rule engine is carried over, but it now writes Gmail labels rather than deciding access itself. The collaborators are now agents.