--- name: outlook description: 'Interact with Outlook email — read inbox, send emails, search messages, reply/forward, manage folders, download attachments. Use this skill whenever the user mentions email, Outlook, inbox, mail, send email, check email, unread messages, email search, attachments, reply to email, forward email, 邮件, 收件箱, or wants to read, send, search, reply to, forward, or manage emails.' --- # Outlook Email Read, search, and manage emails via Microsoft Graph API. ## Sending Emails — Draft Mode The Graph API token lacks `Mail.Send` scope (your organization's Azure AD policy), so sending is done via **draft creation**: - `outlook_send.py` creates a draft in Drafts folder — user clicks Send in Outlook - `outlook_reply.py` creates a reply/forward draft — user clicks Send in Outlook - The draft's `webLink` opens directly in Outlook Web for quick sending ## Setup (run FIRST — every time, before any operation) You MUST complete this setup before running any script. Do NOT skip this step. ```bash sig status ms-graph 2>&1 ``` Check the JSON output fields `configured` and `valid`: - **`configured: false`** → run Provider Setup below. Do NOT proceed without completing it. - **`valid: false` (but configured: true)** → run `sig login ms-graph`, then re-check. - **`valid: true`** → detect proxy (see below), then execute the user's request. ### Provider Setup 1. Read `/references/provider-config.yaml` 2. Append the provider block to `~/.sig/config.yaml` under `providers:` 3. Ask the user: "Do you need a proxy to access this site?" — if yes, add `networkProxy: ` under the provider in config.yaml 4. Run `sig login ms-graph` (with `--network-proxy ` if proxy was specified) 5. Verify: run `sig status ms-graph` again — must show `valid: true` before proceeding ### Proxy Detection (after provider is valid) ```bash grep -A15 "^\s*ms-graph:" ~/.sig/config.yaml | grep networkProxy | awk '{print $2}' ``` If this outputs a URL, prefix ALL python3 commands with `HTTPS_PROXY= HTTP_PROXY=`. If using socks5, convert to socks5h for python (e.g. `socks5://...` → `socks5h://...`). If empty, no proxy needed. ## Running Scripts All scripts require setup to be completed first (see above). ## Scripts Reference All scripts are in this skill's `scripts/` directory. Run via Bash tool. | Script | Purpose | Token | | ------------------------ | ------------------------------------ | ----- | | `outlook_folders.py` | List mail folders | Graph | | `outlook_messages.py` | List messages from a folder | Graph | | `outlook_read.py` | Read full message by ID | Graph | | `outlook_search.py` | Search emails with KQL | Graph | | `outlook_send.py` | Send a new email | Graph | | `outlook_reply.py` | Reply/ReplyAll/Forward | Graph | | `outlook_manage.py` | Mark read/unread, move, delete, flag | Graph | | `outlook_attachments.py` | List/download attachments | Graph | ### outlook_folders.py ``` --graph-token TOKEN Graph API Bearer token (required) --include-children Also list child folders (flag) ``` ### outlook_messages.py ``` --graph-token TOKEN Graph API Bearer token (required) --folder FOLDER Folder name or ID (default: Inbox) --limit N Max messages (default: 20, max: 50) --since ISO_DATE Only messages after this date --until ISO_DATE Only messages before this date --unread-only Only show unread messages (flag) ``` Well-known folder names: `Inbox`, `SentItems`, `Drafts`, `DeletedItems`, `Archive`, `JunkEmail`. ### outlook_read.py ``` --graph-token TOKEN Graph API Bearer token (required) --message-id ID Message ID (required) --format FORMAT "text" (default) or "html" ``` ### outlook_search.py ``` --graph-token TOKEN Graph API Bearer token (required) --query TEXT KQL search query (required) --folder FOLDER Restrict to folder (optional) --limit N Max results (default: 20, max: 50) ``` ### outlook_send.py ``` --graph-token TOKEN Graph API Bearer token (required) --to ADDRESSES Comma-separated recipient emails (required) --subject TEXT Email subject (required) --body TEXT Email body content (required) --cc ADDRESSES Comma-separated CC addresses --bcc ADDRESSES Comma-separated BCC addresses --body-type TYPE "text" (default) or "html" --importance LEVEL "low", "normal" (default), or "high" --no-save-to-sent Do not save to Sent Items ``` ### outlook_reply.py ``` --graph-token TOKEN Graph API Bearer token (required) --message-id ID Original message ID (required) --action ACTION "reply", "replyAll", or "forward" --body TEXT Reply/forward body content (required) --to ADDRESSES Recipient addresses (required for forward) ``` ### outlook_manage.py ``` --graph-token TOKEN Graph API Bearer token (required) --message-id ID Message ID (required) --action ACTION "read", "unread", "move", "delete", "flag", "unflag" --folder FOLDER Destination folder (required for move) ``` ### outlook_attachments.py ``` --graph-token TOKEN Graph API Bearer token (required) --message-id ID Message ID (required) --download ATTACHMENT_ID Download a specific attachment (optional) --output-dir DIR Directory for downloaded file (default: /tmp) ``` ## Safety **Always show the user the draft (recipients, subject, body preview) and get explicit confirmation before calling `outlook_send.py`, `outlook_reply.py`, or `outlook_manage.py --action delete`.** ## KQL Search Syntax Use KQL (Keyword Query Language) with `outlook_search.py`: ``` "quarterly report" # Subject, body, or attachment name from:jane.doe@example.com # From a specific sender to:john@example.com # Sent to someone subject:"weekly standup" # In subject line hasattachment:true # Has attachments received>=2026-04-01 # Received after date from:jane subject:report # Combined filters ``` Note: `$orderby` is not supported with `$search` — results are returned by relevance. ## Key Concepts **Folder names** — Use well-known names (`Inbox`, `SentItems`, `Drafts`, `DeletedItems`, `Archive`, `JunkEmail`) or folder IDs from `outlook_folders.py`. **Message IDs** — Long opaque strings (e.g., `AAMkAD...`). Get from `outlook_messages.py` or `outlook_search.py`, then use with `outlook_read.py`, `outlook_reply.py`, `outlook_manage.py`, `outlook_attachments.py`. **Conversation threading** — Each message has a `conversationId`. To see a full email thread: read one message, note its `conversationId`, then search/filter for other messages in that conversation. **HTML bodies** — `outlook_read.py` converts HTML to plain text by default. Use `--format html` to get the raw HTML. **Time parameters** — Accept both `YYYY-MM-DD` and full ISO 8601 (`2026-04-13T09:00:00Z`). ## Error Handling | Error | Cause | Fix | | --------------------- | -------------------------- | --------------------------------------------------- | | 401 Unauthorized | Token expired | Auto-run `sig login` (no user prompt needed), retry | | 403 Forbidden | Insufficient permissions | Check Graph API permissions (Mail.Read, Mail.Send) | | 404 Not found | Invalid message/folder ID | Verify ID from a list or search | | 429 Too Many Requests | Rate limited | Wait and retry | | `MISSING_ARGS` | Required arguments missing | Check script `--help` | ## Workflow Examples ### Check inbox (recent unread emails) 1. `sig run ms-graph -- bash -c 'python3 scripts/outlook_messages.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --unread-only --limit 10'` ### Read a specific email 1. List messages to find the ID: `sig run ms-graph -- bash -c 'python3 scripts/outlook_messages.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --limit 5'` 2. Read full content: `sig run ms-graph -- bash -c 'python3 scripts/outlook_read.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --message-id "$MSG_ID"'` ### Search for emails 1. `sig run ms-graph -- bash -c 'python3 scripts/outlook_search.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --query "from:jane.doe@example.com subject:report"'` ### Send an email 1. **Show draft to user and get confirmation** 2. `sig run ms-graph -- bash -c 'python3 scripts/outlook_send.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --to "jane.doe@example.com" --subject "Meeting follow-up" --body "Hi Jane, ..."'` ### Reply to an email 1. Read the email first: `sig run ms-graph -- bash -c 'python3 scripts/outlook_read.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --message-id "$MSG_ID"'` 2. **Show reply draft to user and get confirmation** 3. `sig run ms-graph -- bash -c 'python3 scripts/outlook_reply.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --message-id "$MSG_ID" --action reply --body "Thanks, sounds good!"'` ### Forward an email 1. **Show forward draft to user and get confirmation** 2. `sig run ms-graph -- bash -c 'python3 scripts/outlook_reply.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --message-id "$MSG_ID" --action forward --body "FYI" --to "colleague@example.com"'` ### Download an attachment 1. List attachments: `sig run ms-graph -- bash -c 'python3 scripts/outlook_attachments.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --message-id "$MSG_ID"'` 2. Download: `sig run ms-graph -- bash -c 'python3 scripts/outlook_attachments.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --message-id "$MSG_ID" --download "$ATTACHMENT_ID" --output-dir ~/Downloads'` ### Check mail folders 1. `sig run ms-graph -- bash -c 'python3 scripts/outlook_folders.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --include-children'`