playbooks

home / skills / probichaux / clawdskills / m365-mail

m365-mail skill

/m365-mail

This skill helps you read, search, and send Microsoft 365 email via Graph API, streamlining inbox management and message workflows.

npx playbooks add skill probichaux/clawdskills --skill m365-mail

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

Files (4)
SKILL.md
3.7 KB
---
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](https://entra.microsoft.com/) → 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 [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
```bash
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
```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

Overview

This skill lets you read, search, send, and manage Microsoft 365 email using the Microsoft Graph API. It provides CLI commands to list inbox messages, read full messages, search with filters, send mail (plain or HTML), and manage folders and message states. It supports human-readable and JSON output and uses OAuth device code flow for authentication.

How this skill works

The skill authenticates via Microsoft Entra ID using delegated permissions (Mail.ReadWrite, Mail.Send) and caches tokens locally for auto-refresh. Commands call the Graph API to fetch messages, perform full-text searches, move or delete items, mark read/unread, and send messages with attachments or HTML bodies. Output can be shown in readable tables or emitted as JSON for programmatic use.

When to use it

  • Check your inbox quickly from a terminal without opening a web client.
  • Search across mail with filters (sender, unread, has attachments) from scripts.
  • Send automated or one-off emails from CI, cron jobs, or development tools.
  • Manage messages and folders (move, delete, mark read/unread) programmatically.
  • Integrate email checks or sends into larger automation workflows.

Best practices

  • Register an Entra app and grant Mail.ReadWrite and Mail.Send with admin consent before use.
  • Use device code flow for headless or CLI authentication and keep client/tenant IDs secure.
  • Prefer JSON output for scripting and human-readable output for interactive use.
  • Cache tokens securely (default ~/.m365mail/) and run m365mail auth if token issues occur.
  • Use ID prefixes shown in lists for convenient message references instead of full IDs.

Example use cases

  • List the last 20 inbox messages with previews to triage new mail.
  • Search for all unread messages from your manager with attachments before a meeting.
  • Send a status report from a deployment script using --body-file or HTML body.
  • Move processed messages to an Archive folder as part of an automation pipeline.
  • Export message metadata as JSON for analytics or audit tooling.

FAQ

What permissions are required?

The app needs delegated Mail.ReadWrite and Mail.Send permissions; admin consent may be required.

Where are tokens and config stored?

Configuration and token cache are stored under ~/.m365mail/ (config.json and token_cache.json).

How do I handle token expiration or 'No cached token'?

Run m365mail auth to re-authenticate; the tool auto-refreshes tokens but reauth may be needed if issues occur.