Neura Market Logo

Outlook

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.

jotamed

@jotamed

What This Skill Does

Command-line toolkit for reading, searching, sending, and managing Outlook emails and calendar events via Microsoft Graph API. Provides scripts for inbox operations, email actions, and calendar management with OAuth2 authentication.

Replaces manually checking Outlook web or desktop by exposing email and calendar operations through a scriptable CLI with automated token management.

When to Use It

  • List recent emails in your Outlook inbox
  • Search Outlook for emails matching a specific query
  • Send an email from the command line
  • Check today's or this week's calendar events
  • Create a new calendar event with subject and time
  • Mark an email as read or flag it as important

Install

$ openclaw skills install @jotamed/outlook

Outlook Skill

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

Quick Setup (Automated)

# 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

./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

./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

./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

./scripts/outlook-mail.sh send <to> <subj> <body> # Send new email
./scripts/outlook-mail.sh reply <id> "body"       # Reply to email

Folders & Stats

./scripts/outlook-mail.sh folders                 # List mail folders
./scripts/outlook-mail.sh stats                   # Inbox statistics

Calendar

Viewing Events

./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

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

Managing Events

./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

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

{
  "n": 1,
  "subject": "Your weekly digest",
  "from": "digest@example.com",
  "date": "2026-01-25T15:44",
  "read": false,
  "id": "icYY6QAIUE26PgAAAA=="
}
{
  "n": 2,
  "subject": "Meeting reminder",
  "from": "calendar@outlook.com",
  "date": "2026-01-25T14:06",
  "read": true,
  "id": "icYY6QAIUE26PQAAAA=="
}

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

{
  "subject": "Your weekly digest",
  "from": { "name": "Digest", "address": "digest@example.com" },
  "to": ["you@hotmail.com"],
  "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:

./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

Top skills in this category

Gmail

@byungkyu

Gmail API integration with managed OAuth. Read, send, and manage emails, threads, labels, and drafts. Use this skill when users want to interact with Gmail. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).

7538k

WeChat MP CN

@guohongbin-git

微信公众号监控 - 文章监控、阅读量追踪、舆情分析（WeChat Official Account）

4714k

Wechat Article Search

@wuchubuzai2018

搜索微信公众号文章技能。通过微信搜索获取文章列表，覆盖科技/AI、社会热点、财经、教育、职场等各类中文资讯；可按关键词检索并返回标题、概要、发布时间、来源公众号与链接。当用户需要查找微信公众号文章、整理参考资料或快速获取文章信息时使用此技能。

3316k

Wechat Publisher

@0731coderlee-sudo

一键发布 Markdown 到微信公众号草稿箱。基于 wenyan-cli，支持多主题、代码高亮、图片自动上传。

399.3k

Google Meet

@byungkyu

Google Meet API integration with managed OAuth. Create meeting spaces, list conference records, and manage meeting participants. Use this skill when users wa...

1518k