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#

Use caseScopes requiredRead-only triage and summarizationMail.Read, offline_accessCreate drafts and move email+ Mail.ReadWriteCreate and delete inbox rules+ MailboxSettings.ReadWriteSend email directly (not draft-first)+ Mail.Send — sensitive, see below

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:

text

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#

ScopeEnablesRisk if misusedMail.ReadRead any message, attachment, and headerRead-only; no exfiltration beyond what the agent session can already seeMail.ReadWriteCreate drafts, move/copy messages, mark readLow on its own; combined with Mail.Send enables outboundMailboxSettings.ReadWriteCreate and delete inbox rulesHIGH — malicious rules with forwardTo/ redirectTo can exfiltrate mail silently even after the session endsMail.SendSend email from the user's accountHIGH — unauthorized outbound mail, impersonation riskUser.ReadRead user profile basics (email, display name)Low; metadata onlyoffline_accessRefresh tokens without re-authLow on its own; extends the blast radius of any other scope if the token is stolen

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:

LayerEnforcement mechanism**Reference runtime (email-agent-mcp)**Send allowlist empty by default. Action-level blocks on forwardTo, forwardAsAttachmentTo, redirectTo, delete, permanentDelete in rules.ts:39. delete_email disabled by default in label.ts.Network policy (NemoClaw)Can block graph.microsoft.com/v1.0/me/sendMail at the network layer via custom policy, eliminating send capability entirelyRaw Graph API clientInstruction-level only. Relies on the agent honoring the draft-first instructions. Not recommended for safety-critical use — pair with one of the runtime layers above

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:

PriorityWhoAction1 - ImmediatePaying customers, active clientsSurface and summarize right away2 - PromptEngaged contacts, active threadsSurface promptly3 - ColleaguesInternal team, contractorsSurface promptly4 - BatchNewsletters, automated notificationsBatch for later review5 - DeprioritizeUnknown sendersDefault low priority

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:

IssueFixCuddled lists (no blank line before - item)Always add a blank line before the first list itemMarkdown in HTML emailConvert markdown to HTML before sending; raw **bold** renders as literal asterisksMissing plain-text bodyAlways include both HTML and plain-text versionsSignature placementPut the signature after the reply body, before the quoted thread

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

3. Create folders — 5-9 folders covers most inboxes. More and they stop getting checked.

4. Move existing email — batch-move matching messages to the new folders

5. Create rules — auto-sort future mail. Set stopProcessingRules: true to prevent cascade.

6. 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:

TierFrequencyWhat to checkLightEvery 15-30 minUnread count from priority senders onlyDeepEvery 2-4 hoursFull triage pass — new unread from all senders, summarize by priority tierDigestDailyEnd-of-day summary — what came in, what was handled, what needs follow-up

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:

ChannelWhen to useChat interfaceDefault. Summarize inline in the conversation.Text messageIf the user prefers distilled updates via messaging. Provide copy-paste text with phone number if no SMS tool is available.Calendar eventFor action items with deadlines — create an event instead of a reminder email.Summary emailOnly if explicitly requested. Be aware this adds to inbox clutter.

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:

text

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