microsoft-graph-api

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