Outlook Delegate

Outlook Delegate Skill

Access another user's Outlook/Microsoft 365 email and calendar as a delegate via Microsoft Graph API.

Delegate Architecture

This skill is designed for scenarios where:

What Changed from Direct Access

| Feature | Direct Access (/me) | Delegate Access (/users/{id}) | |---------|----------------------|--------------------------------| | API Base | /me/messages | /users/{owner}/messages | | Send Email | Appears "From: Owner" | Appears "From: Assistant on behalf of Owner" | | Calendar | Full control | Based on permission level granted | | Permissions | Mail.ReadWrite, Mail.Send | Mail.ReadWrite.Shared, Mail.Send.Shared, Calendars.ReadWrite.Shared |

Configuration

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

{
  "client_id": "your-app-client-id",
  "client_secret": "your-app-client-secret",
  "owner_email": "owner@domain.com",
  "delegate_email": "assistant@domain.com"
}

The owner_email is the mailbox the assistant will access as a delegate.

Setup Requirements

1. Azure AD App Registration

The app registration needs delegated permissions (not application permissions):

2. Exchange Delegate Permissions (Admin or Owner)

The owner must grant the assistant delegate access via Exchange/Outlook:

PowerShell (Admin):

# Grant mailbox access
Add-MailboxPermission -Identity "owner@domain.com" -User "assistant@domain.com" -AccessRights FullAccess
Grant Send-on-Behalf
Set-Mailbox -Identity "owner@domain.com" -GrantSendOnBehalfTo "assistant@domain.com"
Grant calendar access (Editor = can create/modify events)
Add-MailboxFolderPermission -Identity "owner@domain.com:\Calendar" -User "assistant@domain.com" -AccessRights Editor -SharingPermissionFlags Delegate

Or via Outlook Settings: The owner can add the assistant as a delegate in Outlook → File → Account Settings → Delegate Access.

3. Token Flow

The assistant authenticates as itself via OAuth2, then accesses the owner's resources using the /users/{owner@domain.com}/ endpoint.

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

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  [count]    # Owner's mail from sender
./scripts/outlook-mail.sh read                # Read email content

Managing Owner's Emails

./scripts/outlook-mail.sh mark-read           # Mark as read
./scripts/outlook-mail.sh mark-unread         # Mark as unread
./scripts/outlook-mail.sh flag                # Flag as important
./scripts/outlook-mail.sh delete              # Move to trash
./scripts/outlook-mail.sh archive             # Move to archive
./scripts/outlook-mail.sh move        # Move to folder

Sending Emails (On Behalf Of Owner)

./scripts/outlook-mail.sh send     # Send on behalf of owner
./scripts/outlook-mail.sh reply  "body"        # Reply on behalf of owner

Note: Emails will show "Assistant on behalf of Owner" in the From field.

Owner's Calendar

./scripts/outlook-calendar.sh events [count]      # Owner's upcoming events
./scripts/outlook-calendar.sh today               # Owner's today
./scripts/outlook-calendar.sh week                # Owner's week
./scripts/outlook-calendar.sh read            # Event details
./scripts/outlook-calendar.sh free    # Owner's availability

Creating Events on Owner's Calendar

./scripts/outlook-calendar.sh create    [location]
./scripts/outlook-calendar.sh quick  [time]

API Endpoint Changes

The key change is replacing /me with /users/{owner_email}:

# Direct access (old)
API="https://graph.microsoft.com/v1.0/me"
Delegate access (new)
OWNER=$(jq -r '.owner_email' "$CONFIG_FILE")
API="https://graph.microsoft.com/v1.0/users/$OWNER"

Send-on-Behalf Implementation

When sending mail as a delegate, you must specify the from address:

{
  "message": {
    "subject": "Meeting follow-up",
    "from": {
      "emailAddress": {
        "address": "owner@domain.com"
      }
    },
    "toRecipients": [{"emailAddress": {"address": "recipient@example.com"}}],
    "body": {"contentType": "Text", "content": "..."}
  }
}

The recipient sees: "Assistant on behalf of Owner "

Permissions Summary

| Action | Required Permission | Exchange Setting | |--------|-------------------|-----------------| | Read owner's mail | Mail.ReadWrite.Shared | FullAccess or Reviewer | | Modify owner's mail | Mail.ReadWrite.Shared | FullAccess or Editor | | Send as owner | Mail.Send.Shared | SendOnBehalf | | Read owner's calendar | Calendars.ReadWrite.Shared | Reviewer+ | | Create events on owner's calendar | Calendars.ReadWrite.Shared | Editor |

Troubleshooting

"Access denied" or "403 Forbidden" → Check that the assistant has MailboxPermission on the owner's mailbox

"The mailbox is not found" → Verify owner_email in config.json is correct

"Insufficient privileges" → App registration missing .Shared permissions (check Azure AD)

Emails send but don't show "on behalf of" → Missing SendOnBehalf permission. Run:

Set-Mailbox -Identity "owner@domain.com" -GrantSendOnBehalfTo "assistant@domain.com"

"Token expired" → Run outlook-token.sh refresh

Security Considerations

1. Audit Trail: All actions by the assistant are logged in the owner's mailbox audit log 2. Token Storage: Credentials stored in ~/.outlook-mcp/ - protect this directory 3. Scope Limitation: The assistant only has access to what the owner explicitly grants 4. Revocation: The owner can revoke access anytime via Delegate settings

Files

Changelog

v1.0.0 (Delegate Edition)

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

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  [count]    # Owner's mail from sender
./scripts/outlook-mail.sh read                # Read email content

Managing Owner's Emails

./scripts/outlook-mail.sh mark-read           # Mark as read
./scripts/outlook-mail.sh mark-unread         # Mark as unread
./scripts/outlook-mail.sh flag                # Flag as important
./scripts/outlook-mail.sh delete              # Move to trash
./scripts/outlook-mail.sh archive             # Move to archive
./scripts/outlook-mail.sh move        # Move to folder

Sending Emails (On Behalf Of Owner)

./scripts/outlook-mail.sh send     # Send on behalf of owner
./scripts/outlook-mail.sh reply  "body"        # Reply on behalf of owner

Note: Emails will show "Assistant on behalf of Owner" in the From field.

Owner's Calendar

./scripts/outlook-calendar.sh events [count]      # Owner's upcoming events
./scripts/outlook-calendar.sh today               # Owner's today
./scripts/outlook-calendar.sh week                # Owner's week
./scripts/outlook-calendar.sh read            # Event details
./scripts/outlook-calendar.sh free    # Owner's availability

Creating Events on Owner's Calendar

./scripts/outlook-calendar.sh create    [location]
./scripts/outlook-calendar.sh quick  [time]

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

{
  "client_id": "your-app-client-id",
  "client_secret": "your-app-client-secret",
  "owner_email": "owner@domain.com",
  "delegate_email": "assistant@domain.com"
}

The owner_email is the mailbox the assistant will access as a delegate.

"Access denied" or "403 Forbidden" → Check that the assistant has MailboxPermission on the owner's mailbox

"The mailbox is not found" → Verify owner_email in config.json is correct

"Insufficient privileges" → App registration missing .Shared permissions (check Azure AD)

Emails send but don't show "on behalf of" → Missing SendOnBehalf permission. Run:

Set-Mailbox -Identity "owner@domain.com" -GrantSendOnBehalfTo "assistant@domain.com"

"Token expired" → Run outlook-token.sh refresh