Gmail API 集成：阅读、发送与管理邮件 - Openclaw Skills

下载入口:https://github.com/openclaw/skills/tree/main/skills/byungkyu/gmail

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install gmail

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 gmail。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

什么是 Gmail？

此技能提供了一个高性能接口，通过托管 OAuth 网关与 Gmail API 进行交互。通过利用 Openclaw Skills，开发人员可以绕过处理个人 OAuth 流程和令牌刷新的复杂性。相反，Maton 网关直接代理向 Google 基础设施发出的请求，并自动注入必要的凭据。

这种设置允许 AI 代理以最少的样板代码执行复杂的电子邮件操作，例如搜索未读邮件、删除特定会话以及发送 base64 编码的电子邮件。它旨在成为自主代理与全球最常用通信平台之一之间对开发人员友好的桥梁。

Gmail 应用场景

• 自动回复通过电子邮件收到的常见客户咨询。
• 构建 AI 驱动的收件箱整理器，对收到的邮件进行标记和分类。
• 将电子邮件会话与内部 CRM 或任务管理系统同步。
• 通过专用 Gmail 帐户生成并发送自动化报告或通知。
• 使用 Openclaw Skills 搜索功能，通过查询特定发件人或日期范围来研究历史通信。

Gmail 工作原理

1. 用户通过 Maton 平台进行身份验证以获取专门的 API 密钥。
2. 通过托管在 ctrl.maton.ai 的托管 OAuth 流程，在 Openclaw Skills 环境与用户的 Google 帐户之间建立连接。
3. 请求发送到 Maton 网关 URL，该 URL 作为原生 Gmail API 端点的安全代理。
4. 网关使用提供的 API 密钥或特定的连接 ID 标头识别正确的 OAuth 令牌。
5. Gmail API 处理请求（例如列出邮件或发送草稿），并将数据通过网关返回给代理。

Gmail 配置指南

要开始使用此技能，请确保您已准备好 Maton API 密钥并在环境中进行了设置。

export MATON_API_KEY="YOUR_API_KEY"

通过创建连接对象初始化与 Gmail 帐户的连接：

# 为 google-mail 创建新连接
curl -X POST https://ctrl.maton.ai/connections r
  -H "Authorization: Bearer $MATON_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{"app": "google-mail"}'

在浏览器中打开响应中返回的 URL，以通过 Google OAuth 授权访问。状态变为 ACTIVE 后，您就可以开始在 Openclaw Skills 框架内向 Gmail 网关发送请求了。

Gmail 数据架构与分类体系

此技能与标准 Gmail 对象交互。以下是数据的组织方式：

对象	关键属性	用途
邮件	id, threadId, labelIds, snippet	代表单封电子邮件。
会话	id, historyId, messages	代表一组相关的邮件。
标签	id, name, type	元数据标记，如 INBOX、UNREAD 或自定义标签。
草稿	id, message	已创建但尚未发送的邮件。
个人资料	emailAddress, messagesTotal	高层级帐户统计信息。

name: gmail
description: |
  Gmail API integration with managed OAuth. Read, send, and manage emails, threads, labels, and drafts. Use this skill when users want to interact with Gmail. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: ??
    requires:
      env:
        - MATON_API_KEY

Gmail

Access the Gmail API with managed OAuth authentication. Read, send, and manage emails, threads, labels, and drafts.

Quick Start

# List messages
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

Base URL

https://gateway.maton.ai/google-mail/{native-api-path}

Replace {native-api-path} with the actual Gmail API endpoint path. The gateway proxies requests to gmail.googleapis.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Google OAuth connections at https://ctrl.maton.ai.

List Connections

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

Create Connection

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

Get Connection

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

Response:

{
  "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": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

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

Specifying Connection

If you have multiple Gmail connections, specify which one to use with the Maton-Connection header:

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

If omitted, the gateway uses the default (oldest) active connection.

API Reference

List Messages

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

With query filter:

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

Get Message

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

With metadata only:

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

Send Message

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

{
  "raw": "BASE64_ENCODED_EMAIL"
}

List Labels

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

List Threads

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

Get Thread

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

Modify Message Labels

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

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

Trash Message

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

Create Draft

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

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

Send Draft

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

{
  "id": "{draftId}"
}

Get Profile

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

Query Operators

Use in the q parameter:

• is:unread - Unread messages
• is:starred - Starred messages
• from:[email protected] - From specific sender
• to:[email protected] - To specific recipient
• subject:keyword - Subject contains keyword
• after:2024/01/01 - After date
• before:2024/12/31 - Before date
• has:attachment - Has attachments

Code Examples

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'}
)

Notes

• Use me as userId for the authenticated user
• Message body is base64url encoded in the raw field
• Common labels: INBOX, SENT, DRAFT, STARRED, UNREAD, TRASH
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.

Error Handling

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

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

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with google-mail. For example:

• Correct: https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
• Incorrect: https://gateway.maton.ai/gmail/v1/users/me/messages

Resources

• Gmail API Overview
• List Messages
• Get Message
• Send Message
• List Threads
• List Labels
• Create Draft
• Maton Community
• Maton Support