office365-connector

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** ([matt@workandthrive.ai](mailto:matt@workandthrive.ai)) - 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> you@work.com "Work account"

# Authenticate
node auth.js login --account=work
```

### Add More Accounts

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

```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 client@example.com "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 client@example.com "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 client@bigcorp.com "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