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:

1. Setup credentials (one-time): pnpm --prefix "${CLAUDEPLUGINROOT}" 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.*

1. Authenticate (per-project): pnpm --prefix "${CLAUDEPLUGINROOT}" 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

User Information

Email Operations

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": "[email protected]"}},
    "isRead": false,
    "hasAttachments": true
  }
]

me response:

{
  "id": "user-id",
  "displayName": "User Name",
  "mail": "[email protected]",
  "userPrincipalName": "[email protected]"
}

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:

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

Tokens auto-refresh when expired.

Troubleshooting

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

"No credentials found" error: Run setup: pnpm --prefix "${CLAUDEPLUGINROOT}" 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/.