使用 Google Workspace CLIgws按标签批量转发 Gmail 邮件Recipe 实战指南【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli导读recipe-forward-labeled-emails是 Google Workspace CLIgws内置的 productivity 类 Recipe它演示了一条完整可复用的邮件自动化链路先用 Gmail 查询语法筛选出带有指定标签Label的邮件再读取单封邮件内容最后以新邮件形式将其转发给其他收件人。本文以该 Recipe 为骨架结合 gws-gmail 助手命令与 forward.rs 源码实现讲透命令的每个参数、底层工作原理与实战变体。读完你可以直接用命令行完成「把needs-review等标签下的全部邮件批量转给经理审阅」这类日常工作并理解转发时主题、线程头、附件与 HTML 内容是如何被构造的。一、Recipe 是什么从 SKILL.md 到注册表在gws中Recipe 是一组可复用的、面向具体业务场景的命令步骤清单。本 Recipe 的定义位于 skills/recipe-forward-labeled-emails/SKILL.md其 frontmatter 声明了关键元数据字段值含义namerecipe-forward-labeled-emailsRecipe 唯一标识descriptionFind Gmail messages with a specific label and forward them to another address一句话功能描述metadata.version0.22.5随项目版本同步metadata.openclaw.categoryrecipe类型为 Recipemetadata.openclaw.domainproductivity归属生产力场景requires.binsgws依赖gws可执行文件requires.skillsgws-gmail前置技能为 Gmail 助手命令同一 Recipe 也在注册表 crates/google-workspace-cli/registry/recipes.toml 中登记name forward-labeled-emailsservices [gmail]与 SKILL.md 保持一致便于工具链统一发现与生成。执行本 Recipe 的前提是加载gws-gmail技能——它本身并不直接调用底层 REST API 的完整方法列表而是建立在gws gmail助手命令之上。二、前置准备认证与全局约定Recipe 中的每条命令都运行在gws统一 CLI 语法之上gws service resource [sub-resource] method [flags]在开始前需要完成 OAuth 登录详见 gws-shared# 交互式浏览器 OAuth 登录 gws auth login # 或使用 Service Account export GOOGLE_APPLICATION_CREDENTIALS/path/to/key.json常用的全局输出与安全选项包括--formatjson默认 /table/yaml/csv、--dry-run本地校验但不调用 API、--sanitize TEMPLATE经 Model Armor 过滤响应。注意 Shell 引号规则--params与--json的 JSON 值必须用单引号包裹避免内层双引号被 Shell 展开。三、三步走通「按标签查找并转发」Recipe 的核心步骤只有三步从「筛」到「读」再到「转」链路非常清晰步骤 1用 Gmail 查询语法筛选带标签的邮件gws gmail users messages list --params {userId: me, q: label:needs-review} --format table这是对 Gmail APIusers.messages.list的通用方法调用userId固定为me当前认证用户q传入 Gmail 标准查询语法。label:needs-review表示筛选带有该标签的邮件你还可以组合is:unread、newer_than:7d、from:bossexample.com等条件语法与 Gmail 网页搜索一致。--format table让结果以表格形式输出便于人工确认消息 ID 与主题。步骤 2读取单封邮件的完整内容gws gmail users messages get --params {userId: me, id: MSG_ID}把上一步拿到的MSG_ID填入id参数即可获取该邮件的完整 payload含头部、正文、附件元数据。更便捷的方式是使用gws gmail read助手命令见 gws-gmail-read它会把邮件正文提取为纯文本gws gmail read --id MSG_ID加--headers可同时输出 From/To/Subject/Date加--format json便于程序化消费。步骤 3以新邮件形式转发gws gmail send --to managercompany.com --subject FW: [Original Subject] --body Forwarding for your review: [Original Message Body]Recipe 采用「读出来再发出去」的策略把原邮件的主题加上FW:前缀、把原文正文粘贴进--body用send发给新收件人。但如果你希望保留原邮件的发件人、日期、收件人、附件与线程关系更推荐直接用专用的gws gmail forward助手命令见 gws-gmail-forward——它会自动完成上述所有工作见下文第五节。四、发送新邮件的send参数详解Recipe 第三步使用的send是 send.rs 实现的 Gmail 助手命令完整参数如下详见 gws-gmail-sendFlag必填说明--to✓收件人地址多个用逗号分隔--subject✓邮件主题--body✓正文纯文本或配合--html使用 HTML 片段--from—发件人别名send-as省略则用账号默认地址--attach/-a—附加文件可重复指定多次--cc/--bcc—抄送 / 密送多个用逗号分隔--html—将--body按 HTML 处理默认纯文本--dry-run—只显示将要发送的请求不真正执行--draft—存为草稿而不是立即发送从源码看handle_send会先解析参数--to为空会直接报--to must specify at least one recipient校验错误随后用mail_builder生成 RFC 5322 格式的 MIME 原始消息自动完成 base64 编码--from会通过 Gmail 的settings.sendAs接口解析发送身份若指定了显示名则跳过 API 调用。总附件大小上限为 25MB。五、真正的「转发」forward助手命令如果希望更接近 Gmail 网页端的「转发」体验gws gmail forward实现在 forward.rs是 Recipe 第三步的进阶替代它在send的基础上自动完成三件事自动构造转发块读取原邮件的 From/Date/Subject/To/Cc 与正文拼装成---------- Forwarded message ---------格式的引用块纯文本模式或带gmail_quoteCSS 类的 HTML 块--html模式。自动添加Fwd:主题前缀build_forward_subject对不以Fwd:不区分大小写开头的主题统一加前缀已有前缀则原样保留。维护线程头build_references_chain把原邮件的 Message-ID 与 References 链带入新邮件In-Reply-To指向直接父邮件保证 Gmail 收件端线程归组正确。其参数与send基本一致但--message-id取代了--subject/--body的必填地位Flag必填说明--message-id✓要转发的 Gmail 消息 ID--to✓收件人逗号分隔--from—发件身份send-as 别名--body—在转发块上方附加的说明文字配合--html可为 HTML 片段--no-original-attachments—不带原邮件的文件附件--html模式仍保留内联图片--attach/-a—额外附加文件可多次指定--cc/--bcc—抄送 / 密送--html—正文与转发块按 HTML 处理--dry-run—本地构造消息并预览不请求 API、不携带真实附件数据--draft—存为草稿典型用法# 基础转发 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com # 附加说明 抄送 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com --body FYI see below --cc eveexample.com # HTML 转发保留原邮件排版与内联图片 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com --body pFYI/p --html # 不带原附件只转发正文 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com --no-original-attachments # 先存草稿确认后再发 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com --draft六、源码级原理转发时发生了什么1. 原邮件的读取与解析handle_forward在非--dry-run模式下先以gmail.modify权限GMAIL_SCOPE见 mod.rs获取令牌再调用GET /gmail/v1/users/me/messages/{id}?formatfull拉取完整消息fetch_message_metadata。随后parse_original_message从 JSON payload 的 headers 中解析 From/To/Cc/Subject/Date/Message-ID/References并递归遍历 MIME payload 树提取纯文本正文、HTML 正文与附件元数据extract_payload_recursive。若From或Message-ID头缺失会直接报错保证转发块内容完整。2. 附件与内联图片的策略include_original_part函数实现了一套与 Gmail 网页端对齐的过滤矩阵模式普通文件附件内联图片有 Content-ID默认纯文本保留丢弃与 Gmail 网页一致--html保留保留通过cid:引用渲染--no-original-attachments纯文本丢弃丢弃--no-original-attachments--html丢弃保留属于正文一部分附件二进制数据通过GET /users/me/messages/{id}/attachments/{attachmentId}逐个拉取fetch_attachment_data并先按元数据尺寸做预检、下载后再校验累计大小超出 25MB 上限MAX_TOTAL_ATTACHMENT_BYTES会返回明确的校验错误。原附件与你用-a附加的文件一起计入该上限。3. 消息组装与发送create_forward_raw_message使用mail_builder组装 MIME 消息写入收件人与可选头From/Cc/Bcc、线程头In-Reply-To/References再将「你的说明 转发块」按纯文本或 HTML 模式拼接最后dispatch_raw_email根据--draft选择调用messages.send或drafts.create。--dry-run则使用占位消息OriginalMessage::dry_run_placeholder在本地构造预览完全不触网、不携带真实附件数据。4. 测试保障forward.rs 内置了 20 个单元测试覆盖转发块格式含/缺 Date、Cc、Fwd:前缀的大小写与幂等、References 链构造、HTML 模式回退与转义、等字符会被正确转义、附件与内联图片的multipart/mixed/multipart/related结构以及上述过滤矩阵的四种组合。这些测试从侧面印证了「转发行为与 Gmail 网页端一致」的设计目标。七、组合实战把 Recipe 升级为批量工作流将三步命令与forward结合可以写成一段可循环的批量转发流程伪代码示意# 1. 列出标签下所有邮件 ID IDS$(gws gmail users messages list \ --params {userId: me, q: label:needs-review is:unread} \ --format json | jq -r .messages[].id) # 2. 逐个转发或先 --draft 人工复核 for id in $IDS; do gws gmail forward --message-id $id --to managercompany.com \ --body Forwarding for your review --no-original-attachments --draft done要点与限制查询条件可自由组合如label:needs-review newer_than:30d、label:invoices from:vendorexample.com结果翻页可用全局的--page-all与--page-limit控制。生产环境建议先用--draft或--dry-run验证目标邮件再真正发送——Recipe 的send/forward均为写操作请遵守 gws-shared 中的安全规则执行写命令前与用户确认。25MB 附件上限对含大附件的邮件批量转发是硬约束正文层面的转发--no-original-attachments则没有此顾虑。八、小结recipe-forward-labeled-emails虽只有三步却完整演示了gws的两类命令协作模式通用 API 方法users messages list/get负责查询与读取助手命令send/forward负责构造并发送合规的 MIME 消息。若只是把标签邮件转给他人直接使用forward一行命令即可获得与 Gmail 网页端一致的转发块、附件策略与线程归组如需深度定制正文或批量加工则按 Recipe 的三步链路自行组合。相关技能的完整参数表可继续查阅 gws-gmail、gws-gmail-forward、gws-gmail-send 与 gws-gmail-read。【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
使用 Google Workspace CLI（gws）按标签批量转发 Gmail 邮件：Recipe 实战指南
使用 Google Workspace CLIgws按标签批量转发 Gmail 邮件Recipe 实战指南【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli导读recipe-forward-labeled-emails是 Google Workspace CLIgws内置的 productivity 类 Recipe它演示了一条完整可复用的邮件自动化链路先用 Gmail 查询语法筛选出带有指定标签Label的邮件再读取单封邮件内容最后以新邮件形式将其转发给其他收件人。本文以该 Recipe 为骨架结合 gws-gmail 助手命令与 forward.rs 源码实现讲透命令的每个参数、底层工作原理与实战变体。读完你可以直接用命令行完成「把needs-review等标签下的全部邮件批量转给经理审阅」这类日常工作并理解转发时主题、线程头、附件与 HTML 内容是如何被构造的。一、Recipe 是什么从 SKILL.md 到注册表在gws中Recipe 是一组可复用的、面向具体业务场景的命令步骤清单。本 Recipe 的定义位于 skills/recipe-forward-labeled-emails/SKILL.md其 frontmatter 声明了关键元数据字段值含义namerecipe-forward-labeled-emailsRecipe 唯一标识descriptionFind Gmail messages with a specific label and forward them to another address一句话功能描述metadata.version0.22.5随项目版本同步metadata.openclaw.categoryrecipe类型为 Recipemetadata.openclaw.domainproductivity归属生产力场景requires.binsgws依赖gws可执行文件requires.skillsgws-gmail前置技能为 Gmail 助手命令同一 Recipe 也在注册表 crates/google-workspace-cli/registry/recipes.toml 中登记name forward-labeled-emailsservices [gmail]与 SKILL.md 保持一致便于工具链统一发现与生成。执行本 Recipe 的前提是加载gws-gmail技能——它本身并不直接调用底层 REST API 的完整方法列表而是建立在gws gmail助手命令之上。二、前置准备认证与全局约定Recipe 中的每条命令都运行在gws统一 CLI 语法之上gws service resource [sub-resource] method [flags]在开始前需要完成 OAuth 登录详见 gws-shared# 交互式浏览器 OAuth 登录 gws auth login # 或使用 Service Account export GOOGLE_APPLICATION_CREDENTIALS/path/to/key.json常用的全局输出与安全选项包括--formatjson默认 /table/yaml/csv、--dry-run本地校验但不调用 API、--sanitize TEMPLATE经 Model Armor 过滤响应。注意 Shell 引号规则--params与--json的 JSON 值必须用单引号包裹避免内层双引号被 Shell 展开。三、三步走通「按标签查找并转发」Recipe 的核心步骤只有三步从「筛」到「读」再到「转」链路非常清晰步骤 1用 Gmail 查询语法筛选带标签的邮件gws gmail users messages list --params {userId: me, q: label:needs-review} --format table这是对 Gmail APIusers.messages.list的通用方法调用userId固定为me当前认证用户q传入 Gmail 标准查询语法。label:needs-review表示筛选带有该标签的邮件你还可以组合is:unread、newer_than:7d、from:bossexample.com等条件语法与 Gmail 网页搜索一致。--format table让结果以表格形式输出便于人工确认消息 ID 与主题。步骤 2读取单封邮件的完整内容gws gmail users messages get --params {userId: me, id: MSG_ID}把上一步拿到的MSG_ID填入id参数即可获取该邮件的完整 payload含头部、正文、附件元数据。更便捷的方式是使用gws gmail read助手命令见 gws-gmail-read它会把邮件正文提取为纯文本gws gmail read --id MSG_ID加--headers可同时输出 From/To/Subject/Date加--format json便于程序化消费。步骤 3以新邮件形式转发gws gmail send --to managercompany.com --subject FW: [Original Subject] --body Forwarding for your review: [Original Message Body]Recipe 采用「读出来再发出去」的策略把原邮件的主题加上FW:前缀、把原文正文粘贴进--body用send发给新收件人。但如果你希望保留原邮件的发件人、日期、收件人、附件与线程关系更推荐直接用专用的gws gmail forward助手命令见 gws-gmail-forward——它会自动完成上述所有工作见下文第五节。四、发送新邮件的send参数详解Recipe 第三步使用的send是 send.rs 实现的 Gmail 助手命令完整参数如下详见 gws-gmail-sendFlag必填说明--to✓收件人地址多个用逗号分隔--subject✓邮件主题--body✓正文纯文本或配合--html使用 HTML 片段--from—发件人别名send-as省略则用账号默认地址--attach/-a—附加文件可重复指定多次--cc/--bcc—抄送 / 密送多个用逗号分隔--html—将--body按 HTML 处理默认纯文本--dry-run—只显示将要发送的请求不真正执行--draft—存为草稿而不是立即发送从源码看handle_send会先解析参数--to为空会直接报--to must specify at least one recipient校验错误随后用mail_builder生成 RFC 5322 格式的 MIME 原始消息自动完成 base64 编码--from会通过 Gmail 的settings.sendAs接口解析发送身份若指定了显示名则跳过 API 调用。总附件大小上限为 25MB。五、真正的「转发」forward助手命令如果希望更接近 Gmail 网页端的「转发」体验gws gmail forward实现在 forward.rs是 Recipe 第三步的进阶替代它在send的基础上自动完成三件事自动构造转发块读取原邮件的 From/Date/Subject/To/Cc 与正文拼装成---------- Forwarded message ---------格式的引用块纯文本模式或带gmail_quoteCSS 类的 HTML 块--html模式。自动添加Fwd:主题前缀build_forward_subject对不以Fwd:不区分大小写开头的主题统一加前缀已有前缀则原样保留。维护线程头build_references_chain把原邮件的 Message-ID 与 References 链带入新邮件In-Reply-To指向直接父邮件保证 Gmail 收件端线程归组正确。其参数与send基本一致但--message-id取代了--subject/--body的必填地位Flag必填说明--message-id✓要转发的 Gmail 消息 ID--to✓收件人逗号分隔--from—发件身份send-as 别名--body—在转发块上方附加的说明文字配合--html可为 HTML 片段--no-original-attachments—不带原邮件的文件附件--html模式仍保留内联图片--attach/-a—额外附加文件可多次指定--cc/--bcc—抄送 / 密送--html—正文与转发块按 HTML 处理--dry-run—本地构造消息并预览不请求 API、不携带真实附件数据--draft—存为草稿典型用法# 基础转发 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com # 附加说明 抄送 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com --body FYI see below --cc eveexample.com # HTML 转发保留原邮件排版与内联图片 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com --body pFYI/p --html # 不带原附件只转发正文 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com --no-original-attachments # 先存草稿确认后再发 gws gmail forward --message-id 18f1a2b3c4d --to daveexample.com --draft六、源码级原理转发时发生了什么1. 原邮件的读取与解析handle_forward在非--dry-run模式下先以gmail.modify权限GMAIL_SCOPE见 mod.rs获取令牌再调用GET /gmail/v1/users/me/messages/{id}?formatfull拉取完整消息fetch_message_metadata。随后parse_original_message从 JSON payload 的 headers 中解析 From/To/Cc/Subject/Date/Message-ID/References并递归遍历 MIME payload 树提取纯文本正文、HTML 正文与附件元数据extract_payload_recursive。若From或Message-ID头缺失会直接报错保证转发块内容完整。2. 附件与内联图片的策略include_original_part函数实现了一套与 Gmail 网页端对齐的过滤矩阵模式普通文件附件内联图片有 Content-ID默认纯文本保留丢弃与 Gmail 网页一致--html保留保留通过cid:引用渲染--no-original-attachments纯文本丢弃丢弃--no-original-attachments--html丢弃保留属于正文一部分附件二进制数据通过GET /users/me/messages/{id}/attachments/{attachmentId}逐个拉取fetch_attachment_data并先按元数据尺寸做预检、下载后再校验累计大小超出 25MB 上限MAX_TOTAL_ATTACHMENT_BYTES会返回明确的校验错误。原附件与你用-a附加的文件一起计入该上限。3. 消息组装与发送create_forward_raw_message使用mail_builder组装 MIME 消息写入收件人与可选头From/Cc/Bcc、线程头In-Reply-To/References再将「你的说明 转发块」按纯文本或 HTML 模式拼接最后dispatch_raw_email根据--draft选择调用messages.send或drafts.create。--dry-run则使用占位消息OriginalMessage::dry_run_placeholder在本地构造预览完全不触网、不携带真实附件数据。4. 测试保障forward.rs 内置了 20 个单元测试覆盖转发块格式含/缺 Date、Cc、Fwd:前缀的大小写与幂等、References 链构造、HTML 模式回退与转义、等字符会被正确转义、附件与内联图片的multipart/mixed/multipart/related结构以及上述过滤矩阵的四种组合。这些测试从侧面印证了「转发行为与 Gmail 网页端一致」的设计目标。七、组合实战把 Recipe 升级为批量工作流将三步命令与forward结合可以写成一段可循环的批量转发流程伪代码示意# 1. 列出标签下所有邮件 ID IDS$(gws gmail users messages list \ --params {userId: me, q: label:needs-review is:unread} \ --format json | jq -r .messages[].id) # 2. 逐个转发或先 --draft 人工复核 for id in $IDS; do gws gmail forward --message-id $id --to managercompany.com \ --body Forwarding for your review --no-original-attachments --draft done要点与限制查询条件可自由组合如label:needs-review newer_than:30d、label:invoices from:vendorexample.com结果翻页可用全局的--page-all与--page-limit控制。生产环境建议先用--draft或--dry-run验证目标邮件再真正发送——Recipe 的send/forward均为写操作请遵守 gws-shared 中的安全规则执行写命令前与用户确认。25MB 附件上限对含大附件的邮件批量转发是硬约束正文层面的转发--no-original-attachments则没有此顾虑。八、小结recipe-forward-labeled-emails虽只有三步却完整演示了gws的两类命令协作模式通用 API 方法users messages list/get负责查询与读取助手命令send/forward负责构造并发送合规的 MIME 消息。若只是把标签邮件转给他人直接使用forward一行命令即可获得与 Gmail 网页端一致的转发块、附件策略与线程归组如需深度定制正文或批量加工则按 Recipe 的三步链路自行组合。相关技能的完整参数表可继续查阅 gws-gmail、gws-gmail-forward、gws-gmail-send 与 gws-gmail-read。【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
