outlook

Microsoft 365 Outlook mail and calendar through the Microsoft Graph API. Two scripts do the work: ${CLAUDE_SKILL_DIR}/scripts/outlook-mail.sh and ${CLAUDE_SKILL_DIR}/scripts/outlook-calendar.sh. The index below has every command. For the exact arguments and behaviour, read references/commands.md.

Rules

1. Draft, show, then send. Every mail command makes a draft; only send sends. Show the user the draft (From, To, Cc, Bcc, subject, body, attachments) and wait for an explicit "send it" before running send. The same goes for invitations: create an event with no attendees, show the user the event and the attendee list, and run invite only after they approve.

2. Replies go to everyone. reply, mdreply and followup are reply-all: every original To and Cc recipient is on the draft. Read the original's full To and Cc before replying, and check the recipients the draft prints. People Cc assistants and colleagues; dropping them is a real harm. For a reply to the sender only, trim the draft with update to and update cc "".

3. Read the whole message. preview is a 200-character snippet, for finding a message only. Before you summarise, answer or act on an email, read it end to end, including the attachment list and any request in the body. In a long chain, find where the current message ends and the quoted chain begins.

4. Check the time. Run date (and date -u) before anything that involves today, deadlines or "yesterday"; a session can span days. Graph timestamps are UTC. Calendar times are wall-clock in OUTLOOK_TZ, which defaults to the system zone, and a server is often UTC when the user is not. If the calendar warns that it is using UTC and that is not the user's zone, set OUTLOOK_TZ (for example Europe/London) before quoting a time.

5. Refusals and permission prompts are the send gap working. Never work around one, for example by calling Graph with curl yourself or by rewording a command so it is not recognised.

• With OUTLOOK_READ_ONLY=1, every command that writes or sends refuses. Tell the user; do not unset it.
• send, invite, respond, cancel, create ... --send-invites and update ... --notify-attendees may raise a permission prompt. That prompt is the user's approval, so show them what will be sent first.
• create refuses attendees without --send-invites. update refuses to change a meeting you organise without --notify-attendees, and delete refuses one (use cancel).

6. Confirm the From address. To send as an alias, get the exact address from aliases, set it with update <draft-id> from <address> (or OUTLOOK_FROM_ADDRESS for every draft), and show the user the From line before sending.

7. Setup is the user's. If an account is not configured, or a refresh is refused because the sign-in has lapsed, ask the user to run ${CLAUDE_SKILL_DIR}/scripts/outlook-setup.sh (add --account <name> for another mailbox). Do not run it yourself: it opens a browser and waits for a person to paste back a URL.

Command index

Mail is outlook-mail.sh <verb>, calendar is outlook-calendar.sh <verb>. Add --account <name> before the verb for another mailbox. Listings print short IDs, which every command accepts. A message keeps its ID when it moves to another folder.

Read mail

• inbox, unread, focused, sent, drafts, flagged [count]: list, newest first
• folder <name> [count], from <address> [count], category <name> [count]: list by folder, sender or category
• search <text or KQL> [count|all]: search; KQL such as subject:x AND from:y works
• read <id>: the whole message. preview <id>: a snippet, for navigation only
• thread <id>: the conversation, oldest first. stats: inbox totals

Write mail (all make drafts)

• draft <to> <subject> <body>, mddraft <to> <subject> <markdown> [--cc x] [--bcc y]: a new draft; prefer mddraft
• reply <id> <body>, mdreply <id> <markdown>: reply-all draft; prefer mdreply
• forward <id> <to> [markdown comment], followup <sent-id> [markdown]: forward, or chase your own sent mail
• update <draft-id> <field> <value>: subject, body, mdbody (keeps the quoted chain), to, cc, bcc, importance, from
• aliases: the addresses this mailbox can send as
• attach <draft-id> <file> [--inline <cid>]: add a file, up to 150 MB
• signature <draft-id> <html-file>: add an HTML signature; its local images go inline
• send <draft-id>: sends; prints From, To, Cc, Bcc, subject and attachments first

Attachments

• attachments <id>: list. download <id> [attachment-id]: save to ./inbox/

Organise mail

• markread, markunread, flag, unflag, junk, notjunk, archive <id>
• delete <id>: to Deleted Items, where it can be restored
• move <id> <folder>, batch-move <folder> <ids...> (or IDs on stdin): move; Parent/Child targets one folder
• categories, categorize <id> "<a, b>" | --add <c> | --remove <c>: apply categories
• mkcategory <name> [colour], rccategory <name> <colour>, rmcategory <name>: the master list
• folders, subfolders [folder], mkdir <name> [parent], rename <old> <new>, rmdir <name> [--force]: folders
• export <folder> <dir> [--since YYYY-MM-DD] [--count N]: raw .eml for the outlook-to-md skill to archive

Calendar

• events [count], today, week, day <YYYY-MM-DD>, search <text> [days]: list, with short IDs
• read <event-id>, calendars, free <start> <end>: details, calendars, busy periods
• create <subject> <start> <end> [location], quick <subject> <start>: sends nothing
• invite <event-id> <emails> [optional]: sends invitations
• respond <event-id> accept|decline|tentative [message]: tells the organiser
• update <event-id> <field> <value> [--notify-attendees]: subject, location, start or end
• cancel <event-id> [message]: a meeting you organise; tells every attendee
• delete <event-id>: removes an event that notifies nobody

Accounts (outlook-token.sh)

• list, status, test, refresh, get: accounts, connection, a valid token

Times are YYYY-MM-DDTHH:MM. Markdown commands need pandoc. Throttling (HTTP 429) is retried by the scripts, so do not loop a command. batch-move prints FAILED <id> for each message it did not move; run it again with those IDs.