Agent skill · hexbee
m365-oauth-mail
m365-oauth-mail — an agent skill for coding agents.
What it needs
About 1k tokens when loaded.
What this skill does
M365 邮箱 OAuth2 只读访问（设备码 + Outlook REST） 适用于任何能执行Python3脚本的环境，只依赖标准库。 背景与坑位（实测 2026-08） 1. 密码直连 IMAP 已被微软全面禁用：imaplib + 密码登录 outlook.office365.com:993 会报 AUTHENTICATE failed，不要走这条路。 2. Thunderbird 公共客户端 ID（9e5f94bc-...）在开启管理员审批的租户会弹 "Enter justification for requesting this app"，走不通。 3. 解法：用微软第一方 Office 客户端 ID d3590ed6-52b3-4102-aeff-aad2292ab01c， 第一方应用免管理员审批，设备码流程直接成功。 4. 该 ID 的令牌不含 IMAP.AccessAsUser.All（IMAP XOAUTH2 仍会失败），但含 Mail.ReadWrite / EWS.AccessAsUser.All / OutlookService.AccessAsUser.All， 改走 Outlook REST API v2.0 即可：GET https://outlook.office365.com/api/v2.0/me/messages。 关键技术点 认证用 v1 端点（非 v2.0）：https://login.microsoftonline.com/common/oauth2/ devicecode 请求：clientid + resource=https://outlook.office365.com token 轮询参数名是 code（v1 不叫 devicecode，两个都传最稳） token 刷新：granttype=refreshtoken + resource v1 端点返回的字段：verificationurl（不是 verificationuri）、expiresin 是字符串 （代码里要 float() 转换） 设备码要落盘保存（含 expiresat），进程因网络抖动挂掉后重启可复用未过期设备码 HTTP 请求加重试（代理环境偶发 502 Tunnel connection failed） REST API 返回字段是 PascalCase（Subject/From/ReceivedDateTime/BodyPreview）， BodyPreview 直接可用作摘要，无需解析正文 令牌文件权限 chmod 600；不要把令牌或密码写进任何 prompt / 配置模板 现成脚本 scripts/fetchemails.py（仅标准库，python3 直接运行，支持 --help）： 去重机制：每次运行会把拉取到的消息 Id 记入 emailseen.json（带时间戳，31 天自动修剪）。 默认输出全部邮件并在头部显示「共 X 封，其中 Y 封新」，新邮件带 [新] 标记； 定时任务建议配 --new-only，避免窗口重叠时重复分类。 退出码：0 成功 / 2 网络 / 3 认证失败 / 4 [NEEDLOGIN] 令牌失效需重新 login / 5 API 错误。 stdout 输出 markdown 摘要，错误信息走 stderr，方便 agent 判断分支。 数据目录 脚本默认自动使用固定数据目录 ~/.m365-oauth-mail/（无需任何配置，目录不存在会自动创建）。 ~/.m365-oauth-mail/emailtokens.json：OAuth 令牌（600 权限，核心实例数据） ~/.m365-oauth-mail/emailpendingdevice.json：授权中设备码断点（授权成功自动删除） ~/.m365-oauth-mail/emailseen.json：已见消息 Id 去重记录（保留 31 天自动修剪） 可选 ~/.m365-oauth-mail/emailconfig.json：{"hours": 12} 固定默认时间窗口 多邮箱场景：用环境变量 MAILDATADIR 为每个邮箱指定独立目录 （如 MAILDATADIR=~/.m365-oauth-mail-corp python3 fetchemails.py login），互不干扰。 定时总结 任意调度机制均可（cron：0 20 ，或 agent 自带的定时任务能力）。要点： 每次运行脚本（无参数 = 最近 24h），把 stdout 交给 agent/LLM 生成分类摘要： 【需要回复/行动】【重要通知】【可忽略】三组，每封一行 （主题 发件人 时间 一句话摘要） 处理退出码分支：4 → 提 …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills hexbee/m365-oauth-mail