Composio Gmail 工具包实战指南OAuth 认证、邮件收发、附件上传与标签触发器【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本指南以 Composio 开源仓库中的 Gmail 支持文档 toolkits-gmail.md 为主体系统讲解如何在 Composio 平台上配置 Gmail 认证、发送与获取邮件、安全处理附件、管理标签以及配置新邮件触发器。读完本文你将掌握 Gmail 工具包的 Scope 选择与版本策略、GMAIL_SEND_EMAIL的正确调用姿势、附件超时排查流程以及从仓库源码与 FAQ 中可验证的底层实现细节。Gmail 工具包概览从 toolkits.json 可以看到Composio 的 Gmail 工具包slug 为gmail包含63 个工具与 2 个触发器版本号为20260828_00认证方式为OAUTH2同时提供 Composio 托管认证composioManagedAuthSchemes: OAUTH2。工具覆盖发信、收信、草稿、标签、过滤器、线程、设置等场景例如GMAIL_SEND_EMAIL/GMAIL_CREATE_EMAIL_DRAFT/GMAIL_SEND_DRAFT邮件发送链路GMAIL_LIST_LABELS/GMAIL_CREATE_LABEL/GMAIL_ADD_LABEL_TO_EMAIL标签管理GMAIL_CREATE_FILTER/GMAIL_DELETE_FILTER过滤器管理GMAIL_PATCH_SEND_AS/GMAIL_LIST_SEND_AS/GMAIL_GET_VACATION_SETTINGS较新的邮件设置工具。配置 Gmail OAuth、Scope 与工具包版本新 Gmail 设置工具使用latest或 v3.1 端点对于较新的 Gmail 工具如GMAIL_PATCH_SEND_AS、GMAIL_LIST_SEND_AS、GMAIL_GET_VACATION_SETTINGS必须在执行体中显式传入version: latest或者直接使用 v3.1 端点v3.1 端点默认使用 latest。原因在于v3 执行端点在不指定版本时可能默认回退到基础工具包版本00000000_00此时新版工具可能不可用或行为不一致。相关版本演进说明可参见 04-08-26-v31-api.mdx。先创建 Auth Config再发起连接Gmail 的自定义 OAuth 认证遵循两步走流程顺序不可颠倒先创建 Gmail Auth Config携带自定义 OAuth 凭据client ID、client secret、redirect URI并在credentials.scopes中声明所需 Scope再基于该 Auth Config 发起 Connected Account连接回调 URLcallback URL在发起连接时提供而 OAuth client ID/secret 与 redirect URI 保存在 Auth Config 上。也就是说回调地址属于连接这一层凭据属于认证配置这一层二者职责分离。这与仓库中的 auth_configs.py 与 connected_accounts.py 示例所展示的 API 用法一致。按需选择 Scope逗号拼接的 scopes 字符串创建 Gmail Auth Config 时在credentials.scopes中传入所需的 Gmail Scope通常以逗号拼接的字符串形式提供。常用示例Scope用途gmail.send发送邮件细粒度但属于敏感 Scopegmail.readonly只读获取邮件gmail.compose创建草稿gmail.modify读写并修改邮件gmail.labels管理标签创建过滤器必须使用gmail.settings.basicGmail 过滤器创建工具GMAIL_CREATE_FILTER对应 Gmail API 的users.settings.filters.create端点POST /gmail/v1/users/{userId}/settings/filters。Google 官方要求该端点必须使用https://www.googleapis.com/auth/gmail.settings.basic这一 OAuth Scope而当前 Composio 的GMAIL_CREATE_FILTERaction 声明的正是这唯一的必选 Scope。实操要点Google 必须为该 Scope 所在的 OAuth 应用完成审核批准如果同意屏幕因未验证的 Scope而拦截请改用已针对gmail.settings.basic完成验证的 OAuth 应用并重新连接。这一点同样适用于 Google Super其文档 googlesuper/public.md 明确指出通过 Google Super 创建 Gmail 过滤器同样需要gmail.settings.basic。gmail.send与mail.google.com的取舍https://www.googleapis.com/auth/gmail.send可以发送邮件但它是细粒度的敏感 Scope需要 Google 审核验证更宽泛的https://mail.google.com/拥有完整邮箱访问权限也能覆盖发送场景但其权限范围大于很多用户的实际需求。选择建议优先采用最小权限原则若你的 OAuth 应用尚未通过gmail.send的验证再考虑是否接受mail.google.com的宽泛授权。获取完整邮件正文时避免gmail.metadatahttps://www.googleapis.com/auth/gmail.metadata是受限的元数据专用 Scope只能用于获取标签、头部等元数据不能用于请求完整邮件内容。当工具需要读取完整 payload/body 时必须从 Auth Config 中移除gmail.metadata改用一个允许内容访问的 Scope如https://mail.google.com/、gmail.readonly或gmail.modify并重新连接账号以让新的 Scope 集合生效详见 faq/gmail.md。多 Google 服务共用一个连接Google Super如果同一个 Google 账号需要同时使用 Gmail、Google Calendar、Google Meet 等服务官方建议使用Google Super统一 Google Workspace 超集工具包通过一次 Google Super 连接覆盖多个服务前提是配置了所需 Scope。Google Super 拥有跨服务认证的权威指引详见 Google Super 文档。同时注意Google Super 可移除不需要的 Scope 与工具来缩小权限面但剩余的 Scope 必须仍能覆盖你实际要用的工具通过 Google Super 创建 Gmail 过滤器同样需要gmail.settings.basic用户在同意屏幕上可以取消勾选部分 Scope只要 token 交换成功 Composio 就会标记连接为 active——Auth Config 里的 Scope 只是蓝图最终权限由用户在同意屏幕上决定。寻址与发送 Gmail 邮件用me指代已认证用户在 Gmail 工具调用中me可以作为user_id使用用于指代当前已认证的 Connected Account无需再显式拼接邮箱地址。至少提供一个收件人通道GMAIL_SEND_EMAIL不再强制要求单一的必填收件人字段。to/recipient_email、cc、bcc中至少提供一个即可这让工具能灵活适配不同的邮件编排流程result composio.tools.execute( slugGMAIL_SEND_EMAIL, user_idme, arguments{ recipient_email: recipientexample.com, subject: Report attached, body: See attached., }, )托管 MCP / Tool Router 调用收件人放在嵌套arguments中通过COMPOSIO_MULTI_EXECUTE_TOOL发起托管 MCP / Tool Router 调用时收件人字段必须放在嵌套的 toolarguments对象内。除非当前 schema 显式暴露了其他形状否则建议第一位 To 收件人使用recipient_email其余 To 收件人使用extra_recipients。典型报错与排查如果连接处于 active 状态但 action 返回At least one of to (or recipient_email), cc, or bcc must be provided说明工具在进入 Gmail API 执行之前就因未收到收件人通道而失败。排查步骤用精确的嵌套recipient_email形状重试仍失败则提供全新的 request ID 以便调查。用from_email选择发件别名GMAIL_SEND_EMAIL支持通过from_email参数选择 Gmail 的send-as 别名发送别名适合多别名邮箱场景。安全地发送附件执行前先上传文件临时 S3/文件实例是短生命周期的。在 SDK 或 MCP 流程中请先调用files.upload上传文件再把返回的FileUploadable/ 已上传文件对象传给 Agent 或工具调用。仓库 FAQ 进一步补充Composio SDK 默认启用**自动上传auto-upload**功能直接传入本地文件路径或公网 URL 字符串到attachment字段即可SDK 会自动完成上传与格式转换无需手动构造{ s3key, name, mimetype }对象详见 faq/gmail.md。超时后先核实再重试GMAIL_SEND_EMAIL接受的是已上传的 Composio 文件引用而不是签名 URL 或 JSON 字符串。该 action 的底层流程为下载已上传文件 → 构建 MIME 消息 → base64-url 编码 → POST 到 Gmail。因此带附件的发送会明显慢于纯文本小邮件客户端超时并不等于发送失败。当前 Python 与 TypeScript SDK不会自动重试非幂等的工具执行。当GMAIL_SEND_EMAIL出现挂起或重复发送带附件时现象处理方式日志是快速的 400 校验错误检查attachment参数是否为包含name、mimetype、s3key的对象/列表客户端超时先查看 Composio 执行日志或 Gmail 已发送Sent文件夹再决定是否手动重试客户端版本过旧Python SDK 低于 0.16.0 或 TypeScript SDK 低于 0.14.0 时先升级再排查 SDK 层自动重试问题获取消息与标签管理减小抓取载荷在 Gmail 获取/列表类流程中按以下方式控制返回数据量支持处设置include_payloadfalse与verbosefalse极轻量场景使用only_idstrue随后按需单独获取选中消息配合max_results与 Gmail 的query过滤条件保持结果集精简。注意verbosetrue的线程结果无法自定义字段选择且可能不是最新数据。标签操作使用标签 ID 而非显示名称Gmail 标签操作以及需要 ID 的触发器标签过滤要求传入标签 IDlabelId而不是显示名称。用GMAIL_LIST_LABELS获取 ID。仓库的工具描述也印证了这一点例如GMAIL_ADD_LABEL_TO_EMAIL要求label_ids有效自定义标签 ID 可用listLabels获取GMAIL_CREATE_LABEL返回的Label_123形式的 labelId 是下游工具唯一接受的形态。修补标签颜色使用 Gmail 认可的色值修补标签颜色时使用标签 ID并以对象字段传入背景色例如{ background_color: #FFFF0000 }Gmail 只接受 Gmail API 参考文档中列出的特定标签颜色值随意传入其他色值将不被接受。配置 Gmail 新邮件触发器过滤配置 Gmail 新邮件new-message触发器时使用 Gmail 查询语法过滤匹配邮件例如label:sent OR label:category_personal该方式直接依赖查询语句而非标签 ID可以避免该触发器路径对标签 ID 的依赖。仓库中 Gmail 工具包共提供 2 个触发器见 toolkits.json邮件类触发器的轮询默认约每分钟一次如需更低延迟可考虑 Webhook 或 Google Pub/Sub 方案详见 faq/gmail.md。常见问题速查结合仓库 FAQfaq/gmail.md补充几个高频排障点App is blockedOAuth 客户端请求了 Google 未验证的 Scope移除额外 Scope或自建 OAuth 应用并提交 Scope 验证Gmail API has not been used in project使用自定义 OAuth 凭据时必须在拥有该凭据的 Google Cloud 项目中启用 Gmail API401 错误通常是访问令牌失效用户撤销授权、改密码/2FA、Workspace 管理员策略变更或 Google 每账号约 50 个刷新令牌的上限被超重新认证用户即可恢复Quota Exhausted / 限流Google 有每分钟与每日配额使用 Composio 默认 OAuth 应用会与所有用户共享配额自建 OAuth 应用可获得独立配额并建议搭配指数退避与重试。总结Composio 的 Gmail 工具包以 63 个工具与 2 个触发器覆盖了从认证、收发、附件到标签、过滤器、触发器的完整邮件自动化链路。实践中的关键原则可以概括为先建 Auth Config 再发起连接、按最小权限选择 Scope新设置工具记得传latest或走 v3.1、收件人至少提供一条通道且托管调用必须嵌套在arguments中、附件先上传再执行并在超时后先核实再重试、标签操作一律使用 ID。把握这些要点即可在 Composio 上稳定构建 Gmail 相关的 AI Agent 工作流。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考