gmail

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gmail Search Skill

Gmail搜索技能

Search and fetch emails via Gmail API with flexible query options and output formats.

通过Gmail API搜索和获取邮件，支持灵活的查询选项与输出格式。

Prerequisites

前置条件

Credentials must be configured in

~/.gmail_credentials/

. Run

setup

to check status:

bash

python3 scripts/gmail_search.py setup

需在

~/.gmail_credentials/

目录下配置凭据。运行

setup

命令检查状态：

bash

python3 scripts/gmail_search.py setup

Obtaining Gmail API Credentials

获取Gmail API凭据

1. Create Google Cloud Project

1. 创建Google Cloud项目

Go to console.cloud.google.com
Click project dropdown -> "New Project"
Name it (e.g., "Gmail Agent Skill") -> Create

访问console.cloud.google.com
点击项目下拉菜单 -> “新建项目”
为项目命名（例如：“Gmail Agent Skill”）-> 点击创建

2. Enable Gmail API

2. 启用Gmail API

Navigate to "APIs & Services" -> "Library"
Search for "Gmail API"
Click it and press "Enable"

导航至“API与服务” -> “库”
搜索“Gmail API”
点击该API并选择“启用”

3. Configure OAuth Consent Screen

3. 配置OAuth同意屏幕

Go to "OAuth consent screen" (left sidebar)
Choose "External" user type
Fill in required fields:
- App name: Gmail Agent Skill
- User support email: your email
- Developer email: your email
Click "Save and Continue", skip Scopes
On "Test users" page, add your Gmail address
Complete all steps

进入左侧边栏的“OAuth同意屏幕”
选择“外部”用户类型
填写必填字段：
- 应用名称：Gmail Agent Skill
- 用户支持邮箱：你的邮箱地址
- 开发者邮箱：你的邮箱地址
点击“保存并继续”，跳过权限范围步骤
在“测试用户”页面，添加你的Gmail地址
完成所有步骤

4. Publish the Test App

4. 发布测试应用

Important: Without this step, you'll get "Error 403: access_denied".

Go back to "OAuth consent screen"
Under "Publishing status", click "Publish App"
Confirm the dialog

This keeps the app in test mode (not production) but allows your test users to authenticate. You'll see an "unverified app" warning during login - click "Advanced" -> "Go to Gmail Agent Skill (unsafe)" to proceed.

Note: Test tokens expire after 7 days. Production requires Google verification.

重要提示： 若不执行此步骤，你将遇到“Error 403: access_denied”错误。

返回“OAuth同意屏幕”页面
在“发布状态”下，点击“发布应用”
确认弹窗提示

此操作会将应用保持在测试模式（而非生产模式），但允许你的测试用户完成身份验证。登录过程中你会看到“未经验证的应用”警告，点击“高级” -> “前往Gmail Agent Skill（不安全）”即可继续。

注意： 测试令牌有效期为7天。生产环境需要通过Google的验证流程。

5. Create OAuth Credentials

5. 创建OAuth凭据

Go to "Credentials" (left sidebar)
Click "Create Credentials" -> "OAuth client ID"
Select "Desktop app" as application type
Name it (e.g., "Gmail Agent Client")
Click "Create"

进入左侧边栏的“凭据”页面
点击“创建凭据” -> “OAuth客户端ID”
选择应用类型为“桌面应用”
为其命名（例如：“Gmail Agent Client”）
点击“创建”

6. Get Your Credentials

6. 获取你的凭据

Client ID will be displayed - copy it
Client Secret: Click the download icon or view details to get the secret

页面会显示客户端ID，复制该ID
客户端密钥：点击下载图标或查看详情以获取密钥

7. Save Credentials

7. 保存凭据

Create

~/.gmail_credentials/credentials.json

json

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}

创建

~/.gmail_credentials/credentials.json

文件：

json

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}

8. Authenticate

8. 身份验证

bash

python3 scripts/gmail_search.py auth

This opens a browser. Click through the "unverified app" warning ("Advanced" -> "Go to Gmail Agent Skill"), approve access, and you're ready.

bash

python3 scripts/gmail_search.py auth

执行该命令会打开浏览器。点击跳过“未经验证的应用”警告（“高级” -> “前往Gmail Agent Skill”），授权访问权限后即可完成配置。

Quick Start

快速开始

bash

undefined

bash

undefined

Check setup status

检查设置状态

python3 scripts/gmail_search.py setup

Authenticate (opens browser)

身份验证（打开浏览器）

python3 scripts/gmail_search.py auth

Search emails

搜索邮件

python3 scripts/gmail_search.py search "meeting notes"

Search with filters

使用筛选条件搜索

python3 scripts/gmail_search.py search --from "boss@company.com" --unread

undefined

python3 scripts/gmail_search.py search --from "boss@company.com" --unread

undefined

Commands

命令说明

Setup

检查设置

Check configuration status:

bash

python3 scripts/gmail_search.py setup
python3 scripts/gmail_search.py setup --json

检查配置状态：

bash

python3 scripts/gmail_search.py setup
python3 scripts/gmail_search.py setup --json

Authenticate

身份验证

Authenticate with Gmail (opens browser for OAuth):

bash

python3 scripts/gmail_search.py auth

通过Gmail完成身份验证（会打开浏览器进行OAuth授权）：

bash

python3 scripts/gmail_search.py auth

Scope

权限范围

View or change API permission scope:

bash

undefined

查看或修改API权限范围：

bash

undefined

View current scope

查看当前权限范围

python3 scripts/gmail_search.py scope

Change scope (requires re-auth)

修改权限范围（需要重新进行身份验证）

python3 scripts/gmail_search.py scope --set readonly python3 scripts/gmail_search.py scope --set modify python3 scripts/gmail_search.py scope --set full


**Available scopes:**
- `readonly` - Read emails only (default, recommended)
- `modify` - Read + modify labels, mark read/unread
- `full` - Full access including delete

python3 scripts/gmail_search.py scope --set readonly python3 scripts/gmail_search.py scope --set modify python3 scripts/gmail_search.py scope --set full


**可用权限范围：**
- `readonly` - 仅读取邮件（默认推荐选项）
- `modify` - 读取邮件 + 修改标签、标记已读/未读
- `full` - 完全访问权限，包括删除邮件

Search

搜索邮件

Search emails with free-text query or filters:

bash

undefined

使用自由文本查询或筛选条件搜索邮件：

bash

undefined

Free-text search (uses Gmail search syntax)

自由文本搜索（使用Gmail原生搜索语法）

python3 scripts/gmail_search.py search "project deadline" python3 scripts/gmail_search.py search "from:john@example.com subject:invoice"

Using helper flags

使用辅助参数

python3 scripts/gmail_search.py search --from "john@example.com" python3 scripts/gmail_search.py search --to "me@example.com" python3 scripts/gmail_search.py search --subject "Weekly Report" python3 scripts/gmail_search.py search --label "INBOX" python3 scripts/gmail_search.py search --label "work"

Date filters (YYYY/MM/DD format)

日期筛选（格式为YYYY/MM/DD）

python3 scripts/gmail_search.py search --after 2024/01/01 python3 scripts/gmail_search.py search --before 2024/12/31 python3 scripts/gmail_search.py search --after 2024/01/01 --before 2024/06/30

Status filters

状态筛选

python3 scripts/gmail_search.py search --unread python3 scripts/gmail_search.py search --starred python3 scripts/gmail_search.py search --has-attachment

Combined filters

组合筛选条件

python3 scripts/gmail_search.py search "invoice" --from "billing@" --has-attachment --after 2024/01/01

Limit results

限制结果数量

python3 scripts/gmail_search.py search "meeting" --limit 50

Include full body (default shows snippet only)

包含完整邮件内容（默认仅显示摘要）

python3 scripts/gmail_search.py search "contract" --full

Include attachment info

包含附件信息

python3 scripts/gmail_search.py search --has-attachment --attachments

JSON output

JSON格式输出

python3 scripts/gmail_search.py search "project" --json

undefined

python3 scripts/gmail_search.py search "project" --json

undefined

Download Attachments

下载附件

Download attachments from a specific message:

bash

undefined

从指定邮件中下载附件：

bash

undefined

Download to default location (~/Downloads/gmail_attachments/)

下载至默认目录（~/Downloads/gmail_attachments/）

python3 scripts/gmail_search.py download MESSAGE_ID

Download to custom directory

下载至自定义目录

python3 scripts/gmail_search.py download MESSAGE_ID --output /path/to/folder

JSON output

JSON格式输出

python3 scripts/gmail_search.py download MESSAGE_ID --json


Get message ID from search results (shown in output).

python3 scripts/gmail_search.py download MESSAGE_ID --json


邮件ID可从搜索结果中获取（会在输出中显示）。

Labels

标签管理

List all available Gmail labels:

bash

python3 scripts/gmail_search.py labels
python3 scripts/gmail_search.py labels --json

列出所有可用的Gmail标签：

bash

python3 scripts/gmail_search.py labels
python3 scripts/gmail_search.py labels --json

Output Formats

输出格式

Markdown (default)

Markdown（默认）

markdown

undefined

markdown

undefined

Gmail Search Results (3 messages)

Weekly Report

From: boss@company.com To: me@example.com Date: Mon, 25 Nov 2024 10:00:00 +0000 ID:

18abc123def

Here's the weekly report summary...

undefined

From: boss@company.com To: me@example.com Date: Mon, 25 Nov 2024 10:00:00 +0000 ID:

18abc123def

Here's the weekly report summary...

undefined

JSON

Add

--json

flag for structured output:

json

[
  {
    "id": "18abc123def",
    "thread_id": "18abc123def",
    "from": "boss@company.com",
    "to": "me@example.com",
    "subject": "Weekly Report",
    "date": "Mon, 25 Nov 2024 10:00:00 +0000",
    "snippet": "Here's the weekly report summary...",
    "labels": ["INBOX", "UNREAD"]
  }
]

添加

--json

参数以获取结构化输出：

json

[
  {
    "id": "18abc123def",
    "thread_id": "18abc123def",
    "from": "boss@company.com",
    "to": "me@example.com",
    "subject": "Weekly Report",
    "date": "Mon, 25 Nov 2024 10:00:00 +0000",
    "snippet": "Here's the weekly report summary...",
    "labels": ["INBOX", "UNREAD"]
  }
]

Gmail Search Syntax

Gmail搜索语法

The skill supports Gmail's native search syntax in free-text queries:

Operator	Example	Description
`from:`	`from:john@example.com`	From specific sender
`to:`	`to:team@company.com`	To specific recipient
`subject:`	`subject:meeting`	In subject line
`label:`	`label:work`	Has specific label
`has:attachment`	`has:attachment`	Has attachments
`filename:`	`filename:pdf`	Attachment filename
`is:unread`	`is:unread`	Unread messages
`is:starred`	`is:starred`	Starred messages
`after:`	`after:2024/01/01`	After date
`before:`	`before:2024/12/31`	Before date
`newer_than:`	`newer_than:7d`	Within last N days
`older_than:`	`older_than:1m`	Older than N months
`in:`	`in:inbox`	In specific folder
`OR`	`from:john OR from:jane`	Either condition
`-`	`-label:spam`	Exclude
`""`	`"exact phrase"`	Exact match

本技能支持在自由文本查询中使用Gmail原生搜索语法：

操作符	示例	说明
`from:`	`from:john@example.com`	来自指定发件人
`to:`	`to:team@company.com`	发送至指定收件人
`subject:`	`subject:meeting`	主题包含指定内容
`label:`	`label:work`	带有指定标签
`has:attachment`	`has:attachment`	包含附件
`filename:`	`filename:pdf`	附件文件名匹配
`is:unread`	`is:unread`	未读邮件
`is:starred`	`is:starred`	已加星标的邮件
`after:`	`after:2024/01/01`	指定日期之后的邮件
`before:`	`before:2024/12/31`	指定日期之前的邮件
`newer_than:`	`newer_than:7d`	最近N天内的邮件
`older_than:`	`older_than:1m`	早于N个月的邮件
`in:`	`in:inbox`	在指定文件夹中
`OR`	`from:john OR from:jane`	满足任一条件
`-`	`-label:spam`	排除指定条件
`""`	`"exact phrase"`	精确匹配短语

Example User Requests

用户请求示例

User says	Command
"Search Gmail for meeting notes"	`search "meeting notes"`
"Find emails from John"	`search --from "john"`
"Show unread emails"	`search --unread`
"Emails about the project from last month"	`search "project" --after 2024/10/01`
"Invoices with attachments"	`search "invoice" --has-attachment`
"Read the full email about contract"	`search "contract" --full --limit 1`
"Download attachments from that email"	`download MESSAGE_ID`
"What labels do I have?"	`labels`
"Starred emails from boss"	`search --from "boss" --starred`
"Is Gmail configured?"	`setup`

用户指令	对应命令
“搜索Gmail中的会议纪要”	`search "meeting notes"`
“查找来自John的邮件”	`search --from "john"`
“显示未读邮件”	`search --unread`
“上个月关于项目的邮件”	`search "project" --after 2024/10/01`
“带有附件的发票邮件”	`search "invoice" --has-attachment`
“查看关于合同的完整邮件”	`search "contract" --full --limit 1`
“下载那封邮件的附件”	`download MESSAGE_ID`
“我有哪些Gmail标签？”	`labels`
“来自老板的已加星标邮件”	`search --from "boss" --starred`
“Gmail配置好了吗？”	`setup`

Dependencies

依赖安装

bash

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

bash

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib