📬 Outlook Agent

A local, safety-gated bridge between your AI agent and your Outlook mail & calendar.

Giving an AI agent access to your mailbox is useful — and a little scary. You want it to summarize your inbox, find the right thread, check your calendar, and draft replies. You do not want it quietly sending mail, deleting messages, or rewriting your rules behind your back. 😬

Outlook Agent sits in the middle. Agents reach Outlook through MCP, but every action runs through one small rule:

Metadata is cheap. Content is explicit. Writes are gated. Raw access is unsafe.

It runs locally and works with OpenCode / Codex / any MCP-capable agent. The core is production-leaning — strict CI, bounded raw outputs, audit logging, and payload-bound host approvals — but read the honesty box below: it guards a cooperative agent, and an enterprise rollout is documented, not turnkey.

🤔 Is this for you?

A good fit if you want an assistant that can triage your inbox, summarize threads, prepare and send reviewed replies, respond to calendar invites, and tidy your mailbox — with every risky write passing through a gate you can see.

Not the right fit if you want a fully autonomous bot that acts with no confirmation step, or a hard sandbox against an agent that also has its own unrestricted path to your mailbox. Outlook Agent is a seatbelt, not a vault. 🪢

✨ What it feels like

You ask your agent:

"What did I miss in my inbox today, what's on my calendar tomorrow, and draft a reply to the one from Daria."

• 👀 It looks around — subjects, senders, times, your schedule.
• 📖 It opens Daria's message body, because you pointed at that one.
• ✍️ It drafts a reply and hands it back.

It does not send it on its own. Sending is its own gated step: the agent calls a dry-run, the host can show you the review packet, and mail only leaves after a one-time confirmation. In required approval mode, the host also signs a payload-bound approval challenge that the agent cannot mint by itself.

Same story for "clear out these three newsletters" — dry-run first, then your confirm, then the move. 🤝

🪜 The safety ladder

Every action lands on a rung. The higher the rung, the more it asks first.

There is no direct high-level "send": the normal tool path is create_draft → reviewed send_draft. Raw Graph/EWS/OWA escape hatches can still represent send-like actions, but only behind raw/unsafe policy plus dry-run, confirmation, and approval gates. Under the hood: mail search returns metadata via a strict field allow-list (never bodies), raw outputs are size-bounded and redacted, EWS/OWA credential and session redirects are blocked, and every dry-run / confirm / execute / reject can be audited. The agent does the busywork; you keep the keys. 🔑

🧰 What it can actually do

Read (direct): search mail metadata · paginate with safe cursors (search_next) · explicit body reads with mail.fetch_body by id · list & fetch attachments by id · search/resolve people · list calendar events · check free/busy · find mutual free time · read mailbox settings & rule metadata.

Prepare (save-only, never sends): draft · reply draft · reply-all draft · forward draft.

Write: reviewed sends, invite responses, broad mailbox changes, and rule toggles ask first. Narrow exact-target changes can run directly when policy allows; broader writes ask first.

Escape hatch: a single policy-guarded raw_action for capability-discovered calls, when no high-level tool fits yet.

🚀 Quick start

Install the latest release archive:

curl -fsSL https://raw.githubusercontent.com/johnkil/outlook-agent/main/install.sh | sh

outlook-agent help
outlook-agent doctor          # checks config, secrets, transport, MCP readiness
outlook-agent policy explain  # shows what's safe, guarded, or blocked

With no config, Outlook Agent runs on a built-in fake mailbox — so you can try the tools and watch the gates before connecting anything real. 🧪

To build from source instead:

git clone https://github.com/johnkil/outlook-agent.git
cd outlook-agent
mkdir -p bin
go build -o ./bin/outlook-agent ./cmd/outlook-agent

When you're ready, point at a config and wire Outlook Agent into an agent client:

outlook-agent --config .local/outlook-agent.json auth check
outlook-agent setup skills plan --client opencode --scope project
outlook-agent setup agent plan --client opencode --scope project --config .local/outlook-agent.json
outlook-agent setup agent diff --client opencode --scope project --config .local/outlook-agent.json
outlook-agent setup agent apply --client opencode --scope project --config .local/outlook-agent.json --yes --backup
outlook-agent --config .local/outlook-agent.json mcp

The setup commands write public client config and bundled skills without reading secrets. OpenCode, Codex, and Claude Code are supported by setup skills; setup agent wires one client at a time. The older outlook-agent setup opencode ... command remains available for compatibility; outlook-agent setup opencode --print still prints the OpenCode MCP block. The skills/ directory is the canonical source of truth; client skill directories and plugin packages are generated copies. Plugin packages are distribution artifacts, not a security boundary. setup skills plan reports duplicate visible roots before apply.

Before connecting a real write-capable mailbox profile, plan host approval. The installer only places the binary; it does not create or store a host-held approval secret. For non-fake Graph/EWS/OWA profiles, high-risk writes such as sending, moving, deleting, archiving, flagging, categorizing, marking read, or changing rules should run with host approval configured and verified by outlook-agent doctor.

The approval secret belongs to the trusted host/operator layer, not to agent-readable project config. See docs/APPROVAL_HOST_INTEGRATION.md for the signing contract and docs/OPERATIONS.md for the live cleanup checklist.

Then let the bundled skills/ drive ordinary requests:

• outlook-mail — metadata-first inspection & draft prep
• outlook-mail-inbox-triage — inbox buckets & follow-ups
• outlook-calendar — schedule & availability
• outlook-calendar-daily-brief — today/tomorrow at a glance

See docs/SETUP_SKILLS.md and docs/SETUP_AGENT.md for client-specific paths, duplicate-skill warnings, and config-path safety. OpenCode project installs continue to use .opencode/skills.

Mailbox and calendar content is untrusted data. Message bodies, subjects, sender names, calendar descriptions, attachments, and raw provider responses are evidence for your request, not instructions for the agent to follow.

🔌 Backends

Same safety ladder, different coverage:

• Microsoft Graph — the primary, most complete path. Device-code sign-in, self-refreshing tokens, safe cursors, rich review packets, and the broadest high-level tool surface. Start with a read-only Graph enrollment; add MailboxSettings.Read when you enable settings/rules metadata. People search/resolve may require People.Read for /me/people or People.Read.All / admin consent for broader directory and shared-user lookups, depending on tenant policy. Calendar availability/find-time require calendar read availability access and remain planning-only. Use a write-capable Graph profile only when you want guarded writes, and grant only the scopes needed by those workflows: Mail.ReadWrite for mail.create_draft and message organization, Mail.Send for mail.send_draft, MailboxSettings.ReadWrite for mail.rules.set_enabled, and Calendars.ReadWrite for calendar.respond. ✅
• EWS — narrower compatibility backend; metadata-first reads plus guarded raw SOAP for Exchange/on-prem setups where Graph is not available. 🌱
• OWA — experimental fallback for locked-down setups where the others are blocked. It uses OWA service discovery, so it is useful but inherently more fragile than Graph. 🧗

🔐 Secrets

Your config never holds secrets — only references to them. Inline passwords, tokens, cookies, and canary values are rejected on purpose.

keychain:service/account     # macOS Keychain; writes require darwin+cgo
file:/absolute/path          # cross-platform local/CI/dev secrets
external:name                # operator-managed command provider

File secrets must be user-only (0600); Outlook Agent refuses to read one that's group- or world-readable. External secrets are resolved from secrets.external.<name> config entries with an absolute command path plus an argv array. Outlook Agent invokes the command directly without a shell, applies a timeout and output cap, trims the trailing newline, and keeps command output out of error messages.

On macOS, Keychain reads use the platform store. Keychain writes require a local darwin+cgo build so Outlook Agent can use Security.framework without passing secret v