--- name: outlook-delegate description: Read, search, and manage Outlook emails and calendar via Microsoft Graph API with delegate support. Supports sending as self, as owner (Send As), and on behalf of owner (Send on Behalf). Modified for delegate access from https://clawhub.ai/jotamed/outlook version: 1.1.0 author: 87marc ---

Outlook Delegate Skill

Access another user's Outlook/Microsoft 365 email and calendar as a delegate via Microsoft Graph API. Supports three sending modes: as yourself, as the owner, or on behalf of the owner.

Delegate Architecture

This skill is designed for scenarios where:

• Your AI assistant (the delegate) has its own Microsoft 365 account
• The owner has granted the assistant delegate access to their mailbox/calendar
• The assistant can send emails as itself, as the owner, or on behalf of the owner

Sending Modes Explained

All three modes use the same Graph API call (/users/{delegate}/sendMail with the from field set). The difference between Send As and Send on Behalf is determined entirely by which Exchange permission is granted, not by the API endpoint.

| Mode | Command | Exchange Permission Required | from field | sender field | What Recipient Sees | |------|---------|------------------------------|--------------|----------------|---------------------| | As Self | send | (none extra) | Delegate | Delegate | "From: Assistant" | | As Owner (Send As) | send-as | SendAs only | Owner | Owner | "From: Owner" | | On Behalf Of | send-behalf | SendOnBehalf only | Owner | Delegate | "From: Assistant on behalf of Owner" |

> ⚠️ CRITICAL: Do NOT grant both SendAs and SendOnBehalf permissions. If both are granted, Exchange always uses SendAs, and the "on behalf of" indication will never appear. Choose ONE based on your desired behavior.

How It Works Under the Hood

When you call send-as or send-behalf, the skill makes the same API call: it sends via the delegate's endpoint with the owner in the from field. Microsoft Graph automatically sets the sender property to the authenticated user (the delegate). Whether the recipient sees "on behalf of" depends solely on the Exchange permission:

• SendAs permission → Graph sets both sender and from to the owner. No indication of delegation.
• SendOnBehalf permission → Graph keeps sender as the delegate and from as the owner. Recipient sees "on behalf of."

Configuration

Config File: ~/.outlook-mcp/config.json

{
  "client_id": "your-app-client-id",
  "client_secret": "your-app-client-secret",
  "tenant_id": "your-tenant-id",
  "owner_email": "[email protected]",
  "owner_name": "Owner Display Name",
  "delegate_email": "[email protected]",
  "delegate_name": "AI Assistant",
  "timezone": "America/New_York"
}

| Field | Description | |-------|-------------| | client_id | Microsoft Entra ID App Registration client ID | | client_secret | Microsoft Entra ID App Registration client secret | | tenant_id | Your Microsoft Entra tenant ID (auto-detected during setup) | | owner_email | The mailbox the assistant accesses as delegate | | owner_name | Display name for the owner (used in From field) | | delegate_email | The assistant's own email address | | delegate_name | Display name for the assistant | | timezone | IANA timezone for calendar operations (e.g., America/New_York, Europe/London, UTC) |

Setup Requirements

1. Microsoft Entra ID App Registration

Create an app registration in Azure Portal:

1. Go to portal.azure.com → Microsoft Entra ID → App registrations
2. New registration:

- Name: "AI Assistant Mail Access" - Supported account types: "Accounts in this organizational directory only" (single tenant) - Redirect URI: http://localhost:8400/callback

1. Note the Application (client) ID and Directory (tenant) ID

2. Configure API Permissions

In your app → API permissions → Add a permission → Microsoft Graph → Delegated permissions:

Required for all modes:

• Mail.ReadWrite — Read/write assistant's own mail
• Mail.Send — Send mail as assistant
• Calendars.ReadWrite — Read/write calendars
• User.Read — Read own profile
• offline_access — Refresh tokens

Required for delegate access:

• Mail.ReadWrite.Shared — Read/write shared mailboxes
• Mail.Send.Shared — Send on behalf of others
• Calendars.ReadWrite.Shared — Read/write shared calendars

Click "Grant admin consent" (requires admin).

3. Create Client Secret

1. Certificates & secrets → New client secret
2. Description: "AI Assistant"
3. Expiration: Choose appropriate duration
4. Copy the Value immediately (shown only once)

4. Grant Exchange Delegate Permissions

The owner (or an admin) must grant the assistant access via PowerShell.

Choose your sending mode FIRST, then grant the appropriate permissions:

# Connect to Exchange Online
Install-Module -Name ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName [email protected]

# REQUIRED: Full Mailbox Access (for reading owner's mail)
Add-MailboxPermission -Identity "[email protected]" `
    -User "[email protected]" `
    -AccessRights FullAccess `
    -InheritanceType All `
    -AutoMapping $false

# REQUIRED: Calendar Delegate Access
Add-MailboxFolderPermission -Identity "[email protected]:\Calendar" `
    -User "[email protected]" `
    -AccessRights Editor `
    -SharingPermissionFlags Delegate

Then choose ONE of the following — do NOT grant both:

# OPTION A: Send As (emails appear directly from owner, no indication)
Add-RecipientPermission -Identity "[email protected]" `
    -Trustee "[email protected]" `
    -AccessRights SendAs `
    -Confirm:$false

# OPTION B: Send on Behalf (emails show "assistant on behalf of owner")
Set-Mailbox -Identity "[email protected]" `
    -GrantSendOnBehalfTo "[email protected]"

Verify permissions:

# Check mailbox permissions
Get-MailboxPermission -Identity "[email protected]" | Where-Object {$_.User -like "*assistant*"}

# Check Send As
Get-RecipientPermission -Identity "[email protected]" | Where-Object {$_.Trustee -like "*assistant*"}

# Check Send on Behalf
Get-Mailbox "[email protected]" | Select-Object GrantSendOnBehalfTo

# Check Calendar permissions
Get-MailboxFolderPermission -Identity "[email protected]:\Calendar"

5. Permissions Summary

| Action | Graph Permission | Exchange Permission | |--------|-----------------|---------------------| | Read owner's mail | Mail.ReadWrite.Shared | FullAccess | | Send as self | Mail.Send | (none needed) | | Send as owner | Mail.Send.Shared | SendAs only | | Send on behalf of owner | Mail.Send.Shared | SendOnBehalf only | | Read/write owner's calendar | Calendars.ReadWrite.Shared | Editor |

Usage

Token Management

./scripts/outlook-token.sh refresh   # Refresh expired token
./scripts/outlook-token.sh test      # Test connection to both accounts
./scripts/outlook-token.sh get       # Print access token
./scripts/outlook-token.sh info      # Show configuration info

Reading Owner's Emails

./scripts/outlook-mail.sh inbox [count]           # Owner's inbox
./scripts/outlook-mail.sh unread [count]          # Owner's unread
./scripts/outlook-mail.sh search "query" [count]  # Search owner's mail
./scripts/outlook-mail.sh from <email> [count]    # Owner's mail from sender
./scripts/outlook-mail.sh read <id>               # Read email content
./scripts/outlook-mail.sh attachments <id>        # List attachments

...