Gmail API 技能：Python 自动化邮件管理、搜索和发送指南

gmail by odyssey4me/agent-skills

147 周安装量

2 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/odyssey4me/agent-skills --skill gmail

自动化生产力 API

🇨🇳中文介绍

Gmail

与 Gmail 交互，进行邮件管理、搜索和组织。

安装

依赖项 : pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

设置验证

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

$SKILL_DIR/scripts/gmail.py check

这将检查：

Python 依赖项 (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
身份验证配置
与 Gmail API 的连接性

如果缺少任何内容，检查命令将提供设置说明。

身份验证

Gmail 使用 OAuth 2.0 进行身份验证。完整的设置说明，请参阅：

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

快速开始

创建 ~/.config/agent-skills/google.yaml：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

867,400 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

228,700 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

157,400 周安装

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

运行 $SKILL_DIR/scripts/gmail.py check 以触发 OAuth 流程并验证设置。

遇到作用域或身份验证错误时，请参阅 OAuth 故障排除指南。

有关每个命令的读/写分类，请参阅 permissions.md。

验证配置和连接性。

$SKILL_DIR/scripts/gmail.py check

Python 依赖项是否已安装
身份验证是否已配置
是否可以连接到 Gmail API
显示您的电子邮件地址和邮箱统计信息

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

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

凭据将保存到 ~/.config/agent-skills/gmail.yaml。

清除存储的 OAuth 令牌。下一个需要身份验证的命令将自动触发重新身份验证。

$SKILL_DIR/scripts/gmail.py auth reset

当您遇到作用域或身份验证错误时使用此命令。

显示当前的 OAuth 令牌信息，无需进行 API 调用。

$SKILL_DIR/scripts/gmail.py auth status

显示：是否存储了令牌、授予的作用域、刷新令牌是否存在、令牌过期时间以及客户端 ID。

列出匹配查询条件的邮件。

# 列出最近的邮件
$SKILL_DIR/scripts/gmail.py messages list

# 搜索未读邮件
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

# 搜索并限制最大结果数
$SKILL_DIR/scripts/gmail.py messages list --query "from:user@example.com" --max-results 20

--query: Gmail 搜索查询（可选）
--max-results: 最大结果数（默认值：10）

搜索查询示例：

完整的 Gmail 搜索语法，请参阅 gmail-queries.md。

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

通过 ID 获取邮件。

# 获取完整邮件
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID

# 获取精简格式
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID --format minimal

message_id: 邮件 ID（必需）
--format: 邮件格式 (full, minimal, raw, metadata) - 默认值：full

发送电子邮件。

# 发送简单邮件
$SKILL_DIR/scripts/gmail.py send \
  --to recipient@example.com \
  --subject "Hello" \
  --body "This is the message body"

# 发送带抄送和密送的邮件
$SKILL_DIR/scripts/gmail.py send \
  --to recipient@example.com \
  --subject "Team Update" \
  --body "Here's the update..." \
  --cc team@example.com \
  --bcc boss@example.com

--to: 收件人电子邮件地址（必需）
--subject: 邮件主题（必需）
--body: 邮件正文文本（必需）
--cc: 抄送收件人（逗号分隔）
--bcc: 密送收件人（逗号分隔）

列出草稿邮件。

# 列出草稿
$SKILL_DIR/scripts/gmail.py drafts list

# 列出并自定义最大结果数
$SKILL_DIR/scripts/gmail.py drafts list --max-results 20

--max-results: 最大结果数（默认值：10）

创建草稿邮件。

# 创建草稿
$SKILL_DIR/scripts/gmail.py drafts create \
  --to recipient@example.com \
  --subject "Draft Subject" \
  --body "This is a draft message"

# 创建带抄送的草稿
$SKILL_DIR/scripts/gmail.py drafts create \
  --to recipient@example.com \
  --subject "Meeting Notes" \
  --body "Notes from today's meeting..." \
  --cc team@example.com

--to: 收件人电子邮件地址（必需）
--subject: 邮件主题（必需）
--body: 邮件正文文本（必需）
--cc: 抄送收件人（逗号分隔）
--bcc: 密送收件人（逗号分隔）

发送草稿邮件。

# 通过 ID 发送草稿
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

draft_id: 要发送的草稿 ID（必需）

列出所有 Gmail 标签。

# 列出标签
$SKILL_DIR/scripts/gmail.py labels list

# 创建标签
$SKILL_DIR/scripts/gmail.py labels create "Project X"

name: 标签名称（必需）

$SKILL_DIR/scripts/gmail.py check

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

搜索来自特定发件人的邮件

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

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

创建并发送草稿

# 创建草稿
$SKILL_DIR/scripts/gmail.py drafts create \
  --to team@example.com \
  --subject "Weekly Update" \
  --body "Here's this week's update..."

# 列出草稿以获取 ID
$SKILL_DIR/scripts/gmail.py drafts list

# 发送草稿
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

使用标签进行组织

# 创建标签
$SKILL_DIR/scripts/gmail.py labels create "Project Alpha"

# 列出所有标签
$SKILL_DIR/scripts/gmail.py labels list

# 查找上周带有附件的邮件
$SKILL_DIR/scripts/gmail.py messages list --query "has:attachment newer_than:7d"

# 查找来自特定发件人的重要邮件
$SKILL_DIR/scripts/gmail.py messages list --query "from:ceo@example.com is:important"

# 查找会话中的邮件
$SKILL_DIR/scripts/gmail.py messages list --query "subject:project-alpha"

Gmail 搜索查询语法

常用搜索运算符：

运算符	描述	示例
`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`

使用空格（隐式 AND）或 OR 组合运算符：

# AND (隐式)
from:user@example.com subject:meeting

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

# 使用括号分组
(from:user@example.com OR from:other@example.com) subject:meeting

完整参考，请参阅 gmail-queries.md。

身份验证和作用域错误不可重试。 如果命令因身份验证错误、作用域不足错误或权限被拒绝错误（退出代码 1）而失败，请停止并通知用户。不要重试或尝试自主修复问题——这些错误需要用户交互（基于浏览器的 OAuth 同意）。请引导用户查看 OAuth 故障排除指南。

可重试的错误：速率限制（HTTP 429）和临时服务器错误（HTTP 5xx）可能在短暂等待后重试成功。所有其他错误都应报告给用户。

此技能需要进行 API 调用，需要结构化输入/输出。建议使用标准能力模型。

🇺🇸English

Gmail

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

Installation

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

Setup Verification

After installation, verify the skill is properly configured:

$SKILL_DIR/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.

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

Quick Start

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

oauth_client: client_id: your-client-id.apps.googleusercontent.com client_secret: your-client-secret
Run $SKILL_DIR/scripts/gmail.py check to trigger OAuth flow and verify setup.

On scope or authentication errors, see the OAuth troubleshooting guide.

Commands

See permissions.md for read/write classification of each command.

check

Verify configuration and connectivity.

$SKILL_DIR/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

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

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

Credentials are saved to ~/.config/agent-skills/gmail.yaml.

auth reset

Clear stored OAuth token. The next command that needs authentication will trigger re-authentication automatically.

$SKILL_DIR/scripts/gmail.py auth reset

Use this when you encounter scope or authentication errors.

auth status

Show current OAuth token information without making API calls.

$SKILL_DIR/scripts/gmail.py auth status

Displays: whether a token is stored, granted scopes, refresh token presence, token expiry, and client ID.

messages list

List messages matching a query.

# List recent messages
$SKILL_DIR/scripts/gmail.py messages list

# Search for unread messages
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

# Search with max results
$SKILL_DIR/scripts/gmail.py messages list --query "from:user@example.com" --max-results 20

Arguments:

--query: Gmail search query (optional)
--max-results: Maximum number of results (default: 10)

Search Query Examples:

For complete Gmail search syntax, see 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

messages get

Get a message by ID.

# Get full message
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID

# Get minimal format
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID --format minimal

Arguments:

message_id: The message ID (required)
--format: Message format (full, minimal, raw, metadata) - default: full

send

Send an email message.

# Send simple email
$SKILL_DIR/scripts/gmail.py send \
  --to recipient@example.com \
  --subject "Hello" \
  --body "This is the message body"

# Send with CC and BCC
$SKILL_DIR/scripts/gmail.py send \
  --to recipient@example.com \
  --subject "Team Update" \
  --body "Here's the update..." \
  --cc team@example.com \
  --bcc boss@example.com

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)

drafts list

List draft messages.

# List drafts
$SKILL_DIR/scripts/gmail.py drafts list

# List with custom max results
$SKILL_DIR/scripts/gmail.py drafts list --max-results 20

Arguments:

--max-results: Maximum number of results (default: 10)

drafts create

Create a draft email.

# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
  --to recipient@example.com \
  --subject "Draft Subject" \
  --body "This is a draft message"

# Create draft with CC
$SKILL_DIR/scripts/gmail.py drafts create \
  --to recipient@example.com \
  --subject "Meeting Notes" \
  --body "Notes from today's meeting..." \
  --cc team@example.com

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)

drafts send

Send a draft message.

# Send draft by ID
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

Arguments:

draft_id: The draft ID to send (required)

labels list

List all Gmail labels.

# List labels
$SKILL_DIR/scripts/gmail.py labels list

labels create

Create a new label.

# Create label
$SKILL_DIR/scripts/gmail.py labels create "Project X"

Arguments:

name: Label name (required)

Examples

Verify Setup

$SKILL_DIR/scripts/gmail.py check

Find unread emails

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

Search for emails from a sender

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

Send a quick email

$SKILL_DIR/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

# Create draft
$SKILL_DIR/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
$SKILL_DIR/scripts/gmail.py drafts list

# Send the draft
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

Organize with labels

# Create a label
$SKILL_DIR/scripts/gmail.py labels create "Project Alpha"

# List all labels
$SKILL_DIR/scripts/gmail.py labels list

Advanced searches

# Find emails with attachments from last week
$SKILL_DIR/scripts/gmail.py messages list --query "has:attachment newer_than:7d"

# Find important emails from specific sender
$SKILL_DIR/scripts/gmail.py messages list --query "from:ceo@example.com is:important"

# Find emails in a conversation
$SKILL_DIR/scripts/gmail.py messages list --query "subject:project-alpha"

Gmail Search Query Syntax

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:`

Combine operators with spaces (implicit AND) or OR:

# 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.

Error Handling

Authentication and scope errors are not retryable. If a command fails with an authentication error, insufficient scope error, or permission denied error (exit code 1), stop and inform the user. Do not retry or attempt to fix the issue autonomously — these errors require user interaction (browser-based OAuth consent). Point the user to the OAuth troubleshooting guide.

Retryable errors : Rate limiting (HTTP 429) and temporary server errors (HTTP 5xx) may succeed on retry after a brief wait. All other errors should be reported to the user.

Model Guidance

This skill makes API calls requiring structured input/output. A standard-capability model is recommended.

Weekly Installs

133

Repository

odyssey4me/agent-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

opencode120

gemini-cli116

codex114

cursor113

github-copilot106

amp98

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

129,699 周安装

Gmail API 技能：Python 自动化邮件管理、搜索和发送指南

🇨🇳中文介绍

Gmail

安装

设置验证

身份验证

快速开始

相关 Skills

命令

check

auth setup

auth reset

auth status

messages list

messages get

send

drafts list

drafts create

drafts send

labels list

labels create

示例

验证设置

查找未读邮件

搜索来自特定发件人的邮件

发送快速邮件

创建并发送草稿

使用标签进行组织

高级搜索

Gmail 搜索查询语法

错误处理

模型指导

🇺🇸English

Gmail

Installation

Setup Verification

Authentication

Quick Start

Commands

check

auth setup

auth reset

auth status

messages list

messages get

send

drafts list

drafts create

drafts send

labels list

labels create

Examples

Verify Setup

Find unread emails

Search for emails from a sender

Send a quick email

Create and send a draft

Organize with labels

Advanced searches

Gmail Search Query Syntax

Error Handling

Model Guidance

最新 Skills