gmail

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gmail

Interact with Gmail for email management, search, and organization.

与Gmail交互，实现邮件管理、搜索和整理。

Installation

安装

Install Python dependencies:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Download the skill from Releases or use directly from this repository.

安装Python依赖:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

下载技能：从Releases下载，或直接使用本仓库中的内容。

Setup Verification

设置验证

After installation, verify the skill is properly configured:

bash

python scripts/gmail.py check

This will check:

Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
Authentication configuration
Connectivity to Gmail API

If anything is missing, the check command will provide setup instructions.

安装完成后，验证技能是否配置正确：

bash

python scripts/gmail.py check

此命令会检查：

Python依赖（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
认证配置
与Gmail API的连接性

如果有缺失，检查命令会提供设置说明。

Authentication

认证

Gmail uses OAuth 2.0 for authentication. For complete setup instructions, see:

GCP Project Setup Guide - Create project, enable Gmail API
Google OAuth Setup Guide - Configure credentials

Gmail使用OAuth 2.0进行认证。完整设置说明请参考：

GCP项目设置指南 - 创建项目，启用Gmail API
Google OAuth设置指南 - 配置凭证

Quick Start

快速开始

Create

~/.config/agent-skills/google.yaml

yaml

oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret

Run
```
python scripts/gmail.py check
```
to trigger OAuth flow and verify setup.

创建

~/.config/agent-skills/google.yaml

文件:

yaml

oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret

运行
```
python scripts/gmail.py check
```
触发OAuth流程并验证设置。

OAuth Scopes

OAuth权限范围

The skill requests granular scopes for different operations:

Scope	Permission	Used For
`gmail.readonly`	Read messages, labels, settings	Listing and reading messages
`gmail.send`	Send emails	Sending messages and drafts
`gmail.modify`	Modify labels and metadata	Managing labels on messages
`gmail.labels`	Manage labels	Creating and listing labels

该技能针对不同操作请求细分的权限范围：

权限范围	权限说明	用途
`gmail.readonly`	读取邮件、标签、设置	列出和读取邮件
`gmail.send`	发送邮件	发送邮件和草稿
`gmail.modify`	修改标签和元数据	管理邮件标签
`gmail.labels`	管理标签	创建和列出标签

Scope Errors

权限范围错误

If you encounter "insufficient scope" errors, revoke your token and re-authenticate:

Revoke at https://myaccount.google.com/permissions

Clear token:

keyring del agent-skills gmail-token-json

Re-run:
```
python scripts/gmail.py check
```

如果遇到“权限范围不足”错误，请撤销令牌并重新认证：

在https://myaccount.google.com/permissions撤销权限

清除令牌：

keyring del agent-skills gmail-token-json

重新运行：
```
python scripts/gmail.py check
```

Commands

命令

check

Verify configuration and connectivity.

bash

python scripts/gmail.py check

This validates:

Python dependencies are installed
Authentication is configured
Can connect to Gmail API
Displays your email address and mailbox statistics

验证配置和连接性。

bash

python scripts/gmail.py check

此命令会验证：

Python依赖已安装
认证已配置
可连接到Gmail API
显示你的邮箱地址和邮箱统计信息

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

bash

python scripts/gmail.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Credentials are saved to

~/.config/agent-skills/gmail.yaml

存储OAuth 2.0客户端凭证，用于自定义OAuth流程。

bash

python scripts/gmail.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

凭证会保存到

~/.config/agent-skills/gmail.yaml

。

messages list

List messages matching a query.

bash

undefined

列出符合查询条件的邮件。

bash

undefined

List recent messages

列出最近的邮件

python scripts/gmail.py messages list

Search for unread messages

搜索未读邮件

python scripts/gmail.py messages list --query "is:unread"

Search with max results

搜索并设置最大结果数

python scripts/gmail.py messages list --query "from:user@example.com" --max-results 20

Output as JSON

以JSON格式输出

python scripts/gmail.py messages list --query "subject:meeting" --json


**Arguments:**
- `--query`: Gmail search query (optional)
- `--max-results`: Maximum number of results (default: 10)
- `--json`: Output as JSON

**Search Query Examples:**

For complete Gmail search syntax, see [gmail-queries.md](references/gmail-queries.md).

Common queries:
- `is:unread` - Unread messages
- `from:user@example.com` - Messages from sender
- `subject:meeting` - Messages with subject keyword
- `has:attachment` - Messages with attachments
- `after:2024/01/01` - Messages after date
- `label:important` - Messages with label

python scripts/gmail.py messages list --query "subject:meeting" --json


**参数:**
- `--query`: Gmail搜索查询语句（可选）
- `--max-results`: 最大结果数（默认：10）
- `--json`: 以JSON格式输出

**搜索查询示例:**

完整的Gmail搜索语法请参考[gmail-queries.md](references/gmail-queries.md)。

常用查询语句：
- `is:unread` - 未读邮件
- `from:user@example.com` - 指定发件人的邮件
- `subject:meeting` - 主题包含关键词的邮件
- `has:attachment` - 带附件的邮件
- `after:2024/01/01` - 指定日期之后的邮件
- `label:important` - 带指定标签的邮件

messages get

Get a message by ID.

bash

undefined

通过ID获取单封邮件。

bash

undefined

Get full message

获取完整邮件

python scripts/gmail.py messages get MESSAGE_ID

Get minimal format

获取精简格式邮件

python scripts/gmail.py messages get MESSAGE_ID --format minimal

Output as JSON

以JSON格式输出

python scripts/gmail.py messages get MESSAGE_ID --json


**Arguments:**
- `message_id`: The message ID (required)
- `--format`: Message format (full, minimal, raw, metadata) - default: full
- `--json`: Output as JSON

python scripts/gmail.py messages get MESSAGE_ID --json


**参数:**
- `message_id`: 邮件ID（必填）
- `--format`: 邮件格式（full、minimal、raw、metadata）- 默认：full
- `--json`: 以JSON格式输出

send

Send an email message.

bash

undefined

发送邮件。

bash

undefined

Send simple email

发送简单邮件

python scripts/gmail.py send
--to recipient@example.com
--subject "Hello"
--body "This is the message body"

Send with CC and BCC

发送带抄送给密送的邮件

python scripts/gmail.py send
--to recipient@example.com
--subject "Team Update"
--body "Here's the update..."
--cc team@example.com
--bcc boss@example.com

Output as JSON

以JSON格式输出

python scripts/gmail.py send
--to user@example.com
--subject "Test"
--body "Test message"
--json


**Arguments:**
- `--to`: Recipient email address (required)
- `--subject`: Email subject (required)
- `--body`: Email body text (required)
- `--cc`: CC recipients (comma-separated)
- `--bcc`: BCC recipients (comma-separated)
- `--json`: Output as JSON

python scripts/gmail.py send
--to user@example.com
--subject "Test"
--body "Test message"
--json


**参数:**
- `--to`: 收件人邮箱地址（必填）
- `--subject`: 邮件主题（必填）
- `--body`: 邮件正文（必填）
- `--cc`: 抄送人（逗号分隔）
- `--bcc`: 密送人（逗号分隔）
- `--json`: 以JSON格式输出

drafts list

List draft messages.

bash

undefined

列出草稿邮件。

bash

undefined

List drafts

列出草稿

python scripts/gmail.py drafts list

List with custom max results

自定义最大结果数列出草稿

python scripts/gmail.py drafts list --max-results 20

Output as JSON

以JSON格式输出

python scripts/gmail.py drafts list --json


**Arguments:**
- `--max-results`: Maximum number of results (default: 10)
- `--json`: Output as JSON

python scripts/gmail.py drafts list --json


**参数:**
- `--max-results`: 最大结果数（默认：10）
- `--json`: 以JSON格式输出

drafts create

Create a draft email.

bash

undefined

创建草稿邮件。

bash

undefined

Create draft

创建草稿

python scripts/gmail.py drafts create
--to recipient@example.com
--subject "Draft Subject"
--body "This is a draft message"

Create draft with CC

创建带抄送的草稿

python scripts/gmail.py drafts create
--to recipient@example.com
--subject "Meeting Notes"
--body "Notes from today's meeting..."
--cc team@example.com

Output as JSON

以JSON格式输出

python scripts/gmail.py drafts create
--to user@example.com
--subject "Test Draft"
--body "Draft body"
--json


**Arguments:**
- `--to`: Recipient email address (required)
- `--subject`: Email subject (required)
- `--body`: Email body text (required)
- `--cc`: CC recipients (comma-separated)
- `--bcc`: BCC recipients (comma-separated)
- `--json`: Output as JSON

python scripts/gmail.py drafts create
--to user@example.com
--subject "Test Draft"
--body "Draft body"
--json


**参数:**
- `--to`: 收件人邮箱地址（必填）
- `--subject`: 邮件主题（必填）
- `--body`: 邮件正文（必填）
- `--cc`: 抄送人（逗号分隔）
- `--bcc`: 密送人（逗号分隔）
- `--json`: 以JSON格式输出

drafts send

Send a draft message.

bash

undefined

发送草稿邮件。

bash

undefined

Send draft by ID

通过ID发送草稿

python scripts/gmail.py drafts send DRAFT_ID

Output as JSON

以JSON格式输出

python scripts/gmail.py drafts send DRAFT_ID --json


**Arguments:**
- `draft_id`: The draft ID to send (required)
- `--json`: Output as JSON

python scripts/gmail.py drafts send DRAFT_ID --json


**参数:**
- `draft_id`: 要发送的草稿ID（必填）
- `--json`: 以JSON格式输出

labels list

List all Gmail labels.

bash

undefined

列出所有Gmail标签。

bash

undefined

List labels

列出标签

python scripts/gmail.py labels list

Output as JSON

以JSON格式输出

python scripts/gmail.py labels list --json


**Arguments:**
- `--json`: Output as JSON

python scripts/gmail.py labels list --json


**参数:**
- `--json`: 以JSON格式输出

labels create

Create a new label.

bash

undefined

创建新标签。

bash

undefined

Create label

创建标签

python scripts/gmail.py labels create "Project X"

Output as JSON

以JSON格式输出

python scripts/gmail.py labels create "Important" --json


**Arguments:**
- `name`: Label name (required)
- `--json`: Output as JSON

python scripts/gmail.py labels create "Important" --json


**参数:**
- `name`: 标签名称（必填）
- `--json`: 以JSON格式输出

Examples

示例

Verify Setup

验证设置

bash

python scripts/gmail.py check

bash

python scripts/gmail.py check

Find unread emails

查找未读邮件

bash

python scripts/gmail.py messages list --query "is:unread"

bash

python scripts/gmail.py messages list --query "is:unread"

Search for emails from a sender

搜索指定发件人的邮件

bash

python scripts/gmail.py messages list --query "from:boss@example.com" --max-results 5

bash

python scripts/gmail.py messages list --query "from:boss@example.com" --max-results 5

Send a quick email

快速发送邮件

bash

python scripts/gmail.py send \
  --to colleague@example.com \
  --subject "Quick Question" \
  --body "Do you have time for a meeting tomorrow?"

bash

python scripts/gmail.py send \
  --to colleague@example.com \
  --subject "Quick Question" \
  --body "Do you have time for a meeting tomorrow?"

Create and send a draft

创建并发送草稿

bash

undefined

bash

undefined

Create draft

创建草稿

python scripts/gmail.py drafts create
--to team@example.com
--subject "Weekly Update"
--body "Here's this week's update..."

List drafts to get the ID

列出草稿获取ID

python scripts/gmail.py drafts list

Send the draft

发送草稿

python scripts/gmail.py drafts send DRAFT_ID

undefined

python scripts/gmail.py drafts send DRAFT_ID

undefined

Organize with labels

使用标签整理邮件

bash

undefined

bash

undefined

Create a label

创建标签

python scripts/gmail.py labels create "Project Alpha"

List all labels

列出所有标签

python scripts/gmail.py labels list

undefined

python scripts/gmail.py labels list

undefined

Advanced searches

高级搜索

bash

undefined

bash

undefined

Find emails with attachments from last week

查找上周带附件的邮件

python scripts/gmail.py messages list --query "has:attachment newer_than:7d"

Find important emails from specific sender

查找指定发件人的重要邮件

python scripts/gmail.py messages list --query "from:ceo@example.com is:important"

Find emails in a conversation

查找同一对话中的邮件

python scripts/gmail.py messages list --query "subject:project-alpha"

undefined

python scripts/gmail.py messages list --query "subject:project-alpha"

undefined

Gmail Search Query Syntax

Gmail搜索查询语法

Common search operators:

Operator	Description	Example
`from:`	Sender email	`from:user@example.com`
`to:`	Recipient email	`to:user@example.com`
`subject:`	Subject contains	`subject:meeting`
`label:`	Has label	`label:important`
`has:attachment`	Has attachment	`has:attachment`
`is:unread`	Unread messages	`is:unread`
`is:starred`	Starred messages	`is:starred`
`after:`	After date	`after:2024/01/01`
`before:`	Before date	`before:2024/12/31`
`newer_than:`	Newer than period	`newer_than:7d`
`older_than:`	Older than period	`older_than:30d`

Combine operators with spaces (implicit AND) or

OR

bash

undefined

常用搜索操作符：

操作符	说明	示例
`from:`	发件人邮箱	`from:user@example.com`
`to:`	收件人邮箱	`to:user@example.com`
`subject:`	主题包含关键词	`subject:meeting`
`label:`	带指定标签	`label:important`
`has:attachment`	带附件	`has:attachment`
`is:unread`	未读邮件	`is:unread`
`is:starred`	已标星邮件	`is:starred`
`after:`	指定日期之后	`after:2024/01/01`
`before:`	指定日期之前	`before:2024/12/31`
`newer_than:`	指定时间范围内的新邮件	`newer_than:7d`
`older_than:`	指定时间范围内的旧邮件	`older_than:30d`

使用空格（隐式逻辑与）或

OR

组合操作符：

bash

undefined

AND (implicit)

逻辑与（隐式）

from:user@example.com subject:meeting

OR

逻辑或

from:user@example.com OR from:other@example.com

Grouping with parentheses

括号分组

(from:user@example.com OR from:other@example.com) subject:meeting


For the complete reference, see [gmail-queries.md](references/gmail-queries.md).

(from:user@example.com OR from:other@example.com) subject:meeting


完整参考请见[gmail-queries.md](references/gmail-queries.md)。

Troubleshooting

故障排除

Check command fails

检查命令执行失败

Run

python scripts/gmail.py check

to diagnose issues. It will provide specific error messages and setup instructions.

运行

python scripts/gmail.py check

诊断问题，它会提供具体错误信息和设置说明。

Authentication failed

认证失败

Verify your OAuth client ID and client secret are correct in
```
~/.config/agent-skills/google.yaml
```

Token expired or corrupted - clear and re-authenticate:

bash

keyring del agent-skills gmail-token-json
python scripts/gmail.py check

验证
```
~/.config/agent-skills/google.yaml
```
中的OAuth客户端ID和密钥是否正确

令牌过期或损坏 - 清除并重新认证：

bash

keyring del agent-skills gmail-token-json
python scripts/gmail.py check

Permission denied

权限被拒绝

Your OAuth token may not have the necessary scopes. Revoke access at https://myaccount.google.com/permissions, clear your token, and re-authenticate.

你的OAuth令牌可能缺少必要的权限范围。在https://myaccount.google.com/permissions撤销权限，清除令牌后重新认证。

Import errors

导入错误

Ensure dependencies are installed:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

确保依赖已安装：

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Rate limiting

速率限制

Gmail API has quota limits. If you hit rate limits, wait a few minutes before retrying. For high-volume usage, consider requesting quota increases in the Google Cloud Console.

Gmail API有配额限制。如果触发速率限制，请等待几分钟后重试。对于高用量场景，可在Google Cloud Console申请提高配额。

API Scopes

API权限范围

This skill requests the following OAuth scopes:

https://www.googleapis.com/auth/gmail.readonly

- Read email messages and settings

https://www.googleapis.com/auth/gmail.send

- Send email messages

https://www.googleapis.com/auth/gmail.modify

- Modify labels and message metadata

https://www.googleapis.com/auth/gmail.labels

- Manage labels

These scopes provide full email management capabilities while following the principle of least privilege.

本技能请求以下OAuth权限范围：

https://www.googleapis.com/auth/gmail.readonly

- 读取邮件和设置

https://www.googleapis.com/auth/gmail.send

- 发送邮件

https://www.googleapis.com/auth/gmail.modify

- 修改标签和邮件元数据

https://www.googleapis.com/auth/gmail.labels

- 管理标签

这些权限范围在遵循最小权限原则的同时，提供完整的邮件管理能力。

Security Notes

安全说明

OAuth tokens are stored securely in your system keyring
Client secrets are stored in
```
~/.config/agent-skills/gmail.yaml
```
with file permissions 600
No passwords are stored - only OAuth tokens
Tokens refresh automatically when using the skill
Browser-based consent ensures you approve all requested permissions

Always review OAuth consent screens before granting access to your Gmail account.

OAuth令牌安全存储在系统密钥环中
客户端密钥存储在
```
~/.config/agent-skills/gmail.yaml
```
，文件权限为600
不存储密码 - 仅存储OAuth令牌
令牌会自动刷新 - 使用技能时自动完成
基于浏览器的授权 - 确保你批准所有请求的权限

在授予Gmail账户访问权限前，请务必仔细查看OAuth授权界面。