name	outlook-access
description	通过 Microsoft Graph API 访问 Outlook / Microsoft 365 账户：读取与搜索邮件、发送邮件（纯文本与 HTML）、按规则自动整理归档邮件、列出邮件文件夹、查看账户信息。调用方式：python3 outlook.py <子命令> 或直接传 Graph 路径。适用于任何需要读写用户 Outlook 邮箱的 Agent 任务。

Outlook Access (Microsoft Graph API)

让 Agent 通过官方 Microsoft Graph API 读写用户的 Outlook 邮箱。所有操作走 python3 outlook.py，Token 自动管理（过期自动刷新），无需用户重复授权。

前提

已授权（token 存在脚本同目录 .outlook-token.json）。若缺失，走 OAuth device code 授权（见下），用户打开 https://microsoft.com/link 输入代码即可。
已授权 scope：Mail.Read、Mail.ReadWrite、Mail.Send、User.Read、offline_access。

授权（AI 友好两阶段，不阻塞）

授权必须由用户本人确认（微软安全要求），但接口设计成 AI 可编排：

# 阶段 1: 发起授权, 立即返回 JSON(不阻塞)
python3 outlook.py authorize --json
# → {"status":"pending_user_action","verification_uri":"https://www.microsoft.com/link",
#    "user_code":"XXXX","expires_in":900,"poll_hint":"python3 outlook.py authorize --poll"}

# 把 user_code + verification_uri 展示给用户, 用户浏览器确认后:

# 阶段 2: 轮询一次, AI 可循环调用直到 success
python3 outlook.py authorize --poll
# → {"status":"success",...}   exit 0   (或 {"status":"pending",...} exit 2, 稍后重试)

--poll 退出码约定：0=授权成功、2=用户还没确认(稍后重试)、1=失败/被拒/过期
人也可以直接 python3 outlook.py authorize（阻塞式交互模式，自动等用户完成）

命令

命令	用途
`python3 outlook.py whoami`	查看当前授权账户
`python3 outlook.py folders`	列出所有邮件文件夹及邮件数
`python3 outlook.py "/me/messages?$top=10&$select=subject,from,receivedDateTime"`	直接调用任意 Graph v1.0 路径（读邮件/搜索/任何操作）
`python3 outlook.py stats [--folder 收件箱] [--top 30]`	按发件域名统计邮件分布
`python3 outlook.py organize --dry-run`	预览按规则整理的方案（不移动）
`python3 outlook.py organize --confirm --workers 8`	按 rules.json 规则批量归档邮件（多线程）
`python3 outlook.py move <message_id> <文件夹名>`	移动单封邮件

发送邮件（POST /me/sendMail）

# 经 outlook.py 的 graph() 函数
python3 - <<'EOF'
import outlook
outlook.graph("/me/sendMail", method="POST", body={
    "message": {
        "subject": "主题",
        "body": {"contentType": "Text", "content": "正文"},  # 或 "HTML"
        "toRecipients": [{"emailAddress": {"address": "xx@example.com"}}],
    },
    "saveToSentItems": True,
})
EOF

成功返回 HTTP 202。
发送对外邮件前必须先把完整内容展示给用户审核，用户确认后才能发。

整理规则（rules.json，可选）

脚本同目录 rules.json：[{"keyword": "github.com", "folder": "GitHub"}, ...]

keyword 对发件人域名做子串匹配；folder 为目标文件夹名。
提供 rules.example.json 作模板；rules.json 属个人配置，勿提交。

重要注意事项（踩坑记录）

移动邮件必须用 POST /me/messages/{id}/move（body: {"destinationId": 文件夹id}）。 PATCH parentFolderId 对个人账户返回 200 但静默无效，邮件不会移动。
移动后消息 id 会变化，用 move 响应里的新 id 验证。
验证移动结果要直接读取目标文件夹的 messages 列表； mailFolders 的 totalItemCount 和 $search 索引有延迟，不可作为依据。
Graph 对个人账户限流严格：脚本已内置 429 指数退避与网络重试，不要额外加大并发。
token 文件含敏感凭据，只存本地（.gitignore），勿外传。

FilesExpand file tree

SKILL.md

Latest commit

History