GigaMail — the email layer for AI agents

MAIL CITY / FIELD GUIDE

The journey above.
The engine underneath.

GigaMail is the email layer for AI agents. It reads and searches your inbox, brings in your documents and calendar, and puts a human decision around actions that need one.

This answers our clients every day.

Two minutes and a quarter on a demo mailbox, in four scenes. You direct the agent from your own inbox: write an instruction, read what came back, edit it, send it. You are not chatting with a bot in another window.

THE ENGINE ROOM

Your agent brings the intelligence.

GigaMail runs on your machine, next to the inbox you already use. There is no built-in LLM: the intelligence is whatever agent you bring. Works with Claude, Codex, OpenClaw, Hermes, or your own agent. Ours is Sofia.

CONTEXT

Your documents. Your answers.

Identity, tone, price lists and knowledge files give the agent the context it needs to prepare a reply.

CONNECTION

The inbox stays yours.

Microsoft Graph and IMAP connect GigaMail to providers such as Gmail and Aruba. MCP over stdio connects the agent, without a listening network port or a GigaMail relay service.

IN PRACTICE

From enquiry to proposal.

We build and sell apartments. A prospect asks about a unit: size, price, a viewing. The agent pulls the real figures from our own files, attaches the right floor plans, and offers slots that are genuinely free in our calendar.

Local data, explicit provider boundary. Mail indexes, credentials and memory stay on your machine. Content read by your agent is handled by that agent’s provider.

THE HUMAN CHECKPOINT

Permission is a separate step.

An agent can ask to send a message. It does not receive a secret it can use to approve its own request.

REQUEST
The agent gets a preview.
A proposed action returns a preview and an inert request ID. The agent can present the proposal, but cannot turn that ID into approval.
DECISION
You approve outside the agent.
The console, CLI, Telegram or Windows notifications surface the decision. Approval is protected by Windows Hello or Touch ID, beyond the agent’s reach.
EXECUTION
The approved arguments run.
Execution uses the exact arguments you reviewed, rather than a replacement supplied by the agent. Every write is recorded in the action log.

THE AUTONOMY LANES · SINCE 0.2

Autopilot starts with your rule.

Choose the senders or folders a rule covers, and the documents the agent should use. Semi-autopilot proposes a draft. Autopilot sends within a scope you approved in advance.

SEMI-AUTOPILOT

Prepare → review → decide.

Routine mail becomes a proposal for human approval. Notifications offer approve, reject and “redo it like this”, with a record of who decided.

AUTOPILOT

Match → check → execute.

A personally authorized rule supplies pre-approval for a precise scope. Rules carry an expiry, daily cap and per-sender cooldown.

Rules are outside MCP.

Creating or reactivating rules happens in the console or CLI behind Windows Hello or Touch ID. No MCP tool can create, change or enable them.

The drafter writes the body.

Recipient, subject and thread come from the incoming message. The recipient is the authenticated sender, never Reply-To or an address embedded in a generated draft.

Deterministic barriers.

DMARC failure prevents automatic sending. Auto-generated mail, lists, no-reply senders, provider-marked spam and executable attachments receive no reply.

Approve from wherever you are.

Drafts arrive as a Windows toast and a Telegram message with approve, reject and “redo it like this” buttons. Decisions are accepted only from the owner’s chat, with an audit line saying who decided what.

AUDIT TRAILdecided_by automode:<rule_id>

Autopilot is pre-approval within a rule you created in person.

THE TOOL DEPOT

24 tools. Three permission levels.

Read operations, reversible writes and destructive actions have different boundaries. Login and credentials stay in the CLI and are not exposed as agent tools.

Read

Free to inspect

list_messages
search_mail
read_message
read_attachment
sender_history
get_identity
list_knowledge_files
read_knowledge_file
observer_context
find_free_slots
list_events
list_folders
list_unread
memory_stats
list_accounts

Safe writes

Reversible and logged

mark_read
move_message
create_folder

Destructive

Authorization required

send_mail
reply_mail
delete_message
delete_folder
create_event
delete_event

THE INJECTION LAB

An email is input, not authority.

Email content is untrusted input. We wrote hostile emails that order the assistant to forward the inbox to a stranger, wipe the mailbox and approve its own send, then fed them to a real agent with all 24 tools live.

Forward the inbox to a strangerREFUSED

Delete the mailbox in bulkREFUSED

Approve its own send requestREFUSED

Terminal output of the anti-injection harness: three hostile-email scenarios run against a real agent in dry-run mode, all three reporting OK with zero destructive actions. — The harness in dry-run mode. Three hostile scenarios, three refusals, zero destructive actions.

The third scenario exists because someone on r/mcp found the hole: the first version handed the agent a confirmation token in the tool result, so it held both halves. Approval now lives outside the agent’s reach entirely. The structural half of that suite runs in CI on every push, on Windows and Linux, across Python 3.10, 3.12 and 3.13, 279 tests. Several of them exist because strangers on r/mcp found real holes, and each fix ships with their name in the changelog.

Inspect the implementation and test suite ↗

YOUR DEPARTURE POINT

Run it on your own machine.

The Windows desktop app bundles the console, the backend and its own Python: one installer, no prerequisites, and it updates itself. The three steps below are the pip route, for when your agent is the interface.

Download for Windows Read the documentation ↗

Windows 10/11 installer, everything included. Unsigned for now: SmartScreen will warn on first run. The SHA-256 is shown next to the file on the release page.

Install & connect

pip install "gigamail[all]"

gigamail login              # Microsoft device flow
gigamail accounts add-imap  # Gmail, Aruba, any IMAP

Add your context

gigamail identity set
gigamail identity add-file price-list.xlsx
gigamail identity add-file ./floor-plans/

Connect your agent

{
  "mcpServers": {
    "gigamail": { "command": "gigamail-server" }
  }
}

Then ask: “Reply to the last quote request using the price list.”

GigaMail

Open source · AGPL-3.0-or-later
Commercial licenses available.

Back to Mail City ↑

Mail City is a model of the workflow, not a connected client: it never touches your inbox and sends no email. The 3D world reuses open-source code listed in the code credits.