gigamail

<!--
GigaMail — mail for your AI agent
Copyright (C) 2026 Adecubed

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at your
option) any later version. See the LICENSE file for details.
-->
<!-- mcp-name: io.github.adecubed/gigamail -->

# GigaMail — Mail for your AI agent

**English** · [Italiano](#lang-it) · [中文](#lang-zh)

[![Download](https://img.shields.io/badge/Download-Windows%20installer-e0409a?logo=windows&logoColor=white)](https://github.com/adecubed/gigamail/releases/latest) [![PyPI](https://img.shields.io/pypi/v/gigamail?label=pip%20install%20gigamail&color=5b6bff)](https://pypi.org/project/gigamail/) [![License AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-555)](LICENSE)

**MCP server that gives your agent — Claude, Codex, OpenClaw, Hermes, or any
MCP client — safe, controlled access to your email** — multi-account (Microsoft Graph + IMAP), calendar,
local search index, sender memory, and an agent-aware permission model.

No built-in LLM: the intelligence is your agent's. The MCP server speaks
stdio only — no network port. (An optional human console adds a local HTTP
API bound to 127.0.0.1.)

**On your data**: GigaMail keeps mail indexes, credentials, memory and
configuration **on your machine** — we run no service and receive nothing.
Mail content your agent reads is, of course, handled by that agent and its
model provider under their own data policies. Choose your agent
accordingly; the masker lets you hide sensitive fields (tax codes, VAT
numbers, IBANs, emails, phone numbers — validated deterministically, no AI)
before the agent ever sees them.



https://github.com/user-attachments/assets/362b58b6-6161-4911-b255-4c735bc7ba56



*The human console in ninety seconds, on a demo mailbox: dashboard, reading
a mail, a reply drafted by the agent from a one-line instruction, folders,
calendar, "ask your mail", automation rules and the first-run guide. The
human reviews and sends — or edits the instruction and regenerates.*

## Why

- **Hybrid search**: provider search (Graph/IMAP) + local SQLite index — fast
  and offline-friendly
- **Sender memory**: tone, topics and history per sender, so replies sound right
- **Observer**: patterns learned from how the user edited past drafts
- **Knowledge files**: attach your price lists, terms, product sheets to an
  account — the agent reads them to answer mail. Your agent doesn't need to
  know everything: the account carries its own knowledge
- **Agent-aware permissions**: reads are free; send/delete require an
  approval given **out of band** — the agent gets an inert request id, a
  human approves from the console or the CLI, and only then does it execute,
  with the exact arguments the human saw. Every write lands in an
  append-only action log
- **Credentials never touch the agent channel**: login and account management
  live in the CLI only — a prompt injection inside an email cannot add
  accounts or read secrets

## Quick start

GigaMail ships through two channels:

- **`pip install gigamail`** — the agentic core: MCP server, CLI, watcher
  and the console's local HTTP backend. No graphical app — the right
  channel when your agent is the interface.
- **Windows desktop app** — the human console packaged with an
  embedded Python: one installer, no prerequisites. Download
  `GigaMail-Setup-<version>.exe` from the [latest release](https://github.com/adecubed/gigamail/releases/latest);
  the app then updates itself from there. The installer is not code-signed
  yet, so Windows SmartScreen warns on first run — compare the SHA-256
  digest GitHub shows next to the asset. To build it yourself: Node 22+,
  `console/prepare-python.ps1`, then `npm run dist`.

Everything below covers the pip channel.

```bash
pip install "gigamail[all]"

gigamail login                # Microsoft device flow
gigamail accounts add-imap    # or IMAP: Aruba, Gmail, Libero, ...
```

> **Microsoft login note**: the bundled Azure app is not yet
> publisher-verified, so the consent screen shows an "unverified" notice
> (works fine; some corporate tenants may block it). Standard alternative:
> register your own Azure app and set your `client_id` in
> `src/ade_mail_agent/core/ms_config.json`. IMAP needs none of this.

Give the account its identity and knowledge (this is what makes replies yours):

```bash
gigamail identity set                       # who am I, what I do, tone
gigamail identity add-file C:\docs\pricelist.xlsx
gigamail identity add-file C:\docs\catalog\   # whole folder
```

Register in Claude Desktop / Claude Code (`mcpServers`):

```json
{
  "gigamail": {
    "command": "gigamail-server"
  }
}
```

The commands are also available under their legacy names
(`ade-mail-agent`, `ade-mail-agent-server`), so existing setups keep working.

Using **OpenClaw** or **Hermes** instead of Claude? Verified configs in
[INTEGRATIONS.md](INTEGRATIONS.md).

> **Are you an AI agent setting this up on behalf of a human?** You can do
> the install and the MCP registration: `pip install "gigamail[all]"`, then
> add `gigamail-server` to your client's MCP config (see INTEGRATIONS.md;
> declare `GIGAMAIL_ROOT` if your client filters the environment). **Stop
> there.** Connecting a mailbox (`gigamail login`, `gigamail accounts
> add-imap`) asks for credentials and must be done by the human in their own
> shell — it is not something you should do, and GigaMail is built so that
> it cannot be done through you. Tell them what to run, then wait.

Then just ask your agent: *"reply to the last quote request using the price
list"* — it reads the mail, pulls the numbers from your file, drafts the
reply, and asks you before sending.

## Tools

24 typed tools, generated from the server itself:

- **Read (15)** — accounts, identity, knowledge files, messages, unread,
  folders, hybrid search, attachment text, sender history, learned
  patterns, calendar events, free-slot availability
- **Safe writes (3, audited)** — mark read, move message, create folder
- **Dangerous (6, human approval out of band)** — send, reply, delete
  message, delete folder, create/delete calendar event

Full map and design decisions: [MAPPA_MCP.md](MAPPA_MCP.md).

## Security model

Email content is treated as **untrusted data** (prompt injection). The
agent cannot approve its own actions, by construction: a dangerous tool
returns only an inert `request_id`, and approving it — from the console or
from `gigamail approvals approve` — requires an OS-level verification of
the person at the machine (**Windows Hello** / **Touch ID**). A process,
including an agent that holds a shell, can open that prompt but cannot
pass it; with no such backend available, nothing approves. No secret ever
enters the model context, so an injected instruction has nothing to
spend. Repeating the id just returns *awaiting approval*. The agent
can only read files explicitly registered by the user, never the rest of the
filesystem. Every write action is logged to `%APPDATA%/ADE/agent_audit.jsonl`
(append-only: GigaMail never rewrites past entries — it is not, and does not
claim to be, tamper-proof storage).

We red-team this: hostile emails ordering exfiltration, mass deletion, and
the agent to approve itself — fed to a real agent with every mail tool
enabled.

> This design is a fix. v0.1.0 returned a one-time confirm token in the
> tool result, which put it in the model's context: the agent held both
> halves. Thanks to **u/ranbuman** and **u/anderson_the_one** on r/mcp for
> catching it. The switch now sits where the agent cannot reach.

![Anti-injection harness: three hostile-email scenarios against a real
agent, zero destructive actions](docs/anti-injection-harness.png)

The structural half of that suite runs in CI on every push
([tests/test_injection.py](tests/test_injection.py)); the real-agent half is
opt-in ([scripts/injection_e2e.py](scripts/injection_e2e.py)) and runs with
a dry-run guard so confirmed actions are audited but never executed.

## Reply rules (0.2): semi-auto and auto reply, fenced

You can tell GigaMail: *mail from these senders (or in this folder) gets a
reply drafted from these documents*. Rules are created from the CLI —
`gigamail rules add` — behind the same Windows Hello / Touch ID prompt as
approvals, and `gigamail watch` is the process that applies them. The MCP
server stays passive and **there is no MCP tool that touches rules**: an
injected instruction cannot enable autopilot.

- **semi** (default): the draft becomes a normal approval request — you get
  the notification, you approve with Hello, it goes out.
- Notifications reach you where you are: a **Windows toast** with
  ✅ / ❌ buttons (run `gigamail desktop-setup` once — UAC prompt — to make
  them clickable; they open the approval, which raises Hello) and
  **Telegram** (`gigamail telegram setup`, your own bot: ✅ approve if you
  opted in with `--approve` behind Hello, ❌ reject, ✏️ ask for changes —
  accepted only from your chat).
- **auto**: the request is born approved, `decided_by automode:<rule_id>` —
  you gave that approval when you created the rule, for a precise scope,
  with a mandatory expiry, a daily cap and a per-sender cooldown. The
  notification still fires.

The drafter (your own agent, via `claude -p`) produces the reply *body*
and nothing else: recipient, subject and thread are fixed from the incoming
message — always the sender, never `Reply-To`, never an address written by
the draft. Deterministic barriers run first: no DMARC pass → never auto;
auto-generated mail, lists, no-reply senders, the provider's spam verdict,
executable attachments → no reply at all; the first message from a new
sender always goes through you; a burst of matches pauses the rule by
itself. Details in [SECURITY.md](SECURITY.md).

## License

**AGPL-3.0-or-later.** Free to use, study, modify and share. If you