Outlook

This skill provides Outlook-specific operations beyond the shared messaging skill. For cross-platform messaging (send, read, search, reply), use the messaging skill. Outlook operations depend on the messaging skill's provider infrastructure - load messaging first if Outlook is not yet connected.

Script Reference

All operations use CLI scripts that return JSON:

• Success: { "ok": true, "data": ... }
• Failure: { "ok": false, "error": "..." }

Email Operations

# Draft an email (--to is optional; omit it to create a draft with no recipient)
bun run scripts/outlook-email.ts draft --to "user@example.com" --subject "Hello" --body "Message body"
bun run scripts/outlook-email.ts draft --subject "Hello" --body "Message body"

# Send an existing draft (REQUIRES user confirmation before execution)
bun run scripts/outlook-email.ts send-draft --draft-id "AAMk..."

# Forward a message
bun run scripts/outlook-email.ts forward --message-id "AAMk..." --to "recipient@example.com" --comment "FYI"

# Trash a message
bun run scripts/outlook-email.ts trash --message-id "AAMk..."

Management Operations

# Categories - add categories to a message
bun run scripts/outlook-manage.ts categories --action add --message-id "AAMk..." --categories "Blue Category,Important"

# Follow-up - flag a message for follow-up
bun run scripts/outlook-manage.ts follow-up --action track --message-id "AAMk..."

# Attachments - list attachments on a message
bun run scripts/outlook-manage.ts attachments --action list --message-id "AAMk..."

# Rules - create a server-side inbox rule
bun run scripts/outlook-manage.ts rules --action create --name "Archive newsletters" --conditions '{"senderContains":["newsletter"]}' --actions '{"moveToFolder":"Archive"}'

# Vacation - enable auto-reply
bun run scripts/outlook-manage.ts vacation --action enable --internal-message "I'm out of office" --external-message "I'm currently away"

# Unsubscribe from a mailing list (REQUIRES user confirmation before execution)
bun run scripts/outlook-manage.ts unsubscribe --message-id "AAMk..."

Scan Operations

# Sender digest - scan inbox grouped by sender
bun run scripts/outlook-scan.ts sender-digest [--query "..."] [--time-range "90d"] [--account "..."]

# Outreach scan - identify cold outreach senders
bun run scripts/outlook-scan.ts outreach-scan [--time-range "90d"] [--account "..."]

Scan scripts store message IDs in the daemon's in-memory cache (via assistant cache) and return a lightweight summary with a cache_key. This keeps thousands of message IDs out of the conversation context. To retrieve cached message IDs for a specific sender:

assistant cache get <cache_key> --json
# Returns: { "ok": true, "data": { "sender@example.com": ["msgId1", "msgId2", ...], ... } }

Email Routing Priority

When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - always default to the user's own email (Outlook) unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Outlook, not the assistant's @vellum.me address.

Do not offer the assistant's own email as an option unless the user specifically asks. If Outlook is not connected, guide them through Outlook setup.

Connection Setup

Outlook

1. Check connection health first. Run assistant oauth ping outlook. This checks whether the user's Outlook/Microsoft account is connected and the token is valid.
2. If no connection is found or the ping fails: Load the vellum-oauth-integrations skill. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.

Error Recovery

When an Outlook script fails with a token or authorization error:

1. Try to reconnect silently. Run assistant oauth ping outlook. This often resolves expired tokens automatically.
2. If reconnection fails, go straight to setup. Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Outlook needs to be reconnected - let me set that up") and immediately load the vellum-oauth-integrations skill. The user came to you to get something done, not to troubleshoot - make it seamless.
3. Never try alternative approaches. Don't use curl, browser automation, or any workaround. If the scripts can't do it, the reconnection flow is the answer.
4. Never expose error details. The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.

Safety: Send-Draft and Unsubscribe

Two operations are high-risk and require explicit user confirmation before execution:

• send-draft: Always show the user what will be sent (recipients, subject, body summary) and wait for explicit confirmation ("yes", "send it", etc.) before running the send-draft script. Never auto-send.
• unsubscribe: Always tell the user which mailing list will be unsubscribed from and wait for explicit confirmation before running the unsubscribe script. Unsubscribe actions cannot be undone.

If the user has not explicitly confirmed, do not execute these operations. A general instruction like "clean up my inbox" is not confirmation to unsubscribe - it means scan and present options.

Drafting vs Sending (Outlook)

Outlook uses a draft-first workflow, matching Gmail. Compose and reply land in the user's Outlook Drafts folder. Nothing is sent until they confirm.

• Prefer messaging_send with platform: "outlook". That creates a real Outlook draft (not a local file). Recipients are optional: if the user has not named a To address, pass a non-email conversation_id (for example drafts) and still create the draft.
• bun run scripts/outlook-email.ts draft does the same via Graph. --to is optional.
• Do not inspect this skill's scripts before creating a draft. Call messaging_send or run the draft command immediately.
• Do not tell the user a draft exists until the tool or script returns success with a draftId. If creation fails or is interrupted, say so and offer the email copy in chat (clipboard or an in-app notification if they ask).
• The forward operation creates a forward draft, preserving attachments.

To actually send: use bun run scripts/outlook-email.ts send-draft with the draft ID after the user has reviewed it. Only run send-draft when the user explicitly says "send it" or equivalent.

Differences from Gmail

Outlook and Gmail have different organizational models. Keep these distinctions in mind:

Categories

Categories are Outlook's tagging system for organizing messages. Unlike Gmail labels, categories are independent of folder structure - a message can be in any folder and have multiple categories. Categories are color-coded (Blue, Green, Orange, Purple, Red, Yellow, or custom names). Use categories to tag and organize messages without moving them between folders.

Follow-up Flags

Outlook uses a native flag system for follow-up tracking:

• flagged - message is marked for follow-up
• complete - follow-up is done
• notFlagged - no follow-up tracking

This replaces Gmail's label-based follow-up approach. Use the Outlook flag system directly rather than creating custom folder-based workarounds.

Inbox Rules vs Gmail Filters

Outlook inbox rules run server-side and support conditions like sender, subject, body keywords, and importance level. Actions include moving to folders, categorizing, flagging, forwarding, and deleting. When a user asks to "filter" or "auto-sort" email, use the rules operation - do not try to replicate Gmail's label-based filtering with Outlook folders.