mcpField
M
m365-mail

m365-mail

github.com/probichauxProductivity0109 installsUpdated 40w ago
Repository

About m365-mail

m365-mail is a command-line tool for managing Microsoft 365 email through Microsoft Graph. It supports reading, searching, sending, and organizing messages, with text and JSON output for interactive or scripted use.

Key features

  1. 01List inbox messages with filters
  2. 02Read and search email
  3. 03Send text or HTML email
  4. 04Move, delete, and mark messages
  5. 05Human-readable and JSON output

Use cases

  1. 01Review unread inbox messages
  2. 02Find email by sender or attachment
  3. 03Send messages to one or more recipients
  4. 04Archive or update message status

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/probichaux/clawdskills --skill m365-mail

After installing, type/m365-mailin Claude Code to confirm it loaded.

Bundled filesscripts/m365mailscripts/m365mail.py

Details

From the project README

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
# 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
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
m365mail read <message_id>        # Full message
m365mail read <id> --max-length 500  # Truncate body
m365mail read <id> --json         # JSON output
Search
m365mail search "quarterly report"      # Full-text search
m365mail search -f [email protected]     # From specific sender
m365mail search -u                      # Unread only
m365mail search -a                      # Has attachments
m365mail search "budget" -f [email protected] -u  # Combine filters
Send Email
m365mail send --to [email protected] --subject "Hello" --body "Message body"
m365mail send --to [email protected] [email protected] --cc [email protected] --subject "Hi" --body "Text"
m365mail send --to [email protected] --subject "Report" --body-file report.txt
m365mail send --to [email protected] --subject "HTML" --body "<h1>Hi</h1>" --html
Manage Messages
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

Comments

Markdown supported