Microsoft Outlook Email Skill

Access Outlook and Hotmail emails via the Microsoft Graph API. Supports reading messages, listing inbox contents, and downloading emails as .eml files.

Prerequisites

Before using email commands, ensure authentication is configured:

Setup credentials (one-time): pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts setup
- Note: For personal accounts, ensure the app is registered as Multitenant + Personal Accounts in the Azure Portal. See the README for detailed steps.
Authenticate (per-project): pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts auth
- Tip: Use auth --browser Safari on macOS if your default browser is causing issues.

Available Commands

All commands output JSON for easy parsing.

Authentication & Setup

Command	Description
`setup`	Configure Microsoft API credentials (interactive)
`auth`	Run OAuth flow - opens browser for login
`auth --global`	Store token globally instead of per-project
`check`	Verify authentication status

User Information

Command	Description
`me`	Get authenticated user profile

Email Operations

Command	Description
`messages`	List recent messages (default: 10)
`messages --limit N`	List N recent messages
`download <id>`	Download specific message as `.eml` file
`download-all`	Download recent messages to `./downloads`
`download-all --limit N`	Download N recent messages

Usage Pattern

Execute commands via:

pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts <command> [options]

Example Workflows

Check inbox:

pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts messages --limit 5

Download specific email:

pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts download <message-id>

Get user profile:

pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts me

Output Format

All commands return JSON:

messages response:

[
  {
    "id": "AAMk...",
    "subject": "Meeting Tomorrow",
    "receivedDateTime": "2024-01-15T10:30:00Z",
    "from": {"emailAddress": {"name": "John", "address": "john@example.com"}},
    "isRead": false,
    "hasAttachments": true
  }
]

me response:

{
  "id": "user-id",
  "displayName": "User Name",
  "mail": "user@outlook.com",
  "userPrincipalName": "user@outlook.com"
}

Token Storage

Project tokens: .claude/microsoft-skill.local.json (default)
Global tokens: ~/.config/microsoft-skill/tokens.json (with --global)

Project tokens allow different Microsoft accounts per project.

Authentication Flow

The skill uses OAuth 2.0 with PKCE:

Run auth command
Browser opens to Microsoft login
Grant permissions (Mail.Read, User.Read)
Callback received on localhost:3000
Token stored for future use

Tokens auto-refresh when expired.

Troubleshooting

"Token not found" error: Run authentication: pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts auth

"No credentials found" error: Run setup: pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts setup

Token expired: The skill auto-refreshes tokens. If issues persist, re-run auth.

Additional Resources

Reference Files

references/setup-guide.md - Detailed Microsoft Entra app registration guide
references/api-reference.md - Microsoft Graph API endpoints and types

Scripts

The main CLI script is at scripts/microsoft.ts with supporting libraries in scripts/lib/.

microsoft-outlook