Microsoft Graph API Integration

Access Microsoft 365 emails and calendar through TypeScript scripts executed via Bun. The scripts handle OAuth authentication, token management, and API requests.

Overview

This skill provides guided access to Microsoft Graph API for:

• Email: List, read, and search emails across folders
• Calendar: View and search calendar events
• Authentication: Device code OAuth flow with multi-profile support

All scripts are located at ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/.

Authentication

Before accessing emails or calendar, authenticate using the device code flow:

bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/auth.ts

The script displays a URL and code. Open the URL in a browser, enter the code, and sign in with a Microsoft account. Credentials are stored in ~/.config/api-skills/credentials.json.

Multi-Profile Support

Store multiple accounts using profiles:

# Authenticate with work account
bun run auth.ts --profile work

# Authenticate with personal account
bun run auth.ts --profile personal

# List all profiles
bun run auth.ts --list

# Delete a profile
bun run auth.ts --delete --profile old-account

Credential Storage

Credentials are stored at ~/.config/api-skills/credentials.json:

{
  "microsoft-graph": {
    "default": {
      "accessToken": "...",
      "refreshToken": "...",
      "expiresAt": "2024-01-15T10:30:00.000Z",
      "account": "user@example.com",
      "scopes": ["Mail.Read", "Calendars.Read", "User.Read"]
    }
  }
}

Tokens are automatically refreshed when expired.

Email Access

Use emails.ts to interact with emails:

List Emails

# List inbox (default)
bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/emails.ts list

# List from specific folder
bun run emails.ts list --folder "Sent Items"
bun run emails.ts list --folder drafts --top 5

# Use different profile
bun run emails.ts list --profile work

Read Specific Email

bun run emails.ts read --id AAMkAG...

Get the ID from the list command output.

Search Emails

# Search by sender
bun run emails.ts search --query "from:boss@company.com"

# Search by subject
bun run emails.ts search --query "subject:quarterly report"

# Combined search
bun run emails.ts search --query "from:hr@company.com subject:benefits"

# Search with attachments
bun run emails.ts search --query "hasAttachments:true"

List Mail Folders

bun run emails.ts folders

Shows folder names, IDs, and message counts.

JSON Output

Add --format json for machine-readable output:

bun run emails.ts list --format json

Calendar Access

Use calendar.ts to view calendar events:

List Upcoming Events

# Default: next 30 days
bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/calendar.ts list

# Today's events
bun run calendar.ts today

# This week's events
bun run calendar.ts week

# Custom date range
bun run calendar.ts list --start tomorrow --end +7d
bun run calendar.ts list --start 2024-02-01 --end 2024-02-28

Date Formats

• Relative: today, tomorrow, +7d, +1m, +1y
• Absolute: ISO format 2024-01-15

View Specific Event

bun run calendar.ts view --id AAMkAG...

Shows full details including attendees and description.

Search Events

bun run calendar.ts search --query "team standup"
bun run calendar.ts search --query "1:1"

Common Workflows

Check for Important Emails

# Unread from specific sender
bun run emails.ts search --query "from:ceo@company.com isRead:false"

# Recent urgent emails
bun run emails.ts search --query "subject:urgent" --top 5

Review Today's Schedule

bun run calendar.ts today

Find Meeting Details

# Search for meeting
bun run calendar.ts search --query "project kickoff"

# Get full details with attendees
bun run calendar.ts view --id <event-id>

Check Multiple Accounts

# Personal inbox
bun run emails.ts list --profile personal

# Work calendar
bun run calendar.ts today --profile work

Error Handling

Authentication Errors

If token is expired or invalid:

Error: No valid token for profile "default". Run auth first:
bun run auth.ts --profile default

Re-run authentication to refresh credentials.

API Errors

Common Graph API errors:

• 401 Unauthorized: Token expired, re-authenticate
• 403 Forbidden: Missing required scopes, re-auth with correct scopes
• 404 Not Found: Invalid folder name or message ID

Scope Requirements

Different operations require different scopes:

• Email: Mail.Read or Mail.ReadBasic
• Calendar: Calendars.Read
• User info: User.Read

To request specific scopes:

bun run auth.ts --scopes Mail.Read,Calendars.Read

Script Reference

All scripts support --help for detailed usage:

Script	Purpose
auth.ts	OAuth authentication and credential management
emails.ts	Email list, read, search, and folder operations
calendar.ts	Calendar view and search operations

Additional Resources

For detailed API reference and advanced patterns, see:

• references/graph-api.md - Microsoft Graph API endpoints and parameters