Skill: tirandagan/office365-connector (version 2.0.0)

--- name: office365-connector description: Office 365 / Outlook connector for email (read/send), calendar (read/write), and contacts (read/write) using resilient OAuth authentication. NOW WITH MULTI-ACCOUNT SUPPORT! Manage multiple Microsoft 365 identities from a single skill. Solves the difficulty connecting to Office 365 email, calendar, and contacts. Uses Microsoft Graph API with comprehensive Azure App Registration setup guide. Perfect for accessing your Microsoft 365/Outlook data from OpenClaw. --- # 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](MULTI-ACCOUNT.md) for complete usage guide. **Attribution:** Enhanced by **Matthew Gordon** ([[REDACTED_SECRET]](mailto:[REDACTED_SECRET])) - See [CREDITS.md](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](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 ```bash cd skills/office365-connector # Add account node accounts.js add work <tenant-id> <client-id> <client-secret> [REDACTED_SECRET] "Work account" # Authenticate node auth.js login --account=work ``` ### Add More Accounts ```bash # Add personal account node accounts.js add personal <tenant> <client> <secret> [REDACTED_SECRET] "Personal" # Add consulting account node accounts.js add consulting <tenant> <client> <secret> [REDACTED_SECRET] "Consulting" # Set default node accounts.js default work # List all accounts node accounts.js list ``` ### Use Your Accounts ```bash # 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 [REDACTED_SECRET] "Subject" "Body" --account=consulting ``` ### Migrate from Single-Account Setup Already using v1.0.0? No problem! ```bash # 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: 1. **Tenant ID** - Your Azure AD tenant identifier 2. **Client ID** - Your application (client) ID 3. **Client Secret** - Your application secret value **Setup time: ~10-15 minutes per account** See [Setup Guide](references/setup-guide.md) 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](references/permissions.md) 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: ```bash 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: ```bash 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: ```json { "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: 1. Request device code from Microsoft 2. Display user code and verification URL 3. User visits URL and enters code 4. Poll for token completion 5. Store access + refresh tokens (per-account) 6. 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 ```bash # 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 [REDACTED_SECRET] "Update" "..." --account=consulting ``` ### Multi-Account Calendar Operations ```bash # Check work calendar node calendar.js today --account=work # Check personal calendar node calendar.js week --account=personal ``` ### Account Management ```bash # 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: ```bash # 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 [REDACTED_SECRET] "Proposal" "..." --account=work ``` ### Personal + Professional Separation ```bash # 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 1. **Token Security**: Tokens stored with restricted file permissions (0600) 2. **Per-Account Isolation**: Each account has separate token storage 3. **Scope Limitation**: Request only the minimum required permissions 4. **Refresh Tokens**: Rotated automatically, old tokens invalidated 5. **Client Secret**: Never logged or exposed; stored with mode 0600 6. **Multi-tenant**: This setup is single-tenant (your organization only) ## Troubleshooting ### Multi-Account Issues **"No account specified and no default account set"** ```bash # Set a default account node accounts.js default work # Or always specify --account= node calendar.js today --account=work ``` **"Account not found"** ```bash # List available accounts node accounts.js list # Add the missing account node accounts.js add <name> <tenant> <client> <secret> ``` **Authentication expired** ```bash # 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](references/setup-guide.md) and [MULTI-ACCOUNT.md](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 ```bash 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 ```bash 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 ```bash 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 ```bash node calendar.js today [--account=name] node calendar.js week [--account=name] ``` ### Send & Manage ```bash 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](MULTI-ACCOUNT.md) - Complete multi-account usage guide - [CHANGELOG.md](CHANGELOG.md) - Version history and changes - [CREDITS.md](CREDITS.md) - Attribution and acknowledgments - [references/setup-guide.md](references/setup-guide.md) - Azure App Registration walkthrough - [references/permissions.md](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 ([[REDACTED_SECRET]](mailto:[REDACTED_SECRET])) 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](CREDITS.md) for complete attribution. ## License Maintains compatibility with the original skill's licensing. See [CREDITS.md](CREDITS.md) for details.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (HIGH)