Outlook Delegate

Read, search, and manage Outlook emails and calendar via Microsoft Graph API with delegate support. Your AI assistant authenticates as itself but accesses the owner's mailbox/calendar as a delegate. Modified for delegate access from https://clawhub.ai/jotamed/outlook

Security Scan

The skill's instructions match its stated purpose (delegated Outlook access) but it references missing scripts, encourages storing client secrets in a plaintext config, and lacks a clear source/homepage — these mismatches and data-handling details warrant caution.

Purpose & Capability

The name/description (Outlook delegate via Microsoft Graph) align with the instructions: the docs explain delegated OAuth flows, required delegated Graph permissions, Exchange mailbox delegate commands, and use of the /users/{owner} endpoint. The skill asks for the expected credentials (client_id/client_secret) and owner/delegate emails. Minor inconsistency: registry metadata lists no required env vars/primary credential, but the SKILL.md expects a local config file containing the client_id/client_secret — this is plausible but not declared in metadata.

Instruction Scope

The SKILL.md instructs running several scripts (./scripts/outlook-token.sh, outlook-mail.sh, outlook-calendar.sh) and using a config path (~/.outlook-mcp/config.json) but the skill bundle contains no code files — those scripts are not present. That means following these instructions would require the user to create or fetch additional code from elsewhere. The doc also advises storing client_secret directly in a plaintext config file and using mail/calendar FullAccess or SendOnBehalf permissions — both are functional for the purpose but present clear security and privilege implications that the user must accept intentionally.

Install Mechanism

No install spec and no code files are present; the skill is instruction-only, so nothing is automatically downloaded or written by an installer. That lowers installer risk but means the agent cannot actually run the referenced scripts unless the user or an external source supplies them.

Credentials

Requested secrets (client_id and client_secret) are appropriate for OAuth delegated access and are proportionate to the stated functionality. However, the SKILL.md recommends storing client_secret in plaintext at ~/.outlook-mcp/config.json, and the Exchange commands require high privileges (Add-MailboxPermission, Set-Mailbox). The skill does not request unrelated credentials, but it does require the owner/admin to grant broad mailbox/calendar access — a high-privilege action that should be limited and audited.

Persistence & Privilege

always is false and the skill does not request permanent platform-level privileges. It does instruct creation of a per-user config file and use of refresh tokens (offline_access) — meaning long-lived tokens may be stored locally. Combined with FullAccess or SendOnBehalf permissions, those tokens could be used to operate on the owner's mailbox until revoked, so the persistence implications are significant even if the skill itself is not marked always:true.

What to consider before installing

This instruction-only skill generally describes a valid delegated Graph/Exchange workflow, but proceed carefully: 1) The package contains no scripts — the SKILL.md references ./scripts/*.sh that are missing. Do not copy/paste or run scripts from unknown sources; ask the publisher for the actual implementation or inspect them before use. 2) The doc recommends storing client_secret in plaintext at ~/.outlook-mcp/config.json — prefer a secure secret store or OS-provided credential manager and minimize how long secrets/tokens are readable on disk. 3) Delegate mailbox permissions (FullAccess, SendOnBehalf) and offline_access tokens are powerful: only grant them when you trust the assistant account and have auditing/revocation procedures. 4) Because there is no homepage or published source, verify the origin of any scripts or code you add; prefer registering an Azure app in your tenant with least-privilege delegated permissions and follow Microsoft security best practices. 5) If you want to proceed, request the missing scripts or a canonical source, review their contents, and consider doing initial tests in a non-production mailbox.

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:

• Your AI assistant has its own Microsoft 365 account (e.g., [e-mail])
• The owner has granted the assistant delegate access to their mailbox/calendar
• The assistant authenticates as itself but accesses the owner's resources

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": "[e-mail]",
  "delegate_email": "[e-mail]"
}

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):

• Mail.ReadWrite.Shared - Read/write access to shared mailboxes
• Mail.Send.Shared - Send mail on behalf of others
• Calendars.ReadWrite.Shared - Read/write shared calendars
• User.Read - Read assistant's own profile
• offline_access - Refresh tokens

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 "[e-mail]" -User "[e-mail]" -AccessRights FullAccess

# Grant Send-on-Behalf
Set-Mailbox -Identity "[e-mail]" -GrantSendOnBehalfTo "[e-mail]"

# Grant calendar access (Editor = can create/modify events)
Add-MailboxFolderPermission -Identity "[e-mail]:\Calendar" -User "[e-mail]" -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/{[e-mail]}/ 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 <email> [count]    # Owner's mail from sender
./scripts/outlook-mail.sh read <id>               # Read email content

Managing Owner's Emails

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

Sending Emails (On Behalf Of Owner)

./scripts/outlook-mail.sh send <to> <subj> <body>  # Send on behalf of owner
./scripts/outlook-mail.sh reply <id> "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 <id>           # Event details
./scripts/outlook-calendar.sh free <start> <end>  # Owner's availability

Creating Events on Owner's Calendar

./scripts/outlook-calendar.sh create <subj> <start> <end> [location]
./scripts/outlook-calendar.sh quick <subject> [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": "[e-mail]"
      }
    },
    "toRecipients": [{"emailAddress": {"address": "[e-mail]"}}],
    "body": {"contentType": "Text", "content": "..."}
  }
}

The recipient sees: "Assistant on behalf of Owner [e-mail]"

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 "[e-mail]" -GrantSendOnBehalfTo "[e-mail]"

"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

• ~/.outlook-mcp/config.json - Client ID, secret, and owner/delegate emails
• ~/.outlook-mcp/credentials.json - OAuth tokens (access + refresh)

Changelog

v1.0.0 (Delegate Edition)

• Breaking: API calls now use /users/{owner} instead of /me
• Added: owner_email and delegate_email config fields
• Added: Send-on-behalf support with proper from field
• Changed: Permissions to .Shared variants
• Added: Delegate setup documentation
• Added: Token test validates access to owner's mailbox
• Based on outlook v1.3.0 by jotamed (https://clawhub.ai/jotamed/outlook)