AgentSkillsCN

m365-mail

通过 Graph API 读取、搜索、发送并管理 Microsoft 365 邮件。当用户咨询邮件、收件箱、消息，或希望在其 M365 账户中发送、阅读、搜索邮件时，可使用此技能。

SKILL.md
--- frontmatter
name: m365-mail
description: Read, search, send, and manage Microsoft 365 email via Graph API. Use when the user asks about email, inbox, messages, or wants to send/read/search mail in their M365 account.

Microsoft 365 Mail

CLI tool for Microsoft 365 email via Microsoft Graph API.

Setup (One-time)

1. Register Entra ID App

  1. •Go to Entra ID Portal → App registrations → New registration
  2. •Name: m365mail-cli (or whatever)
  3. •Supported account types: "Accounts in this organizational directory only"
  4. •Redirect URI: Leave blank (using device code flow)
  5. •Click Register

2. Configure API Permissions

  1. •In your app → API permissions → Add a permission
  2. •Microsoft Graph → Delegated permissions
  3. •Add: Mail.ReadWrite, Mail.Send
  4. •Click "Grant admin consent" (or have admin do it)

3. Enable Public Client Flow

  1. •In your app → Authentication
  2. •Under "Advanced settings", set "Allow public client flows" to Yes
  3. •Save

4. Note Your IDs

  • •Application (client) ID: Found on app Overview page
  • •Directory (tenant) ID: Found on app Overview page

5. Install & Configure

bash
# Install dependencies
pip install msal requests

# Make executable
chmod +x skills/m365-mail/scripts/m365mail.py

# Optional: symlink to PATH
ln -s $(pwd)/skills/m365-mail/scripts/m365mail.py /usr/local/bin/m365mail

# Configure
m365mail setup --client-id <YOUR_CLIENT_ID> --tenant-id <YOUR_TENANT_ID>

# Authenticate (opens browser for device code)
m365mail auth

Commands

List Inbox

bash
m365mail inbox                    # Last 20 messages
m365mail inbox -n 50              # Last 50 messages
m365mail inbox -u                 # Unread only
m365mail inbox -v                 # With preview
m365mail inbox --json             # JSON output

Read Message

bash
m365mail read <message_id>        # Full message
m365mail read <id> --max-length 500  # Truncate body
m365mail read <id> --json         # JSON output

Search

bash
m365mail search "quarterly report"      # Full-text search
m365mail search -f boss@company.com     # From specific sender
m365mail search -u                      # Unread only
m365mail search -a                      # Has attachments
m365mail search "budget" -f cfo@co.com -u  # Combine filters

Send Email

bash
m365mail send --to user@example.com --subject "Hello" --body "Message body"
m365mail send --to a@x.com b@x.com --cc c@x.com --subject "Hi" --body "Text"
m365mail send --to user@x.com --subject "Report" --body-file report.txt
m365mail send --to user@x.com --subject "HTML" --body "<h1>Hi</h1>" --html

Manage Messages

bash
m365mail folders                  # List all folders
m365mail move <message_id> Archive    # Move to folder
m365mail move <message_id> "Deleted Items"
m365mail delete <message_id>      # Permanently delete
m365mail mark <message_id> --read     # Mark read
m365mail mark <message_id> --unread   # Mark unread

Output Formats

  • •Default: Human-readable table/text
  • •--json: Machine-readable JSON (use for programmatic access)
  • •-v/--verbose: Include message preview

Message IDs

Messages are identified by long IDs like AAMkAGI2.... Commands accept:

  • •Full ID
  • •ID prefix (first 8+ chars usually unique)

The inbox/search output shows [AAMkAGI2] prefixes for easy reference.

Token Storage

Tokens cached at ~/.m365mail/:

  • •config.json - Client/tenant IDs
  • •token_cache.json - OAuth tokens (auto-refreshes)

Troubleshooting

"No cached token": Run m365mail auth

Permission denied: Ensure Mail.ReadWrite and Mail.Send permissions are granted (may need admin consent)

Token expired: Tool auto-refreshes; if issues persist, run m365mail auth again