基于 knowledge-work-plugins 仓库的 Zoom Mail API 完整端点指南41 个邮件操作与实战集成【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本文是knowledge-work-plugins仓库中 Zoom Plugin 的 REST API 参考技能rest-api 技能下 mail.md 的深度展开。它面向需要在 Claude Cowork 等知识工作者场景中通过 Zoom Mail API 自动化邮件处理的开发者完整覆盖 41 个端点操作、26 个路径模板、10 个标签下的全部能力。读完本文你将掌握 Zoom Mail API 的端点全景、细粒度授权 scope 映射、草稿与发送、标签与筛选器、委托与假期回复等核心实战模式并能结合仓库中的认证、限流与排错文档直接落地实现。Zoom Mail API 在仓库中的定位与数据来源mail.md是 rest-api 技能下 39 个领域参考文件之一其余如 meetings.md、phone.md它的角色是Mail 领域的权威端点清单endpoint inventory文档明确声明其镜像了官方 Zoom API Hub 的 OpenAPI 文档endpoints.json端点方法method与路径path直接来自官方paths对象。因此在实现时应以本文件作为路径命名的权威来源而将 examples 目录 中的编排模式作为流程参考不要把编排示例当作路径的权威出处。该技能的整体导航路径是先通过plan-zoom-product、plan-zoom-integration或debug-zoom确定方案再进入 rest-api 技能获取端点级细节见 SKILL.md。基础设施基线Base URLhttps://api.zoom.us/v2所有 Mail 端点均挂在该前缀之下认证见仓库中的 authentication.md支持 Server-to-Server OAuth、User OAuth 2.0 与已弃用的JWT路径参数约定所有端点都以/emails/mailboxes/{email}/...为前缀{email}是目标邮箱地址部分端点进一步使用{draftId}、{messageId}、{labelId}、{threadId}、{attachmentId}、{delegateEmail}、{filterId}等资源标识覆盖规模指标数值端点操作operations41路径模板path templates26标签tags10从源码结构可以推断mail.md 与 meetings.md183 操作、128 路径、19 标签采用同一套生成式清单格式只是领域不同两者的 Notes 区块与字段说明完全一致这印证了该参考文件体系的“镜像 OpenAPI”定位。前置准备认证与授权 Scope所有 Mail 端点都需要 Bearer Token 认证Authorization: Bearer {access_token}并绑定特定的授权 scope。仓库中的 authentication.md 与 api-architecture.md 给出了完整指引这里提炼与 Mail 集成最相关的要点。两种推荐的认证方式方式适用场景Token 有效期Server-to-Server OAuth后端自动化、批量处理、无需用户交互1 小时User OAuth 2.0代表具体用户操作其邮箱1 小时可刷新refresh token 最长 15 年获取 S2S token 的标准流程摘自 SKILL.md 快速开始curl -X POST https://zoom.us/oauth/token \ -H Authorization: Basic $(echo -n CLIENT_ID:CLIENT_SECRET | base64) \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typeaccount_credentialsaccount_idACCOUNT_ID响应中包含access_token、expires_in通常 3600 秒与scope字段。注意S2S 应用不得使用me关键字必须提供真实邮箱地址或用户 ID——而 Mail 端点路径本身就是邮箱地址天然契合这一要求。Mail 领域的授权 Scopemail.md 中明确提示每个操作的 scope 名称按操作单独定义且频繁使用细粒度 scopegranular scope实现前需到 API Hub 操作页确认精确 scope。仓库的 granular-scopes.md 恰好维护了这份细粒度映射以下是 Mail 相关操作与 scope 的对应关系每项均有:admin变体用于跨账户管理操作细粒度 ScopeList emails from the mailboxemail:read:list_msgsGet the specified emailemail:read:msgCreate a new email / Send out an emailemail:write:msg/email:write:send_msgUpdate the specified emailemail:write:modify_msgDelete an existing emailemail:delete:msgMove email to/out of TRASHemail:write:trash_msg/email:write:untrash_msgBatch delete / batch modify emailsemail:write:batch_delete_msgs/email:write:batch_modify_msgsList drafts / get draft / create draft / update draft / delete draft / send draftemail:read:list_drafts、email:read:draft、email:write:draft、email:update:draft、email:delete:draft、email:write:send_draftList labels / get / create / update / patch / delete labelemail:read:list_labels、email:read:label、email:write:label、email:update:label、email:delete:labelList history of events for mailboxemail:read:historyGet mailbox profileemail:read:profileGet email attachmentemail:read:attachmentVacation response get/updateemail:read:setting_vacation/email:update:setting_vacationDelegates list/grant/get/revokeemail:read:list_setting_delegates、email:write:setting_delegate、email:read:setting_delegate、email:delete:setting_delegateFilters list/create/get/deleteemail:read:list_setting_filters、email:write:setting_filter、email:read:setting_filter、email:delete:setting_filterThreads list/get/update/delete/trash/untrashemail:read:list_threads、email:read:thread、email:write:thread、email:delete:thread、email:write:trash_thread、email:write:untrash_thread同时仓库 classic-scopes.md 记录了 Mail 的经典聚合 scopemail:read读取用户自身邮箱内容、mail:read:admin读取账户下所有邮箱及账户级设置、mail:write读写用户自身邮箱内容、mail:write:admin读写账户下所有邮箱及账户级设置。设计应用时建议遵循最小权限原则仅请求实际用到的 scope细粒度 scope 比经典 scope 更容易通过审核。环境变量约定仓库 environment-variables.md 规定了标准.env键ZOOM_CLIENT_ID、ZOOM_CLIENT_SECRET必填ZOOM_ACCOUNT_IDS2S 模式、ZOOM_REDIRECT_URIUser OAuth 模式、ZOOM_WEBHOOK_SECRET接收事件时ZOOM_ACCESS_TOKEN、ZOOM_REFRESH_TOKEN属于运行时值。端点全景按标签展开 41 个操作以下各小节完整继承 mail.md 的端点清单并补充每个标签的典型使用场景与实现提示。Drafts草稿6 个操作草稿是“先存后发”工作流的核心适合需要审批、定时或多次编辑后再发送的场景。方法端点说明操作 IDGET/emails/mailboxes/{email}/drafts列出草稿文件夹中的邮件list_draft_emailsPOST/emails/mailboxes/{email}/drafts创建新草稿邮件create_draft_emailPOST/emails/mailboxes/{email}/drafts/send发送草稿邮件send_draft_emailDELETE/emails/mailboxes/{email}/drafts/{draftId}删除已有草稿delete_draft_emailGET/emails/mailboxes/{email}/drafts/{draftId}获取指定草稿get_draft_emailPUT/emails/mailboxes/{email}/drafts/{draftId}更新指定草稿update_draft_email典型流水线是创建草稿 → 多次 PUT 更新 → POST/drafts/send发送。以创建草稿为例curl -X POST https://api.zoom.us/v2/emails/mailboxes/aliceexample.com/drafts \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d { subject: Weekly Sync, body: {text: Hi team, here is the agenda...}, to: [{email: bobexample.com}] }实际请求体字段收件人、抄送、密送、附件、主题、正文等以 API Hub 操作页的 schema 为准实现时可先 GET 一次已有草稿观察响应结构再据此构造创建请求。History历史1 个操作方法端点说明操作 IDGET/emails/mailboxes/{email}/history列出邮箱的事件历史list_mailbox_history该端点用于增量同步场景类似“最近更改”日志可用于检测新邮件、已读状态变化、删除等事件。适合与 Webhook 配合或在无法部署 Webhook 时做低频率的增量轮询注意限流约束详见后文限流章节。Labels标签6 个操作方法端点说明操作 IDGET/emails/mailboxes/{email}/labels列出邮箱中的标签list_labels_in_mailboxPOST/emails/mailboxes/{email}/labels创建新标签create_label_in_mailboxDELETE/emails/mailboxes/{email}/labels/{labelId}从邮箱删除标签delete_label_from_mailboxGET/emails/mailboxes/{email}/labels/{labelId}获取指定标签get_label_in_mailboxPATCH/emails/mailboxes/{email}/labels/{labelId}部分更新指定标签patch_label_in_mailboxPUT/emails/mailboxes/{email}/labels/{labelId}整体更新指定标签update_label_in_mailbox标签用于对邮件分类如 “客户跟进”“报销”PATCH 与 PUT 并存说明该 API 同时支持部分字段与整体替换两种更新语义。创建标签示例curl -X POST https://api.zoom.us/v2/emails/mailboxes/aliceexample.com/labels \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d {name: VIP Clients, color: blue}Mailbox邮箱资料1 个操作方法端点说明操作 IDGET/emails/mailboxes/{email}/profile获取邮箱资料get_mailbox_profile用于读取邮箱的显示名、配额等元信息是初始化界面或校验邮箱有效性的快捷方式需要email:read:profilescope。Messages邮件10 个操作这是最核心的标签覆盖邮件的全生命周期。方法端点说明操作 IDGET/emails/mailboxes/{email}/messages列出邮箱中的邮件list_emailsPOST/emails/mailboxes/{email}/messages创建新邮件create_emailPOST/emails/mailboxes/{email}/messages/batchDelete批量删除指定邮件batch_delete_emailsPOST/emails/mailboxes/{email}/messages/batchModify批量修改指定邮件batch_modify_emailsPOST/emails/mailboxes/{email}/messages/send发送邮件send_emailDELETE/emails/mailboxes/{email}/messages/{messageId}删除已有邮件delete_emailGET/emails/mailboxes/{email}/messages/{messageId}获取指定邮件get_emailPOST/emails/mailboxes/{email}/messages/{messageId}/modify更新指定邮件update_emailPOST/emails/mailboxes/{email}/messages/{messageId}/trash将邮件移入 TRASH 文件夹trash_emailPOST/emails/mailboxes/{email}/messages/{messageId}/untrash将邮件移出 TRASH 文件夹untrash_email关键设计点删除 vs 回收站DELETE /messages/{messageId}是硬删除trash_email/untrash_email则是软回收站语义可在误操作后恢复。面向用户的产品应优先暴露 trash 而非 delete。批量操作batchDelete与batchModify允许一次处理多条邮件能显著减少 API 调用次数——这与 rate-limiting-strategy.md 中“优先批量、避免逐条调用”的建议完全一致。直接发送 vs 草稿POST /messages/send直接发送而 Drafts 标签提供两段式流程。需要“先建后审再发”的合规场景用草稿低延迟自动化场景直接用send_email。批量删除示例请求体为待删除的 messageId 列表curl -X POST https://api.zoom.us/v2/emails/mailboxes/aliceexample.com/messages/batchDelete \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d {ids: [msgId1, msgId2]}Messages.Attachments附件1 个操作方法端点说明操作 IDGET/emails/mailboxes/{email}/messages/{messageId}/attachments/{attachmentId}获取指定邮件的指定附件get_email_attachment需要email:read:attachmentscope。附件 ID 通常来自get_email返回的附件列表获取时可结合下载场景注意响应可能是文件流或 Base64以 API Hub schema 为准。Settings设置2 个操作方法端点说明操作 IDGET/emails/mailboxes/{email}/settings/vacation获取邮箱假期自动回复设置get_mail_vacation_response_settingPUT/emails/mailboxes/{email}/settings/vacation更新邮箱假期自动回复设置update_mailbox_vacation_response_setting用于自动化休假流程——例如员工在日历上的休假事件开始时自动开启假期回复。更新示例curl -X PUT https://api.zoom.us/v2/emails/mailboxes/aliceexample.com/settings/vacation \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d {enabled: true, subject: Out of office, message: I will reply after returning.}Settings.Delegates委托4 个操作方法端点说明操作 IDGET/emails/mailboxes/{email}/settings/delegates列出邮箱上的委托list_mailbox_delegatesPOST/emails/mailboxes/{email}/settings/delegates授予新的邮箱委托访问权限grant_mailbox_delegateDELETE/emails/mailboxes/{email}/settings/delegates/{delegateEmail}撤销已有委托访问权限revoke_mailbox_delegateGET/emails/mailboxes/{email}/settings/delegates/{delegateEmail}获取指定委托get_mailbox_delegate委托让助理或团队成员代为处理他人邮箱如行政助理代管经理邮箱。{delegateEmail}参数使用被委托人的邮箱地址。Settings.Filters筛选器4 个操作方法端点说明操作 IDGET/emails/mailboxes/{email}/settings/filters列出邮件筛选器list_email_filtersPOST/emails/mailboxes/{email}/settings/filters创建邮件筛选器create_email_filterDELETE/emails/mailboxes/{email}/settings/filters/{filterId}删除指定筛选器delete_email_filterGET/emails/mailboxes/{email}/settings/filters/{filterId}获取指定筛选器get_email_filter筛选器用于自动分类如按发件人域、关键词移动到指定标签可视为邮箱内自动化规则的管理接口。Threads会话线程6 个操作方法端点说明操作 IDGET/emails/mailboxes/{email}/threads列出邮箱中的邮件线程list_email_threadsDELETE/emails/mailboxes/{email}/threads/{threadId}删除已有线程delete_email_threadGET/emails/mailboxes/{email}/threads/{threadId}获取指定线程get_email_threadPOST/emails/mailboxes/{email}/threads/{threadId}/modify更新指定线程update_email_threadPOST/emails/mailboxes/{email}/threads/{threadId}/trash将线程移入 TRASH 文件夹trash_email_threadPOST/emails/mailboxes/{email}/threads/{threadId}/untrash将线程移出 TRASH 文件夹untrash_email_thread线程 API 以会话为单位批量操作——例如“整段会话归档”只需一个调用比逐条处理邮件高效得多。在邮件列表界面list_email_threads应作为主数据源配合get_email_thread展示详情。从端点清单到可运行集成实战模式将上述端点组合可以形成若干可直接落地的自动化模式。模式一草稿审批式发送create_draft_email创建草稿由人工或规则get_draft_email/update_draft_email审核修改send_draft_email最终发送。适合需要合规留痕、双人复核的对外通信场景。模式二邮箱清理与归档list_emails分页拉取注意使用next_page_token而非旧的page_number详见 api-architecture.md 与排错文档对过期邮件执行batchDelete/batchModify或逐条trash_email需要恢复时通过untrash_email或untrash_email_thread还原。模式三自动化处理流程用list_mailbox_history发现增量变化用get_email/get_email_attachment读取内容与附件用create_label_in_mailboxbatch_modify_emails自动打标签用send_email自动应答或转发。模式四委托与假期管理用grant_mailbox_delegate/revoke_mailbox_delegate管理代管权限用get_mail_vacation_response_setting/update_mailbox_vacation_response_setting联动休假日历自动切换假期回复。限流、错误处理与可靠性Mail 端点同样受 Zoom 全局限流约束关键事实见 rate-limiting-strategy.md限流按账户而非按应用同一账户下所有应用共享配额一个重负载应用会影响其他应用按计划分档免费版 Light 4 次/秒、Medium 2 次/秒、Heavy 1 次/秒Pro 为 30/20/10 次/秒Business 为 80/60/40 次/秒Resource-Intensive 类别单独计算响应头每个响应携带X-RateLimit-Category、X-RateLimit-TypeQPS / Daily-limit、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset日限额场景还有Retry-After重试策略收到 429 时使用指数退避 抖动jitter优先读取Retry-After判断是秒级还是日级限额并发限制部分资源操作存在单并发约束如对同一资源并发 DELETE需要串行化。对于 Mail 特有的批量场景尤其要用batchDelete/batchModify代替循环单条调用把 N 次请求压成 1 次既省配额又降低 429 风险。诊断 429/401 等错误时可参考 common-errors.md 与 token-scope-playbook.md。一处使用本参考文件的正确姿势根据 mail.md 的 Notes 声明使用本文件时应注意端点方法与路径以本清单为准不要从编排示例反推路径名scope 按操作粒度定义实现前务必核对目标操作对应的细粒度 scope可对照本仓库 granular-scopes.md认证实现参考 authentication.md 及 zoom-oauth 技能完整 OAuth 流程S2S / User / PKCE / Device Code见 authentication-flows.md若构建事件驱动型集成例如新邮件到达触发处理可参考 webhook-server.md 与 zoom-webhooks 技能 的模式。小结Zoom Mail API 通过 41 个操作覆盖了从草稿、发送、批量管理、标签、线程、附件到委托、筛选器与假期回复的完整邮件自动化面。作为 rest-api 技能中的权威端点清单mail.md 为端点发现提供了可靠基准配合本仓库的认证、限流、scope 与排错文档开发者可以在 Claude Cowork 知识工作流中构建稳定、合规、低配额消耗的邮件自动化能力。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考