成为赞助商——支持中文 Agent 生态

了解赞助
库Agent场景库
← 返回用例列表

Gmail API Push/Watch 通知配置清单

按 Cloud Pub/Sub 前置、mailbox watch、historyId/expiration 续订与历史同步,整理邮件变更推送配置清单;不代持 OAuth、不代建生产订阅。

飞书ClaudeChatGPTn8n⚡ 效率办公🏢 企业协作

场景说明

面向个人效率与轻量企业自动化:把「别轮询邮箱、改用推送」写成可对账步骤,衔接行动项抽取上游。

案例叙事

01他们做了什么

个人助理想把「新邮件→待办」做成近实时,却用定时全量拉收件箱,既慢又费配额。

Google《Configure push notifications with the Gmail API》说明:Gmail API 提供服务端推送,便于监视邮箱变更,减少轮询成本。指南仍推荐用同步客户端那套方式取更新。推送经由 Cloud Pub/Sub 投递,可用 webhook 或在单一订阅上拉取。前置需完成 Pub/Sub 相关设置后,对用户邮箱发起 watch;成功时响应类似包含 `historyId` 与 `expiration`:historyId 表示当前邮箱历史水位,客户端会收到该水位之后的变更通知;若还需处理更早变更,应另行用历史接口补齐。expiration 到期后需重新 watch 才能继续收通知。本场景据此输出「Pub/Sub→watch→续订→按 history 拉信」配置清单,作为个人效率链路的上游信号,而不是直接生成待办正文。禁止声称「生产推送已接通」。

02实际效果

  • 源未披露量化「相对轮询节省的请求比例」;公开文只描述推送动机、Pub/Sub、watch 响应字段与续订必要性。
  • 能把「只有通知没有正文 / watch 过期 / history 断档」拆开处理。
  • 可为后续「邮件行动项→待办」自动化提供可靠触发源设计。

03值得知道

  • 需 Google Cloud 项目、Pub/Sub 与合适的 Gmail OAuth 范围;配额与计费以 Google 当前政策为准。
  • 通知可能重复或乱序,业务侧应按 historyId 做幂等。
  • 上面写的是官方配置路径,不是你项目里的订阅实况。

04可复制提示词

Gmail Watch 配置清单

你是 Gmail API 推送配置助手。只给核对清单,不要编造已接通。

GCP/Pub/Sub 摘要:{{pubsub_brief}}
OAuth 范围摘要:{{scopes}}
已有 watch 响应或报错:{{watch_response}}

输出 Markdown:
1. Pub/Sub 前置是否齐全的提问
2. 发起 watch 后必存字段(historyId、expiration)
3. 到期续订与补历史策略
4. 测试项目验收步骤
禁止索要 refresh token;禁止代建云资源。

推送中断复盘提纲

Gmail 推送突然停更或漏信,请写复盘提纲。

最后成功通知时间:{{last_push}}
expiration:{{expiration}}
history 同步摘要:{{history_brief}}

输出:
1. 是否过期未续 watch
2. Pub/Sub 订阅/权限问题提问
3. history 断档补齐步骤
4. 临时改回受控轮询的边界
不要伪造「已恢复推送」。

怎么做

  1. 粘贴是否已有 GCP Pub/Sub 主题/订阅、Gmail OAuth 范围摘要,以及 watch 响应或报错
  2. Agent 按官方指南输出:Pub/Sub 前置→发起 watch→保存 historyId/expiration→到期续订→用 history 拉变更提问清单
  3. 人工在测试项目配置;Agent 不代完成 OAuth 同意屏、不代创建计费资源

实用提示

  • watch 成功响应含当前 historyId 与 expiration;客户端只保证收到该 historyId 之后的变更通知
  • 推送只是信号,具体邮件内容仍要用历史/消息接口拉取;到期必须重新 watch
#Gmail API#Push#Pub/Sub#watch#个人效率