Office 365 Connector (Multi-Account Enhanced)

Overview

This skill provides resilient, production-ready connection to Office 365 / Outlook services including email, calendar, and contacts. Now with multi-account support (v2.0.0), you can manage multiple Microsoft 365 identities (work, personal, consulting, etc.) from a single skill installation.

It solves the common challenge of connecting to Office 365 from automation tools by providing OAuth authentication, automatic token refresh, per-account isolation, and comprehensive Azure App Registration setup guidance.

Perfect for:

Managing multiple work identities across organizations
Separating personal and professional email/calendar
Accessing shared mailboxes and delegated calendars
Consultants and freelancers working across multiple clients

New in v2.0.0: Multi-account support! See MULTI-ACCOUNT.md for complete usage guide.

Attribution: Enhanced by Matthew Gordon (matt@workandthrive.ai) - See CREDITS.md for full attribution.

What's New in v2.0.0

Major Enhancements by Matthew Gordon:

✨ Multi-Account Management - Handle multiple Microsoft 365 identities from one skill
🔐 Per-Account Token Isolation - Separate, secure token storage for each account
🔄 Easy Account Switching - Use
```
--account=name
```
flag across all operations
⚙️ Default Account Selection - Set your preferred account for convenience
📦 Legacy Import Tool - Migrate existing single-account setups seamlessly
🎯 Account Management CLI - Simple add/remove/list/default commands
✅ Full Backward Compatibility - Existing single-account setups work unchanged

See CHANGELOG.md for complete version history.

Capabilities

Email Operations

Read emails (inbox, sent items, folders)
Send emails (with attachments, HTML formatting)
Search emails by sender, subject, date range
Manage folders and move messages
Mark as read/unread, flag messages
Delete messages

Calendar Operations

Read calendar events
Create/update/delete events
Check availability
Manage meeting invitations
Support for recurring events
Time zone handling

Contact Operations

Read contacts and contact folders
Create/update/delete contacts
Search contacts by name, email, company
Manage contact groups
Sync contact information

Quick Start - Multi-Account

Add Your First Account

cd skills/office365-connector
Add account
node accounts.js add work <tenant-id> <client-id> <client-secret> you@work.com "Work account"
Authenticate
node auth.js login --account=work

Add More Accounts

# Add personal account
node accounts.js add personal <tenant> <client> <secret> you@outlook.com "Personal"
Add consulting account
node accounts.js add consulting <tenant> <client> <secret> you@client.com "Consulting"
Set default
node accounts.js default work
List all accounts
node accounts.js list

Use Your Accounts

# Check work calendar
node calendar.js today --account=work
Read personal emails
node email.js recent 10 --account=personal
Send from consulting account

node send-email.js send client@example.com "Subject" "Body" --account=consulting

Migrate from Single-Account Setup

Already using v1.0.0? No problem!

# Import your existing setup
node accounts.js import-legacy
Continue using without changes (environment variables still work)
OR add additional accounts
node accounts.js add secondary <tenant> <client> <secret>

Prerequisites

Before using this skill, you must complete the Azure App Registration setup to obtain:

Tenant ID - Your Azure AD tenant identifier
Client ID - Your application (client) ID
Client Secret - Your application secret value

Setup time: ~10-15 minutes per account

See Setup Guide for complete step-by-step instructions.

Permission Validation

This skill requires the following delegated permissions (user consent required):

Email Permissions

```
Mail.Read
```
- Read user email
```
Mail.ReadWrite
```
- Read and write access to user email
```
Mail.Send
```
- Send email as the user

Calendar Permissions

```
Calendars.Read
```
- Read user calendars
```
Calendars.ReadWrite
```
- Read and write access to user calendars

Contact Permissions

```
Contacts.Read
```
- Read user contacts
```
Contacts.ReadWrite
```
- Read and write access to user contacts

Profile Permissions (required for authentication)

```
User.Read
```
- Sign in and read user profile
```
offline_access
```
- Maintain access to data (refresh tokens)

IMPORTANT: Before proceeding with setup, confirm that you understand and approve these permissions. Each permission grants specific access to your Microsoft 365 data.

See Permissions Reference for detailed information about what each permission allows.

Configuration

Multi-Account Configuration (v2.0.0+)

Accounts are stored in

~/.openclaw/auth/office365-accounts.json

with tokens in

~/.openclaw/auth/office365/

Use the

accounts.js

CLI to manage:

node accounts.js list                # List all accounts
node accounts.js add <name> ...      # Add account
node accounts.js remove <name>       # Remove account
node accounts.js default <name>      # Set default

Legacy Single-Account (Backward Compatible)

Environment variables still work for single-account use:

export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"

Or in OpenClaw config:

{
  "env": {
    "vars": {
      "AZURE_TENANT_ID": "your-tenant-id",
      "AZURE_CLIENT_ID": "your-client-id",
      "AZURE_CLIENT_SECRET": "your-client-secret"
    }
  }
}

Authentication Flow

This skill uses OAuth 2.0 Device Code Flow for resilient authentication:

Request device code from Microsoft
Display user code and verification URL
User visits URL and enters code
Poll for token completion
Store access + refresh tokens (per-account)
Automatically refresh tokens when expired

Token storage: Tokens are securely stored in

~/.openclaw/auth/office365/<account-name>.json

with mode 0600 (owner read/write only).

Usage Examples

Multi-Account Email Operations

# Read from default account
node email.js recent 10
Read from specific account
node email.js recent 10 --account=work
Search in consulting account
node email.js search "proposal" --account=consulting
Send from appropriate identity

node send-email.js send client@example.com "Update" "..." --account=consulting

Multi-Account Calendar Operations

# Check work calendar
node calendar.js today --account=work
Check personal calendar

node calendar.js week --account=personal

Account Management

# List all configured accounts
node accounts.js list
Check authentication status
node auth.js status --account=work
Re-authenticate if needed

node auth.js login --account=work

Real-World Use Cases

Multiple Work Identities

Perfect when working across multiple organizations:

# Morning: Check all calendars
node calendar.js today --account=work
node calendar.js today --account=consulting
node calendar.js today --account=startup
Process emails by identity
node email.js recent --account=work
node email.js recent --account=consulting
Send from appropriate account

node send-email.js send client@bigcorp.com "Proposal" "..." --account=work

Personal + Professional Separation

# Work hours: Work account
node calendar.js today --account=work
node email.js recent --account=work
After hours: Personal account

node email.js recent --account=personal

Error Handling

The skill includes robust error handling for:

Token expiration - Automatic refresh with exponential backoff
Rate limiting - Retry logic with appropriate delays
Network errors - Connection timeout handling
Permission errors - Clear messages about missing scopes
API errors - Detailed error messages from Microsoft Graph
Account not found - Helpful error messages with suggestions

Rate Limits

Microsoft Graph API has rate limits:

Per-app limit: 130,000 requests per hour
Per-user limit: Variable based on workload
Throttling: 429 status code triggers automatic retry

The skill automatically handles throttling with exponential backoff.

Security Considerations

Token Security: Tokens stored with restricted file permissions (0600)
Per-Account Isolation: Each account has separate token storage
Scope Limitation: Request only the minimum required permissions
Refresh Tokens: Rotated automatically, old tokens invalidated
Client Secret: Never logged or exposed; stored with mode 0600
Multi-tenant: This setup is single-tenant (your organization only)

Troubleshooting

Multi-Account Issues

"No account specified and no default account set"

# Set a default account
node accounts.js default work
Or always specify --account=

node calendar.js today --account=work

"Account not found"

# List available accounts
node accounts.js list
Add the missing account
node accounts.js add <name> <tenant> <client> <secret>

Authentication expired

# Check status
node auth.js status --account=work
Re-authenticate

node auth.js login --account=work

Common Issues

"AADSTS700016: Application not found in directory"

Verify Tenant ID matches your Azure AD tenant
Ensure app registration wasn't deleted

"AADSTS65001: User did not consent"

Complete the device code flow authentication
Check Admin Consent if required by organization

"AADSTS700082: Expired refresh token"

Re-authenticate using device code flow
Check token storage file permissions

"403 Forbidden"

Verify API permissions are granted in Azure
Check if admin consent is required

See Setup Guide and MULTI-ACCOUNT.md for detailed troubleshooting.

Limitations

Attachment size: Max 4MB per attachment (API limit)
Email recipients: Max 500 recipients per email
Calendar events: Limited to 1,095 days in the future
Batch operations: Max 20 requests per batch

Command Reference

Account Management

node accounts.js list                           # List all accounts
node accounts.js add <name> <tenant> <client> <secret> [email] [desc]
node accounts.js remove <name>                  # Remove account
node accounts.js default <name>                 # Set default
node accounts.js import-legacy                  # Import v1.0.0 setup

Authentication

node auth.js login [--account=name]            # Authenticate
node auth.js status [--account=name]           # Check status
node auth.js token [--account=name]            # Get access token

Email

node email.js recent [count] [--account=name]
node email.js search "query" [--account=name]
node email.js from email@domain [--account=name]
node email.js read <id> [--account=name]

Calendar

node calendar.js today [--account=name]
node calendar.js week [--account=name]

Send & Manage

node send-email.js send <to> <subject> <body> [--account=name]
node send-email.js reply <message-id> <body> [--account=name]
node cancel-event.js <event-id> [comment] [--account=name]

Resources

Documentation Files

MULTI-ACCOUNT.md - Complete multi-account usage guide
CHANGELOG.md - Version history and changes
CREDITS.md - Attribution and acknowledgments
references/setup-guide.md - Azure App Registration walkthrough
references/permissions.md - Security and permissions reference

Microsoft Resources

Microsoft Graph API Documentation: https://learn.microsoft.com/en-us/graph/api/overview
Delegated vs Application Permissions: https://learn.microsoft.com/en-us/graph/auth/auth-concepts
Rate Limiting: https://learn.microsoft.com/en-us/graph/throttling

Credits

Original Skill: office365-connector v1.0.0 from ClawHub Community

Multi-Account Enhancement (v2.0.0): Matthew Gordon (matt@workandthrive.ai)

Thank you to Matthew Gordon for contributing the multi-account enhancement that makes this skill significantly more useful for consultants, freelancers, and anyone managing multiple work identities!

See CREDITS.md for complete attribution.

License

Maintains compatibility with the original skill's licensing. See CREDITS.md for details.

Office 365 Connector

AI Skill Market Insights

Be Part of the 2,412+ Developer Community