Gmail

核心用法

Gmail技能是Maton平台提供的托管式Gmail API网关，开发者通过单一Maton API Key即可调用完整的Gmail REST API功能，无需自行处理Google OAuth 2.0的复杂授权流程。

典型调用模式：
1. 获取Maton API Key并设置环境变量
2. 在ctrl.maton.ai创建Google OAuth连接，完成浏览器授权
3. 通过gateway.maton.ai/google-mail代理端点调用任意Gmail API

支持的核心操作包括：消息列表查询（支持Gmail搜索语法如is:unread、from:、after:）、单条消息获取、邮件发送（需base64编码）、标签管理、会话线程操作、草稿创建与发送、以及垃圾桶管理。

显著优点

| 优势 | 说明 |

|------|------|

| **零OAuth运维成本** | Maton托管令牌刷新、权限续约，开发者无需维护refresh_token逻辑 |

| **原生API完整透传** | 直接代理Google官方API，功能100%对齐，无能力裁剪 |

| **多账户支持** | 通过`Maton-Connection`头可在同一API Key下切换多个Gmail账户 |

| **熟悉的技术栈** | 标准HTTP/REST接口，支持任意语言（文档提供Python、JavaScript、Bash示例） |

| **细粒度权限控制** | OAuth授权时用户可精确选择授权范围，符合Google安全模型 |

潜在缺点与局限性

• 供应商锁定风险：邮件数据流经Maton网关（gateway.maton.ai），存在单点故障和服务连续性依赖
• 速率限制：明确标注10 req/sec每账户，高并发场景需自行实现队列或降级策略
• 编码复杂度：发送邮件需手动处理base64url编码，无高层封装SDK降低开发效率
• 环境变量陷阱：文档特别提示curl管道到jq时环境变量可能无法展开，存在调试摩擦成本
• 网络依赖：所有调用必须连通Maton服务，无法离线或私有部署

适合人群

• 快速原型开发者：需在数小时内集成邮件功能，不愿投入OAuth基础设施
• 多账户管理场景：如SaaS工具需代管客户Gmail，通过connection_id隔离
• 自动化工作流构建者：结合LLM或定时任务实现邮件分类、自动回复、数据提取

常规风险

| 风险类型 | 评估 |

|---------|------|

| 凭证泄露 | Maton API Key为Bearer令牌，若泄露则攻击者可访问关联的所有Gmail账户；需严格遵循密钥管理最佳实践 |

| 权限过度申请 | 用户授权时若选择过度范围（如全账户访问），可能导致敏感邮件暴露；建议引导用户选择最小权限 |

| 中间人攻击 | 流量经Maton网关，虽使用TLS，但需信任Maton的数据处理合规性；无端到端加密选项 |

| 数据滞留 | 邮件内容在传输过程中经过Maton服务器，敏感场景需评估数据主权和隐私合规要求 |

核心用法

Gmail Skill 是 Maton 平台提供的官方 Gmail API 集成方案，采用托管式 OAuth 2.0 认证，用户无需自行处理 Google 复杂的 OAuth 流程。核心功能覆盖：

• 邮件操作：读取、发送、删除邮件，支持 Base64 编码的原始邮件格式
• 会话管理：线程（Thread）级别的对话追踪，支持完整邮件链查看
• 标签系统：读取、修改邮件标签（INBOX、STARRED、UNREAD 等），实现邮件分类自动化
• 草稿功能：创建、发送草稿，支持邮件预编辑工作流
• 高级搜索：原生支持 Gmail 查询语法（is:unread、from:、after:、has:attachment 等）

技术接入方式极简：获取 Maton API Key → 创建 OAuth 连接 → 通过 gateway.maton.ai/google-mail 代理访问完整 Gmail REST API。支持 Python、JavaScript 等主流语言，所有请求自动注入 OAuth Token。

显著优点

1. 零 OAuth 开发成本：Maton 托管完整的 Google OAuth 生命周期，包括令牌刷新、权限管理和多账户切换
2. 官方 API 完整覆盖：非封装式 SDK，而是原生 Gmail API 代理，支持 100% 的官方端点功能
3. 多连接管理：支持通过 Maton-Connection 头切换多个 Gmail 账户，适合企业多邮箱场景
4. 安全架构：API Key 环境变量注入，无硬编码凭证；TLS 1.2+ 全链路加密；符合 GDPR/CCPA 合规
5. 丰富的查询能力：原生 Gmail 搜索语法支持复杂业务场景（如「上周来自某客户的未读附件邮件」）

潜在缺点与局限性

• 依赖 Maton 平台：服务可用性绑定 Maton 网关，若 Maton 服务中断则无法使用（非 Google 直连）
• 速率限制：10 req/sec 每账户，高频场景（如批量邮件迁移）需自行限流
• Base64 编码门槛：发送邮件需手动处理 Base64url 编码的 RFC 2822 格式邮件，无高层封装 SDK
• 无实时推送：基于轮询模式，无 Gmail Push Notification 原生支持
• 地域与合规：邮件数据流经 Maton 网关，对数据本地化有严格要求的场景需评估

适合人群

• 需要快速集成 Gmail 自动化但不想维护 OAuth 的开发者
• 多账户邮件管理场景（客服系统、营销自动化、个人助理工作流）
• 已有 Gmail API 经验，希望简化认证层的团队
• 构建邮件归档、智能分类、自动回复等 Workflow 的用户

常规风险

• 凭证泄露风险：MATON_API_KEY 泄露可能导致邮件数据被访问，需严格环境变量管理
• OAuth 授权范围：过度授权风险，建议定期在 Google 账户设置中审查已授权应用
• API 限流触发：高频调用可能导致 429 错误，需实现指数退避重试
• 邮件内容编码：Base64 处理不当可能导致邮件格式错误或乱码
• 数据隐私：邮件元数据流经第三方网关，敏感内容建议额外加密或评估本地部署方案