/outlook

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.

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 `<SKILL_DIR>/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: <url>` under the provider in config.yaml 4. Run `sig login ms-graph` (with `--network-proxy <url>` if proxy was specified) 5. Verify: run `sig status ms-graph` again — must show `valid: true` before proceeding

Proxy Detection (after provider is valid)

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=<url> HTTP_PROXY=<url>`. 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, b