Agent skill

microsoft-graph-api

This skill should be used when the user asks to "read my emails", "send an email", "compose email", "check my calendar", "get calendar events", "create a meeting", "schedule an event", "add calendar event", "search emails", "list mail folders", "show unread messages", "what meetings do I have", "fetch emails from Microsoft", "access Outlook", or mentions Microsoft Graph, Office 365 email, or Outlook calendar integration.

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/bltgv/microsoft-graph-api

SKILL.md

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

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

Authentication Required

json
{
  "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

json
{
  "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

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

Email Access

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

List Emails

bash
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

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

Get the ID from the list command output.

Search Emails

bash
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

bash
bun run emails.ts folders

Send Email

bash
# 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

bash
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

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

Search Events

bash
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

bash
# 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:

bash
# 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):

bash
# 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

Didn't find tool you were looking for?

Be as detailed as possible for better results