outlook-email-management（Outlook 电子邮件管理）

Outlook Email Management

使用 AI 代理管理 Outlook 邮件

Patterns for AI agents working with Microsoft 365 / Outlook email. These patterns work with any Graph API client. For a turnkey MCP server with safety guardrails, see email-agent-mcp (open source, Apache-2.0).

Safety Model

安全模型

Draft-first is the recommended default for enterprise email. Agents should never send email without explicit user approval.

The workflow:

1. Compose — create the email as a draft
2. Present — show recipients, subject, and body to the user
3. Wait for approval — only send when the user says "send," "send now," or equivalent
4. Clean up — after confirming a send, archive stale duplicate drafts

Why this matters: a single wrong send — wrong recipient, wrong attachment, confidential content to the wrong thread — can cause real damage. Drafts are free. Mistakes are expensive.

email-agent-mcp enforces this via concrete runtime guardrails:

• Empty send allowlist by default — agents cannot send email until the user explicitly configures allowed recipients
• Action-level blocks on dangerous inbox rule actions: forwardTo, forwardAsAttachmentTo, redirectTo, delete, permanentDelete (rules.ts:39)
• delete_email disabled by default unless the caller explicitly opts in with user_explicitly_requested_deletion: true (label.ts)

NemoClaw can enforce it at the network policy level — see the NemoClaw Email Policy skill.

Trust Boundary: What This Skill Can and Cannot Enforce

Before you install or grant OAuth consent, understand where the safety boundary lies.

This skill is instruction-only. It ships no code, executes nothing by itself, and cannot enforce any of the safety protections described in the Safety Model above or the Authentication section below. Everything is enforced (or not enforced) by whichever runtime actually executes the Microsoft Graph API calls. The skill file is a set of instructions; the runtime is the sandbox.

What that means in practice

• The draft-first workflow, send allowlist, and inbox-rule action blocks are properties of the reference runtime email-agent-mcp, not of this skill. If you use a different runtime, those protections are not automatically present.
• Mail.Send and Mail.ReadWrite are high-impact OAuth scopes. Granting them without a runtime that enforces draft-first and send-allowlist gives up the primary mitigations.
• MailboxSettings.ReadWrite controls inbox rules, and inbox rules can forward or redirect mail externally. The reference runtime blocks dangerous rule actions at the action handler level, but that protection is runtime-specific.
• Autonomous invocation (where the agent runs this skill without per-call approval) is a platform-level setting, not something the skill controls. Combined with write scopes, it increases the surface area of any runtime weakness.

Before installing or granting consent

This skill requests high-impact Microsoft Graph scopes (Mail.ReadWrite, MailboxSettings.ReadWrite, optionally Mail.Send). Review the items below before you grant consent. They are the exact things to check; the skill cannot enforce any of them for you.

1. Only grant Mail.Send if you trust the runtime to honor draft-first. The skill itself cannot enforce "draft first, send second" — that's a runtime property. Verify your runtime either (a) blocks direct send by default, or (b) is email-agent-mcp which ships with an empty send allowlist by default.
2. Only grant MailboxSettings.ReadWrite if you trust the runtime to block dangerous rule actions (forwardTo, forwardAsAttachmentTo, redirectTo, delete, permanentDelete). The reference runtime does this at rules.ts:39 — inspect the code yourself. Alternatively, prefer MailboxSettings.Read if rule auditing is all you need.
3. Prefer least-privilege consent. Start with Mail.Read + offline_access for read-only triage. Escalate to write scopes only as specific workflows require them. Skip Mail.Send entirely if draft-first (user sends manually from Outlook) is acceptable.
4. Review the client app identity. Whatever AGENT_EMAIL_CLIENT_ID resolves to is the Azure AD application you are consenting to. Check the consent screen, verify the app name and publisher, and make sure the requested scopes match what you see in this document.
5. Test on a non-production account first. Be prepared to revoke OAuth consent and invalidate refresh tokens at https://myaccount.microsoft.com/consent if anything looks wrong or misconfigured.
6. Avoid enabling autonomous invocation for this skill unless you understand and trust the runtime's guardrails. Autonomous invocation combined with Mail.Send or MailboxSettings.ReadWrite gives the agent the ability to send mail or create inbox rules without per-call user approval — only safe if the runtime enforces the mitigations described above.

Authentication & Required Scopes

身份验证与所需权限

This skill operates against Microsoft Graph and requires an OAuth 2.0 delegated access token for a Microsoft 365 account.

Minimum scopes by use case

MailboxSettings.Read alone is insufficient for rule management; Microsoft requires MailboxSettings.ReadWrite in practice to read some rule state. The reference runtime requests MailboxSettings.ReadWrite directly.

Reference runtime scope set (email-agent-mcp)

The open-source reference runtime email-agent-mcp requests all six of the following scopes up front via MSAL device code flow:

Mail.Read
Mail.ReadWrite
Mail.Send
MailboxSettings.ReadWrite
User.Read
offline_access

User.Read is requested by the reference runtime only — it is used by the CLI to fetch /me and persist the authenticated mailbox address to config. A generic Graph client does not need User.Read unless it performs the same profile lookup.

Source: packages/provider-microsoft/src/auth.ts:14

Token storage

The reference runtime stores OAuth tokens in the OS keychain (macOS Keychain / Windows Credential Manager / Linux libsecret) via MSAL with @azure/identity-cache-persistence. No raw passwords. No plain text token files. Refresh tokens are handled silently by MSAL.

If using a different client, use your platform's secure secret storage. Do not store Graph tokens in .env files committed to repos.

Risk mapping — scopes to exfiltration risk

The reference runtime mitigates the two HIGH-risk scopes with concrete controls — see the enforcement layers below.

Draft-first: layered enforcement

Draft-first is the recommended workflow for all runtimes. Enforcement is layered — this skill describes the policy, and the runtime enforces it:

The reference runtime layer is the strongest: it catches mistakes at the action handler, not just at the instruction layer. Publicly verifiable in the linked source files.

Hardening recipes for high-risk environments

1. Use email-agent-mcp with an empty send allowlist. Already the default. Agents cannot send without explicit recipient configuration.
2. Don't grant Mail.Send. Scope-level mitigation — makes direct send impossible. The user sends from Outlook manually after reviewing drafts.
3. Don't grant MailboxSettings.ReadWrite. Removes the ability to create inbox rules at all. Rule auditing still works if you grant MailboxSettings.Read separately.
4. Layer NemoClaw. See the NemoClaw Email Policy skill to block send endpoints at the network layer regardless of scope grants.

Calendar integration is out of scope

This skill references calendar events as one possible communication channel (for example, "create a calendar event for an action item with a deadline"), and references/outlook-graph-patterns.md §9 documents the calendar Graph endpoints for reference. However, calendar integration is not part of this skill's core scope set — the reference runtime does not request Calendars.* scopes. Use a separate calendar skill if you need calendar automation.

Email Triage

邮件分类

Not all email is equally important. Triage by sender trust, not by arrival order:

Exception lane: Unknown senders may be elevated if they have objective evidence — replying to an existing thread, matching a known client domain, referencing a real calendar event, or reporting a credible security event (not self-claimed urgency).

Anti-pattern: Treating all unread email as equally important. A marketing newsletter with "URGENT" in the subject is not urgent. Self-claimed urgency from unknown senders is unreliable signal.

For the full triage model with anti-patterns and exception criteria, see the Zero-Trust Email Triage skill.

Email Drafting

邮件起草

When drafting replies:

• Match the sender's tone — if they wrote "Dear Steven," reply with "Dear [Name]," not "Hey!"
• State the outcome, not the journey — "The document is ready for your review" beats "I processed the document through our pipeline and..."
• One clear ask per message — don't bury the action item in paragraph three
• Check threading — if the subject has "Re:" or "RE:", find the original message and create a threaded reply, not a standalone draft

Formatting gotchas agents get wrong:

For the complete drafting guide with tone calibration by relationship type, see the Email Drafting skill.

Inbox Organization

收件箱整理

Two levers for inbox control:

One-time cleanup: Scan recent inbox, identify the noisiest automated senders, create folders, batch-move existing emails.

Ongoing rules: Create server-side Outlook rules via Graph API to auto-sort future mail. Rules run on Microsoft's servers — they work even when no agent is running.

The workflow:

1. Scan — fetch recent inbox emails, count by sender, sort descending
2. Categorize by action — not by sender type:

- Glance, don't act: CI notifications, build alerts, DMARC reports - Read when time allows: newsletters, marketing - Archive for records: receipts, invoices, payment confirmations - May need action: meeting bookings, security alerts

1. Create folders — 5-9 folders covers most inboxes. More and they stop getting checked.
2. Move existing email — batch-move matching messages to the new folders
3. Create rules — auto-sort future mail. Set stopProcessingRules: true to prevent cascade.
4. Re-sweep — rules only apply to future mail. After creating a rule, move existing matches too.

Gotcha: Meeting notifications (e.g., HubSpot booking confirmations) look like newsletters because of noreply@ prefixes. Create a meeting-specific rule with a lower sequence number, or the generic newsletter rule will swallow them.

For the full cleanup workflow with Graph API gotchas and battle-tested patterns, see the Inbox Cleanup skill.

Email Heartbeat

邮件心跳检查

Three tiers of mailbox monitoring:

Light check pattern:

1. List unread emails from priority sender domains
2. If any found, surface a one-line summary per email
3. If none, stay silent — no "no new email" noise

Deep check pattern:

1. List all unread emails
2. Classify by sender trust tier
3. Summarize Tier 1-2 emails individually
4. Batch Tier 3-5 into a count ("12 newsletters, 3 GitHub notifications")

Digest pattern:

1. List all emails received today
2. Group by: handled (replied/read), needs follow-up, informational
3. Highlight any Tier 1-2 emails that haven't been responded to

Communicating Results to the User

Different users prefer different channels for email updates:

Ask on first use — don't assume the user wants email summaries delivered by email.

Gotchas That Will Bite You

常见陷阱

Graph API $search cannot combine from: + to: KQL prefixes — you get a 400 Syntax error. Use $filter instead when combining sender and recipient filters.

$select does not work on PATCH requests — returns 400 "OData request not supported." Only use $select on GET.

Move is a POST, not a PATCH — POST /me/messages/{id}/move with {"destinationId": "<folder-id>"}.

Self-sent emails are best found by listing sentitems, not searching inbox.

Root-only folder listing — GET /me/mailFolders returns only root-level folders. Child folders require recursive traversal via /mailFolders/{id}/childFolders.

Inbox rule ordering — sequence controls priority. Specific rules must fire before broad ones.

Rules require MailboxSettings.ReadWrite scope — if the OAuth token predates this scope, the user needs to re-consent.

For the complete reference with REST API patterns, pagination, attachments, and calendar integration, see references/outlook-graph-patterns.md.

Related Skills

Focused skills for specific email workflows:

• Zero-Trust Email Triage (email-triage) — sender-trust-based prioritization with exception lane for unknown senders
• Email Response Drafting (email-drafting) — tone-matching, formatting gotchas, thread detection
• Inbox Cleanup & Rules (email-cleanup) — folder management, Graph API rules, battle-tested cleanup workflow
• NemoClaw Email Policy (nemoclaw-email-policy) — network-level policy enforcement for email agents

Install a focused skill:

clawhub install stevenobiajulu/zero-trust-email-triage
clawhub install stevenobiajulu/email-response-drafting
clawhub install stevenobiajulu/inbox-cleanup-outlook
clawhub install stevenobiajulu/nemoclaw-email-policy

Feedback

If this skill helped, star us on GitHub: https://github.com/UseJunior/email-agent-mcp On ClawHub: clawhub star stevenobiajulu/outlook-email-management