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