Microsoft 365 Skill for OpenClaw

This skill empowers your OpenClaw agent to manage your Microsoft 365 Emails and Calendar directly from the terminal. It leverages the ms365 CLI tool to perform operations securely and efficiently.

Prerequisites

Before using this skill, ensure the ms365 CLI package is installed on the local system or available via npx.

# To install globally:
npm install -g ms365

Requirements:

• Node.js 22 or later
• A Microsoft 365 account (work, school, or personal)
• An Azure AD app registration with delegated permissions

Authentication Lifecycle

The agent cannot authenticate on behalf of the user. The user must manually run these commands beforehand or you can prompt the user to run them in an interactive terminal.

1. Configure Azure App credentials: ms365 auth configure --client-id <ID> --tenant-id <ID>
2. Login to Microsoft 365: ms365 auth login (Uses Device Code flow; user action required)
3. Check Auth Status: ms365 auth status
4. Logout: ms365 auth logout

Capabilities & Usage Instructions

You (the Agent) can use the bash tool to execute ms365 CLI commands to interact with the user's Microsoft 365 account. Below are the allowed operations.

📧 Email Operations

List Emails

Use this to check recent messages or list items in a specific folder.

• Command: ms365 email list
• Modifiers:
  • -c, --count <number>: Number of results (default: 20)
  • -f, --folder <name>: Target folder - supports well-known names (inbox, sentitems, drafts, etc.), folder display names (case-insensitive), or folder IDs
  • --select <fields>: Comma-separated fields (e.g., subject,from,bodyPreview)
  • --list-folders: Show available folders instead of listing emails
  • --all-folders: List emails from all folders at once
• Example: ms365 email list -c 5 -f inbox
• Example: ms365 email list --list-folders

Read Email

Fetches the full content of an email message given its ID.

• Command: ms365 email read <id>
• Example: ms365 email read AAMkADYzZ1...

Search Emails

Use Keyword Query Language (KQL) to find specific emails.

• Command: ms365 email search "<kql-query>"
• Modifiers:
  • -c, --count <number>: Result count limit
• Example: ms365 email search "from:boss@example.com subject:urgent" -c 10

Send Email

Compose and send an email directly without drafting it first.

• Command: ms365 email send [options]
• Modifiers:
  • --to <addresses>: Comma-separated recipient emails (Required)
  • --subject "<subject>": Email subject line
  • --body "<body>": The content of the email
  • --cc, --bcc: Additional recipients
  • --html: Treats the --body as HTML content
  • --importance <low|normal|high>: Sets email priority
• Example: ms365 email send --to "jane@example.com" --subject "Meeting Notes" --body "Please find the notes attached."

Draft Email

Create an email that gets saved to the Drafts folder instead of sending immediately.

• Command: ms365 email draft [options]
• Modifiers: (Same as Send Email)
• Example: ms365 email draft --to "team@example.com" --subject "Weekly Update" --body "Draft content here"

Move Email

Move an email from one folder to another. Supports well-known folder names, custom folder display names, and folder IDs.

• Command: ms365 email move <id> <destination>
• Modifiers:
  • --list-folders: Show available folders before moving
• Note: <destination> can be a well-known folder name (inbox, drafts, sentitems, deleteditems, junkemail, archive, outbox), a folder display name (case-insensitive), or a folder ID.
• Example: ms365 email move AAMkAD... archive
• Example: ms365 email move AAMkAD... "Archive 2024"

Delete Email

Moves an email to 'Deleted Items' or deletes it permanently.

• Command: ms365 email delete <id>
• Modifiers:
  • --permanent: Hard-deletes the email bypassing 'Deleted Items'.
• Example: ms365 email delete AAMkAD...

List Folders

List all available mail folders with metadata including unread counts and folder structure.

• Command: ms365 email folders list
• Modifiers:
  • -c, --count <number>: Max number of folders (default: 50)
  • --select <fields>: Comma-separated fields
• Example: ms365 email folders list

Folder Info

Get detailed information about a specific folder by name or ID.

• Command: ms365 email folders info <folder>
• Example: ms365 email folders info inbox

Create Folder

Create a new custom mail folder.

• Command: ms365 email folders create <name>
• Modifiers:
  • --parent <parentFolderId>: Parent folder ID for nested folders
• Example: ms365 email folders create "Archive 2024"

📅 Calendar Operations

List Events

Fetch upcoming calendar events.

• Command: ms365 calendar list
• Modifiers:
  • -d, --days <number>: Lookahead days limit (default is 7)
  • --start <datetime>, --end <datetime>: ISO 8601 constraints (overrides days)
  • -c, --count <number>: Maximum entries to return
• Example: ms365 calendar list --days 3 -c 10

Create Event

Schedule a new meeting or blocker on the user's calendar.

• Command: ms365 calendar create [options]
• Modifiers:
  • --subject "<title>": Event title
  • --start <datetime>: ISO 8601 string (e.g., 2024-07-01T09:00:00)
  • --end <datetime>: ISO 8601 string (e.g., 2024-07-01T10:00:00)
  • --timezone <tz>: IANA timezone (default UTC, e.g., America/New_York)
  • --attendees <emails>: Comma-separated addresses
  • --body "<content>": Event details (--html can be used to treat body as HTML)
  • --location "<location>": Physical or virtual location string
  • --all-day: Flag to make this an all-day event
  • --online-meeting: Automatically creates and attaches a Teams link
• Example: ms365 calendar create --subject "Sync" --start "2024-07-01T09:00:00" --end "2024-07-01T09:30:00" --attendees "bob@example.com" --online-meeting

Delete Event

Remove an event from the calendar.

• Command: ms365 calendar delete <id>
• Example: ms365 calendar delete AAMkADc...

Create Recurring Event

Schedule a recurring meeting or blocker on the user's calendar.

• Command: ms365 calendar series-create [options]
• Modifiers:
  • --subject "<title>": Event title (Required)
  • --start <datetime>: ISO 8601 start time (Required)
  • --end <datetime>: ISO 8601 end time (Required)
  • --pattern <pattern>: Recurrence pattern (daily, weekly, absoluteMonthly, relativeMonthly, absoluteYearly, relativeYearly) (Required)
  • --interval <number>: Interval between occurrences (default: 1)
  • --days-of-week <days>: For weekly patterns (Mo,Tu,We,Th,Fr,Sa,Su)
  • --range <type>: How recurrence ends (endDate, noEnd, numbered) (default: noEnd)
  • --end-date <datetime>: End date for recurrence (Required if range is endDate)
  • --occurrences <number>: Number of occurrences (Required if range is numbered)
  • --timezone <tz>: IANA timezone (default: UTC)
  • --attendees <emails>: Comma-separated addresses
  • --body "<content>": Event details
  • --location "<location>": Physical or virtual location
  • --all-day: Make this an all-day event
  • --online-meeting: Automatically creates and attaches a Teams link
• Example: ms365 calendar series-create --subject "Daily Standup" --start "2024-07-10T09:00:00" --end "2024-07-10T09:30:00" --pattern daily --range numbered --occurrences 10

Delete Recurring Event

Remove a recurring event or individual occurrences from the series.

• Command: ms365 calendar series-delete <id>
• Modifiers:
  • --this-and-following: Delete this and following events in series
  • --single: Delete only this single occurrence
• Example: ms365 calendar series-delete AAMkADc...

📇 Contacts Operations

List Contacts

Fetch contacts from your personal contacts folder.

• Command: ms365 contacts list
• Modifiers:
  • -c, --count <number>: Number of results (default: 50)
  • --select <fields>: Comma-separated fields
• Example: ms365 contacts list --count 25

Search Contacts

Search contacts by name or email address.

• Command: ms365 contacts search "<query>"
• Modifiers:
  • -c, --count <number>: Max results to return (default: 25)
• Example: ms365 contacts search "alice@example.com" --count 10

• Data limits: By default, list commands return bounded records. If you need more context, use --count responsibly. Do not request more than 100 items at once to avoid payload bloating.
• Always Verify IDs: Ensure that you have the correct item ID before executing mutating operations like move or delete. You can retrieve IDs using the list or search commands.
• Dates and Timezones: When creating calendar events, verify the user's local timezone. Always provide explicit timezones using the --timezone flag or use UTC natively.
• Auth Tokens: If ms365 returns authentication errors like Token expired or Unauthorized, prompt the user to run ms365 auth login.