home / skills / openclaw / skills / outlook

outlook skill

safe

/skills/jotamed/outlook

This skill helps you read, manage, and schedule emails and events in Outlook using Microsoft Graph API.

npx playbooks add skill openclaw/skills --skill outlook

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

7.0 KB

---
name: outlook
description: Read, search, and manage Outlook emails and calendar via Microsoft Graph API. Use when the user asks about emails, inbox, Outlook, Microsoft mail, calendar events, or scheduling.
version: 1.3.0
author: jotamed
---

# Outlook Skill

Access Outlook/Hotmail email and calendar via Microsoft Graph API using OAuth2.

## Quick Setup (Automated)

```bash
# Requires: Azure CLI, jq
./scripts/outlook-setup.sh
```

The setup script will:
1. Log you into Azure (device code flow)
2. Create an App Registration automatically
3. Configure API permissions (Mail.ReadWrite, Mail.Send, Calendars.ReadWrite)
4. Guide you through authorization
5. Save credentials to `~/.outlook-mcp/`

## Manual Setup

See `references/setup.md` for step-by-step manual configuration via Azure Portal.

## Usage

### Token Management
```bash
./scripts/outlook-token.sh refresh  # Refresh expired token
./scripts/outlook-token.sh test     # Test connection
./scripts/outlook-token.sh get      # Print access token
```

### Reading Emails
```bash
./scripts/outlook-mail.sh inbox [count]           # List latest emails (default: 10)
./scripts/outlook-mail.sh unread [count]          # List unread emails
./scripts/outlook-mail.sh search "query" [count]  # Search emails
./scripts/outlook-mail.sh from <email> [count]    # List emails from sender
./scripts/outlook-mail.sh read <id>               # Read email content
./scripts/outlook-mail.sh attachments <id>        # List email attachments
```

### Managing Emails
```bash
./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 unflag <id>             # Remove flag
./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
```bash
./scripts/outlook-mail.sh send <to> <subj> <body> # Send new email
./scripts/outlook-mail.sh reply <id> "body"       # Reply to email
```

### Folders & Stats
```bash
./scripts/outlook-mail.sh folders                 # List mail folders
./scripts/outlook-mail.sh stats                   # Inbox statistics
```

## Calendar

### Viewing Events
```bash
./scripts/outlook-calendar.sh events [count]      # List upcoming events
./scripts/outlook-calendar.sh today               # Today's events
./scripts/outlook-calendar.sh week                # This week's events
./scripts/outlook-calendar.sh read <id>           # Event details
./scripts/outlook-calendar.sh calendars           # List all calendars
./scripts/outlook-calendar.sh free <start> <end>  # Check availability
```

### Creating Events
```bash
./scripts/outlook-calendar.sh create <subj> <start> <end> [location]  # Create event
./scripts/outlook-calendar.sh quick <subject> [time]                  # Quick 1-hour event
```

### Managing Events
```bash
./scripts/outlook-calendar.sh update <id> <field> <value>  # Update (subject/location/start/end)
./scripts/outlook-calendar.sh delete <id>                  # Delete event
```

Date format: `YYYY-MM-DDTHH:MM` (e.g., `2026-01-26T10:00`)

### Example Output

```bash
$ ./scripts/outlook-mail.sh inbox 3

{
  "n": 1,
  "subject": "Your weekly digest",
  "from": "[email protected]",
  "date": "2026-01-25T15:44",
  "read": false,
  "id": "icYY6QAIUE26PgAAAA=="
}
{
  "n": 2,
  "subject": "Meeting reminder",
  "from": "[email protected]",
  "date": "2026-01-25T14:06",
  "read": true,
  "id": "icYY6QAIUE26PQAAAA=="
}

$ ./scripts/outlook-mail.sh read "icYY6QAIUE26PgAAAA=="

{
  "subject": "Your weekly digest",
  "from": { "name": "Digest", "address": "[email protected]" },
  "to": ["[email protected]"],
  "date": "2026-01-25T15:44:00Z",
  "body": "Here's what happened this week..."
}

$ ./scripts/outlook-mail.sh stats

{
  "folder": "Inbox",
  "total": 14098,
  "unread": 2955
}

$ ./scripts/outlook-calendar.sh today

{
  "n": 1,
  "subject": "Team standup",
  "start": "2026-01-25T10:00",
  "end": "2026-01-25T10:30",
  "location": "Teams",
  "id": "AAMkAGQ5NzE4YjQ3..."
}

$ ./scripts/outlook-calendar.sh create "Lunch with client" "2026-01-26T13:00" "2026-01-26T14:00" "Restaurant"

{
  "status": "event created",
  "subject": "Lunch with client",
  "start": "2026-01-26T13:00",
  "end": "2026-01-26T14:00",
  "id": "AAMkAGQ5NzE4YjQ3..."
}
```

## Token Refresh

Access tokens expire after ~1 hour. Refresh with:

```bash
./scripts/outlook-token.sh refresh
```

## Files

- `~/.outlook-mcp/config.json` - Client ID and secret
- `~/.outlook-mcp/credentials.json` - OAuth tokens (access + refresh)

## Permissions

- `Mail.ReadWrite` - Read and modify emails
- `Mail.Send` - Send emails
- `Calendars.ReadWrite` - Read and modify calendar events
- `offline_access` - Refresh tokens (stay logged in)
- `User.Read` - Basic profile info

## Notes

- **Email IDs**: The `id` field shows the last 20 characters of the full message ID. Use this ID with commands like `read`, `mark-read`, `delete`, etc.
- **Numbered results**: Emails are numbered (n: 1, 2, 3...) for easy reference in conversation.
- **Text extraction**: HTML email bodies are automatically converted to plain text.
- **Token expiry**: Access tokens expire after ~1 hour. Run `outlook-token.sh refresh` when you see auth errors.
- **Recent emails**: Commands like `read`, `mark-read`, etc. search the 100 most recent emails for the ID.

## Troubleshooting

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

**"Invalid grant"** → Token invalid, re-run setup: `outlook-setup.sh`

**"Insufficient privileges"** → Check app permissions in Azure Portal → API Permissions

**"Message not found"** → The email may be older than 100 messages. Use search to find it first.

**"Folder not found"** → Use exact folder name. Run `folders` to see available folders.

## Supported Accounts

- Personal Microsoft accounts (outlook.com, hotmail.com, live.com)
- Work/School accounts (Microsoft 365) - may require admin consent

## Changelog

### v1.3.0
- Added: **Calendar support** (`outlook-calendar.sh`)
  - View events (today, week, upcoming)
  - Create/quick-create events
  - Update event details (subject, location, time)
  - Delete events
  - Check availability (free/busy)
  - List calendars
- Added: `Calendars.ReadWrite` permission

### v1.2.0
- Added: `mark-unread` - Mark emails as unread
- Added: `flag/unflag` - Flag/unflag emails as important
- Added: `delete` - Move emails to trash
- Added: `archive` - Archive emails
- Added: `move` - Move emails to any folder
- Added: `from` - Filter emails by sender
- Added: `attachments` - List email attachments
- Added: `reply` - Reply to emails
- Improved: `send` - Better error handling and status output
- Improved: `move` - Case-insensitive folder names, shows available folders on error

### v1.1.0
- Fixed: Email IDs now use unique suffixes (last 20 chars)
- Added: Numbered results (n: 1, 2, 3...)
- Improved: HTML bodies converted to plain text
- Added: `to` field in read output

### v1.0.0
- Initial release

Overview

This skill lets you read, search, and manage Outlook/Hotmail emails and calendar events through the Microsoft Graph API. It uses OAuth2 for authentication and provides command-line scripts to list, read, send, move, flag, and archive messages as well as view, create, update, and delete calendar events. Setup can be automated or performed manually in the Azure Portal.

How this skill works

The skill stores app credentials and OAuth tokens locally (~/.outlook-mcp/) and calls Microsoft Graph endpoints to perform mail and calendar operations. Scripts wrap Graph API calls for common tasks (inbox, search, read, send, mark-read/unread, folders, events, create/update/delete). Tokens expire after ~1 hour and can be refreshed with a provided helper script. Results are returned as compact JSON-like objects for easy parsing.

When to use it

You need to programmatically read or search Outlook emails from the command line.
You want to send, reply to, or manage email state (mark read/unread, flag, move, archive, delete).
You need to list, create, update, or delete calendar events and check free/busy availability.
You prefer scripted automation for inbox statistics, folder listings, or attachment discovery.
You need an OAuth-backed tool supporting personal and Microsoft 365 accounts.

Best practices

Run the automated setup script to create Azure app registration and grant required API permissions (Mail.ReadWrite, Mail.Send, Calendars.ReadWrite).
Store and back up ~/.outlook-mcp/ config and credentials securely; treat client secret and refresh tokens as sensitive.
Refresh tokens before long automation runs using outlook-token.sh refresh to avoid auth failures.
When operating on messages, use search first if an ID isn’t found—commands search the 100 most recent messages by default.
Use ISO date format YYYY-MM-DDTHH:MM when creating or updating events to avoid parsing errors.

Example use cases

List the latest 10 inbox messages and read full body for a selected item.
Search for messages from a specific sender and archive or move matching items to a folder.
Send a new message or reply to an existing message directly from scripts.
Create a one-hour quick event or schedule a meeting with precise start/end timestamps.
Check calendar availability between two timestamps to plan meetings across calendars.

FAQ

Which accounts are supported?

Personal Microsoft accounts (outlook.com, hotmail.com, live.com) and Work/School Microsoft 365 accounts are supported; admin consent may be required for org tenants.

What do I do when I see "Token expired"?

Run ./scripts/outlook-token.sh refresh to renew the access token. If refresh fails, re-run the setup script to reauthorize.

Why is a message not found by ID?

IDs are taken from the last 20 characters of the full message ID and commands search only the 100 most recent messages. Use search to locate older messages or provide the correct full-suffix ID.