---

name: gmail description: | Gmail API 集成，附带托管 OAuth 功能。可读取、发送和管理邮件、线程、标签和草稿。当用户需要与 Gmail 交互时，使用此技能。对于其他第三方应用，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。 compatibility: 需要网络访问权限和有效的 Maton API 密钥 metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 requires: env: - MATON_API_KEY

Gmail

通过托管的 OAuth 认证访问 Gmail API。读取、发送和管理邮件、线程、标签和草稿。

快速开始

# 列出消息
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://gateway.maton.ai/google-mail/{原生-api-路径}

将 {原生-api-路径} 替换为实际的 Gmail API 端点路径。网关将请求代理到 gmail.googleapis.com 并自动注入您的 OAuth 令牌。

认证

所有请求都要求在 Authorization 头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

**环境变量：**将您的 API 密钥设置为 MATON_API_KEY：

export MATON_API_KEY="您的_API_密钥"

获取您的 API 密钥

1. 登录或在 maton.ai 创建一个账户
2. 前往 maton.ai/settings
3. 复制您的 API 密钥

连接管理

请在 https://ctrl.maton.ai 管理您的 Google OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-mail&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-mail'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-mail",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 Gmail 连接，可以使用 Maton-Connection 头指定使用哪个连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果未指定，网关将使用默认（最早）的活跃连接。

API 参考文档

获取邮件列表

GET /google-mail/gmail/v1/users/me/messages?maxResults=10

带查询过滤器:

GET /google-mail/gmail/v1/users/me/messages?q=is:unread&maxResults=10

获取单封邮件

GET /google-mail/gmail/v1/users/me/messages/{messageId}

仅获取元数据:

GET /google-mail/gmail/v1/users/me/messages/{messageId}?format=metadata&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=Date

发送邮件

POST /google-mail/gmail/v1/users/me/messages/send
Content-Type: application/json

{
  "raw": "BASE64_ENCODED_EMAIL"
}

获取标签列表

GET /google-mail/gmail/v1/users/me/labels

获取会话列表

GET /google-mail/gmail/v1/users/me/threads?maxResults=10

获取单条会话

GET /google-mail/gmail/v1/users/me/threads/{threadId}

修改邮件标签

POST /google-mail/gmail/v1/users/me/messages/{messageId}/modify
Content-Type: application/json

{
  "addLabelIds": ["STARRED"],
  "removeLabelIds": ["UNREAD"]
}

删除邮件到废纸篓

POST /google-mail/gmail/v1/users/me/messages/{messageId}/trash

创建草稿

POST /google-mail/gmail/v1/users/me/drafts
Content-Type: application/json

{
  "message": {
    "raw": "BASE64URL_ENCODED_EMAIL"
  }
}

发送草稿

POST /google-mail/gmail/v1/users/me/drafts/send
Content-Type: application/json

{
  "id": "{draftId}"
}

获取用户资料

GET /google-mail/gmail/v1/users/me/profile

查询运算符

可在 q 参数中使用:

• is:unread - 未读邮件
• is:starred - 加星邮件
• from:email@example.com - 指定发件人
• to:email@example.com - 指定收件人
• subject:keyword - 主题包含关键词
• after:2024/01/01 - 指定日期之后
• before:2024/12/31 - 指定日期之前
• has:attachment - 包含附件

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'maxResults': 10, 'q': 'is:unread'}
)

注意事项

• 使用 me 作为已认证用户的 userId
• 邮件正文以 base64url 编码形式存储在 raw 字段
• 常用标签: INBOX, SENT, DRAFT, STARRED, UNREAD, TRASH
• 重要提示: 使用 curl 命令时，若 URL 包含方括号（如 fields[], sort[], records[]），需添加 -g 参数禁用通配符解析
• 重要提示: 当通过管道将 curl 输出传递给 jq 或其他命令时，某些 shell 环境中可能无法正确展开环境变量（如 $MATON_API_KEY）。管道操作时可能出现"Invalid API key"错误。

错误处理

故障排查：API 密钥问题

1. 检查是否设置了 MATON_API_KEY 环境变量：

echo $MATON_API_KEY

1. 通过列出连接验证 API 密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排查：无效应用名称

1. 确保您的 URL 路径以 google-mail 开头，例如：

• 正确示例：https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
• 错误示例：https://gateway.maton.ai/gmail/v1/users/me/messages

相关资源

• Gmail API 概述
• 列出邮件
• 获取邮件
• 发送邮件
• 列出会话
• 列出标签
• 创建草稿
• Maton 社区
• Maton 技术支持