🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Office 365 Connector
πŸ¦€ ClawHub

Office 365 Connector

by @tirandagan

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.

Versionv2.0.0
Downloads4,269
Stars⭐ 5
#clawhub
TERMINAL
clawhub install office365-connector

πŸ“– About This Skill

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 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    you@work.com "Work account"
    Authenticate
    
node auth.js login --account=work

    Add More Accounts

    # Add personal account
node accounts.js add personal    you@outlook.com "Personal"
    Add consulting account
    
node accounts.js add consulting    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

    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 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  ...      # Add account
node accounts.js remove        # Remove account
node accounts.js default       # 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:

    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/.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

    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" 

    # 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

    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     [email] [desc]
node accounts.js remove                   # Remove account
node accounts.js default                  # 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  [--account=name]

    Calendar

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

    Send & Manage

    node send-email.js send    [--account=name]
node send-email.js reply   [--account=name]
node cancel-event.js  [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.

    βš™οΈ 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  ...      # Add account
node accounts.js remove        # Remove account
node accounts.js default       # 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"
    }
  }
}

    πŸ“‹ Tips & Best Practices

    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

    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.