Microsoft Graph API Integration

Access Microsoft 365 emails and calendar through TypeScript scripts executed via Bun.

Overview

This skill provides access to Microsoft Graph API for:

• Email: List, read, search, and send emails
• Calendar: View, search, and create calendar events

All scripts return JSON and handle authentication automatically.

Response Format

All scripts output JSON with a consistent structure:

Success

{"status": "success", "data": [...]}

Authentication Required

{
  "status": "auth_required",
  "userCode": "ABC123",
  "verificationUri": "https://microsoft.com/devicelogin",
  "expiresAt": "2024-01-15T10:30:00.000Z",
  "message": "To sign in, use a web browser..."
}

When you receive auth_required, display to the user:

To access your email, please authenticate:
1. Go to: https://microsoft.com/devicelogin
2. Enter code: ABC123

Let me know when you've completed authentication.

Then retry the same command - the script will automatically complete authentication.

Authentication Pending

{
  "status": "auth_pending",
  "userCode": "ABC123",
  "verificationUri": "https://microsoft.com/devicelogin",
  "expiresAt": "...",
  "message": "..."
}

User has been shown the code but hasn't completed login yet. Remind them to complete authentication.

Error

{"status": "error", "error": "Error description"}

Email Access

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

List Emails

bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/emails.ts list
bun run emails.ts list --folder "Sent Items" --top 5
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

bun run emails.ts search --query "from:boss@company.com"
bun run emails.ts search --query "subject:quarterly report"
bun run emails.ts search --query "hasAttachments:true"

List Mail Folders

bun run emails.ts folders

Send Email

# Simple email
bun run emails.ts send --to "user@example.com" --subject "Hello" --body "Hi there!"

# Multiple recipients with CC
bun run emails.ts send --to "a@example.com,b@example.com" --cc "c@example.com" --subject "Team Update" --body "Here's the update..."

# HTML email
bun run emails.ts send --to "user@example.com" --subject "Report" --body "<h1>Monthly Report</h1><p>Details...</p>" --html

# With BCC
bun run emails.ts send --to "team@example.com" --bcc "manager@example.com" --subject "Announcement" --body "..."

Calendar Access

List Upcoming Events

bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/calendar.ts list
bun run calendar.ts today
bun run calendar.ts week
bun run calendar.ts list --start tomorrow --end +7d

View Specific Event

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

Search Events

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

Date Formats

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

Create Calendar Event

# Basic event (1 hour default duration)
bun run calendar.ts create --subject "Team Meeting" --start "2024-01-15T14:00:00"

# Event with end time
bun run calendar.ts create --subject "Workshop" --start "2024-01-15T09:00:00" --end "2024-01-15T12:00:00"

# Event with location and description
bun run calendar.ts create --subject "Lunch" --start "2024-01-15T12:00:00" --location "Cafe" --body "Team lunch"

# Event with attendees
bun run calendar.ts create --subject "1:1" --start tomorrow --end +1d --attendees "colleague@example.com"

# Multiple attendees
bun run calendar.ts create --subject "Review" --start "2024-01-15T10:00:00" --attendees "a@ex.com,b@ex.com,c@ex.com"

# All-day event
bun run calendar.ts create --subject "Holiday" --start "2024-12-25" --all-day

# Using relative dates
bun run calendar.ts create --subject "Follow-up" --start tomorrow --end +1d

Multi-Profile Support

Store multiple accounts using profiles:

# Use work profile
bun run emails.ts list --profile work
bun run calendar.ts today --profile work

# Use personal profile
bun run emails.ts list --profile personal

Manual Authentication

For explicit auth management (listing/deleting profiles):

# List all profiles
bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/auth.ts --list

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

# Authenticate with custom Azure AD app
bun run auth.ts --client-id your-app-id --tenant-id your-tenant-id

Token Lifecycle

Token Type	Lifetime	Handling
Access Token	~1 hour	Automatically refreshed
Refresh Token	~90 days	When expired, scripts return auth_required

Users only need to re-authenticate when the refresh token expires (~90 days).

Credential Storage

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

Script Reference

Script	Purpose
emails.ts	Email list, read, search, send, and folder operations
calendar.ts	Calendar view, search, and create operations
auth.ts	Manual credential management (list, delete profiles)

Additional Resources

For detailed API reference, see:

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