gmail

Gmail 邮件管理

本技能提供 Gmail 邮件、标签和整理工作的全面指南。

要求

• 已安装并连接 Hyper MCP。 https://app.hyperfx.ai/mcp
• 已在 https://app.hyperfx.ai/apps 启用 Gmail 集成。

如何运行本技能中的工具

本技能中的每个工具都使用其规范工具名称。使用当前界面提供的调用方式运行：

界面	查找工具	运行工具
MCP 客户端（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>")，然后调用 describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>"，然后调用 hyperai describe <name>	hyperai call <name> --json '{...}'

如果找不到某个工具，则表示其集成尚未连接或未在工作区中启用：请停止操作，并告知用户需要连接哪个集成。

标签操作——关键区别

添加标签（邮件保留在当前位置，同时添加新标签）

• 使用：gmail_labels_add
• 适用场景：添加标签，但不将邮件移出当前位置
• 示例：邮件仍保留在 INBOX 中，同时添加“重要”标签

移至标签（从 INBOX 移除，并添加目标标签）

• 使用：gmail_messages_move_to_label
• 适用场景：将邮件移出收件箱并移至特定标签/文件夹
• 示例：邮件从 INBOX 移除，并移至“归档”或“工作”
• 此操作会执行两项操作：移除 INBOX 标签，并添加目标标签

移除标签（移除指定标签）

• 使用：gmail_labels_remove
• 适用场景：移除邮件上的标签
• 可移除任何标签，包括 INBOX

获取标签 ID

重要： 大多数 Gmail 标签操作需要标签 ID，而不是标签名称。

• 始终先调用 gmail_labels_list，以获取可用标签及其 ID
• 标签 ID 的格式类似：“Label_123”、“Label_456”，或系统标签：“INBOX”、“SENT”、“TRASH”
• 切勿猜测或编造标签 ID

常见工作流

邮件筛选/整理

1. 调用 gmail_labels_list 查看可用标签
2. 调用 gmail_messages_list 获取邮件
3. 使用 gmail_messages_move_to_label 将邮件从 INBOX 移至合适的标签

添加分类（保留在收件箱中）

1. 调用 gmail_labels_list 获取标签 ID
2. 使用 gmail_labels_add 为邮件添加分类，同时将其保留在 INBOX 中

创建新标签

• 如果所需标签不存在，则使用 gmail_labels_create
• 返回新标签的 ID，可立即使用

搜索和列出邮件

gmail_messages_list 支持完整的 Gmail 搜索查询语法：

• query 参数接受与 Gmail 搜索框相同的语法
• 示例：“is:unread”、“from:[email protected]”、“has:attachment subject:invoice”
• 可组合运算符：“from:[email protected] is:unread has:attachment”
• 默认情况下会排除草稿（自动添加 -in:draft）
• 使用 label 参数按指定标签筛选

草稿工作流

创建并发送草稿邮件

1. gmail_drafts_create——创建初始草稿
2. gmail_drafts_update——编辑现有草稿（可选）
3. gmail_drafts_send——将草稿作为邮件发送

管理草稿

• gmail_drafts_list——列出所有草稿邮件
• gmail_drafts_get——通过 ID 获取指定草稿
• gmail_drafts_delete——删除草稿而不发送

何时使用草稿或直接发送

• 使用 gmail_messages_send 立即一步发送
• 如果要在发送前审核/编辑，或安排稍后发送，请使用草稿工作流

邮件操作——重要区别

归档与移至垃圾箱

• gmail_messages_archive——从 INBOX 移除，但保留在“所有邮件”中（可恢复，未删除）
• gmail_messages_trash——移至垃圾箱文件夹（30 天后将自动删除）
• 归档是“清理”收件箱同时保留邮件的首选方式

附件

• gmail_attachments_get - 下载收到的邮件中的附件
• 发送带附件的邮件时，使用 file_ids 参数（需要先将文件存入数据库）

工具选择快速参考

操作	工具
添加标签 X	gmail_labels_add
移动到标签 X	gmail_messages_move_to_label
从收件箱中移除	gmail_messages_move_to_label（移至目标位置）或 gmail_labels_remove（仅移除 INBOX）
归档邮件	gmail_messages_archive（清理时优先使用）
删除邮件/移至垃圾箱	gmail_messages_trash
立即发送邮件	gmail_messages_send
创建稍后发送的邮件	gmail_drafts_create + gmail_drafts_send