Back to Details

m365-mail

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Microsoft 365 Mail

Microsoft 365 Mail

CLI tool for Microsoft 365 email via Microsoft Graph API.
一款通过Microsoft Graph API操作Microsoft 365邮件的CLI工具。

Setup (One-time)

初始化设置（一次性操作）

1. Register Entra ID App

1. 注册Entra ID应用

  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
  1. 访问 Entra ID门户 → 应用注册 → 新注册
  2. 名称：
    m365mail-cli
    （或自定义名称）
  3. 支持的账户类型：“仅限此组织目录中的账户”
  4. 重定向URI：留空（使用设备代码流）
  5. 点击“注册”

2. Configure API Permissions

2. 配置API权限

  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)
  1. 在你的应用中 → API权限 → 添加权限
  2. 选择Microsoft Graph → 委派权限
  3. 添加：
    Mail.ReadWrite
    、
    Mail.Send
  4. 点击“授予管理员同意”（或联系管理员完成此操作）

3. Enable Public Client Flow

3. 启用公共客户端流

  1. In your app → Authentication
  2. Under "Advanced settings", set "Allow public client flows" to Yes
  3. Save
  1. 在你的应用中 → 身份验证
  2. 在“高级设置”下，将“允许公共客户端流”设置为是
  3. 保存设置

4. Note Your IDs

4. 记录相关ID

  • Application (client) ID: Found on app Overview page
  • Directory (tenant) ID: Found on app Overview page
  • 应用程序（客户端）ID：在应用概览页面查看
  • 目录（租户）ID：在应用概览页面查看

5. Install & Configure

5. 安装与配置

bash
undefined
bash
undefined

Install dependencies

Install dependencies

pip install msal requests
pip install msal requests

Make executable

Make executable

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

Optional: symlink to PATH

Optional: symlink to PATH

ln -s $(pwd)/skills/m365-mail/scripts/m365mail.py /usr/local/bin/m365mail
ln -s $(pwd)/skills/m365-mail/scripts/m365mail.py /usr/local/bin/m365mail

Configure

Configure

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

Authenticate (opens browser for device code)

Authenticate (opens browser for device code)

m365mail auth
undefined
m365mail auth
undefined

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
bash
m365mail inbox                    # 最近20条消息
m365mail inbox -n 50              # 最近50条消息
m365mail inbox -u                 # 仅显示未读消息
m365mail inbox -v                 # 包含消息预览
m365mail inbox --json             # 以JSON格式输出

Read Message

读取消息

bash
m365mail read <message_id>        # Full message
m365mail read <id> --max-length 500  # Truncate body
m365mail read <id> --json         # JSON output
bash
m365mail read <message_id>        # 完整消息内容
m365mail read <id> --max-length 500  # 截断消息正文
m365mail read <id> --json         # 以JSON格式输出

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
bash
m365mail search "quarterly report"      # 全文搜索
m365mail search -f boss@company.com     # 搜索特定发件人的邮件
m365mail search -u                      # 仅搜索未读邮件
m365mail search -a                      # 搜索包含附件的邮件
m365mail search "budget" -f cfo@co.com -u  # 组合多个筛选条件

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
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
bash
m365mail folders                  # 列出所有文件夹
m365mail move <message_id> Archive    # 将消息移动到指定文件夹
m365mail move <message_id> "Deleted Items"
m365mail delete <message_id>      # 永久删除消息
m365mail mark <message_id> --read     # 标记为已读
m365mail mark <message_id> --unread   # 标记为未读

Output Formats

输出格式

  • Default: Human-readable table/text
  • --json
    : Machine-readable JSON (use for programmatic access)
  • -v
    /
    --verbose
    : Include message preview
  • 默认：易读的表格/文本格式
  • --json
    ：机器可读的JSON格式（用于程序化访问）
  • -v
    /
    --verbose
    ：包含消息预览内容

Message IDs

消息ID

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.
消息由类似
AAMkAGI2...
的长ID标识。命令支持：
  • 完整ID
  • ID前缀（通常前8个及以上字符即可唯一标识）
收件箱/搜索结果会显示
[AAMkAGI2]
前缀，方便快速引用。

Token Storage

令牌存储

Tokens cached at 
~/.m365mail/
:
  • config.json
    - Client/tenant IDs
  • token_cache.json
    - OAuth tokens (auto-refreshes)
令牌缓存存储在
~/.m365mail/
目录下：
  • config.json
    - 客户端/租户ID
  • token_cache.json
    - OAuth令牌（自动刷新）

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
“无缓存令牌”：运行
m365mail auth
权限被拒绝：确保已授予Mail.ReadWrite和Mail.Send权限（可能需要管理员同意）
令牌过期：工具会自动刷新令牌；若问题持续，重新运行
m365mail auth