---
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 `<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)

```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=<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, 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'`
