gogcligog gmail unread在终端把 Gmail 消息批量标记为未读的完整指南【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli在 Google Workspace 终端化工具 gogcli 中gog gmail unread是 Gmail「Organize」组下的消息状态管理命令用于把已读消息重新标记为未读即给消息重新加上UNREAD标签。它支持按消息 ID 精确操作也支持用 Gmail 搜索查询语query批量处理并内置--dry-run预览、JSON/TSV 机器可读输出与--max限额保护。读完本文你可以掌握该命令的完整用法与参数、它在源码层的执行链路Users.Messages.BatchModify分批调用、标签名到标签 ID 的解析、分页防死循环保护以及它与gog gmail mark-read、gog gmail archive等同类批量操作的异同。命令概览gog gmail unread的规范用法如下mail/email与mark-unread分别为gmail与unread的别名可互换使用gog gmail (mail,email) unread (mark-unread) [messageId ...] [flags]命令注册在 internal/cmd/gmail.go 中帮助文本为 Mark messages as unread归属 Organize 分组mark-unread是其显式别名// internal/cmd/gmail.go Unread GmailUnreadCmd cmd: name:unread aliases:mark-unread group:Organize help:Mark messages as unread它在 gog gmail 父命令下的完整子命令列表中与mark-read标记已读、archive归档、trash移入垃圾箱并列构成一组消息组织操作。核心参数说明命令本身只有三个直接参数全部定义在 internal/cmd/gmail_archive.go 的GmailUnreadCmd结构体中// GmailUnreadCmd marks messages as unread. type GmailUnreadCmd struct { MessageIDs []string arg: optional: name:messageId help:Message IDs to mark as unread Query string name:query short:q help:Mark all messages matching this query as unread Max int64 name:max aliases:limit help:Max messages (with --query) default:100 }参数类型默认值说明[messageId ...]位置参数可多个可选—要标记为未读的消息 ID与--query二选一二者都缺省时命令以用法错误退出-q,--querystring—使用 Gmail 搜索查询语法匹配消息把全部命中结果标记为未读--max,--limitint64100使用--query时允许处理的最大消息数别名--limit关键行为约束来自同一文件的gmailBulkLabelOp实现必须提供目标既没有位置消息 ID、也没有--query时返回用法错误 provide message IDs or --query--max必须为正--query模式下--max 0会在发起任何 API 请求前就以退出码 2 报 --max must be 0。这一点有测试直接验证internal/cmd/gmail_archive_test.go 中的TestGmailBulkOps_QueryInvalidMaxFailsBeforeDryRun包含unread zero用例消息 ID 会被归一化位置参数先经normalizeGmailMessageIDinternal/cmd/webid.go处理因此可以容忍 Gmail Web URL 形式的输入而非裸 ID归档线程模式的测试用例中就传入了完整的https://mail.google.com/...链接并期望其被解析为 thread ID。两种典型用法按消息 ID 标记未读——把之前读过、想重新处理的邮件恢复成未读状态gog gmail unread 18ab12cd34ef5678 gog gmail unread 18ab12cd34ef5678 18ab99cd00ef1122 # 支持一次传多个用查询批量标记——例如把收件箱里发件人为某人、且本周内的邮件全部恢复未读gog gmail unread --query in:inbox from:aliceexample.com after:2026-09-09 gog gmail unread -q in:inbox older_than:7d is:read --max 50 -n # 先预览前 50 条--query使用的是 Gmail 搜索语法in:inbox、is:unread、from:、after:等与gog gmail search使用的查询语法一致。底层执行链路从 ID 到UNREAD标签gog gmail unread的Run方法只有一行核心逻辑把「加UNREAD标签」委托给共用的批量标签操作函数// internal/cmd/gmail_archive.go func (c *GmailUnreadCmd) Run(ctx context.Context, flags *RootFlags) error { return gmailBulkLabelOp(ctx, flags, c.MessageIDs, c.Query, c.Max, []string{UNREAD}, nil, marked as unread, gmail.unread) }对比同文件中的姊妹命令可以看到差异全部体现在「增/删哪些标签」上mark-read移除UNREAD标签trash加TRASH并移除INBOXarchive只移除INBOX而unread只添加UNREAD、不删除任何标签。dry-run 输出中的操作名gmail.unread也因此在测试 internal/cmd/gmail_archive_test.go 中被断言为added_labels: [UNREAD]、removed_labels: []。gmailBulkLabelOp的完整执行流程如下归一化与校验把位置参数归一化为消息 ID校验「ID 或 query 至少其一」与--max 0dry-run 拦截若带--dry-run别名--dryrun/--noop/--preview通过dryRunExitinternal/cmd/dryrun.go打印包含op、message_ids、query、max、added_labels、removed_labels的结构化请求描述后以退出码 0 结束不访问网络解析账号并构建 Gmail 客户端requireAccount(flags)依据-a/--account账号邮箱、别名或auto确定目标账号gmailService构建服务实例收集消息 ID--query模式下调用searchMessageIDs分页搜索结果与位置参数 ID 合并搜索为空则输出 No messages foundJSON 模式下输出{action:marked as unread,count:0}标签名解析为标签 IDfetchLabelNameToIDinternal/cmd/gmail_labels.go拉取账号标签列表建立名称→ID 映射再由resolveLabelIDsinternal/cmd/gmail_labels_utils.go解析。UNREAD是系统标签该步对其是幂等确认分批调用 BatchModify按每批最多 1000 个 IDGmail API 的users.messages.batchModify上限构造BatchModifyMessagesRequest{Ids, AddLabelIds: [UNREAD]}循环发送任一失败会报 batch modify failed at offset N输出结果非 JSON 模式打印Marked as unread N messages单数消息省略 sJSON 模式输出action、count、addedLabels、removedLabels四个字段的对象。搜索分页的两个细节--query模式下的searchMessageIDsinternal/cmd/gmail_archive.go有两个值得注意的工程细节每页最多取 500 条批大小取min(remaining, 500)并只请求messages(id),nextPageToken字段避免拉取消息正文重复分页令牌保护通过pageTokenGuard检测服务端异常地重复返回相同nextPageToken会导致死循环第 2 次即报错 repeated page token。internal/cmd/gmail_archive_test.go 中的TestSearchMessageIDsRejectsRepeatedPageToken、TestSearchMessageIDsRejectsRepeatedEmptyPageToken与TestGmailArchiveCmd_QueryRejectsRepeatedPageToken用假 HTTP 服务专门覆盖了这一场景。机器可读输出与 Agent 安全开关gog gmail unread继承 gogcli 全部根级标志以下与脚本/Agent 场景最相关完整列表见 docs/commands/gog-gmail-unread.md标志说明-n,--dry-run别名--dryrun/--noop/--preview不修改任何数据打印将要执行的动作并以成功码退出-j,--json别名--machine以 JSON 输出到 stdout最适合脚本消费-p,--plain别名--tsv输出稳定、可解析的 TSV 文本无颜色--results-onlyJSON 模式下只输出主结果去掉nextPageToken等外层字段--select,--pick别名--projectJSON 模式下按逗号分隔的字段路径做 best-effort 选择--wrap-untrusted在 JSON/raw 输出中为抓取到的文本字段包裹外部不可信内容标记供 Agent 消费时防提示注入--readonly运行时阻断一切变更类 API 请求配合auth add还会请求只读 OAuth 作用域--gmail-no-send拦截 Gmail 发送类操作Agent 安全开关-a,--account别名--acct指定账号邮箱、别名或auto多账号场景必用--client指定 OAuth 客户端名选择对应的存储凭据与令牌桶--access-token直接使用给定的 access token绕过存储的 refresh token约 1 小时过期--quota-project指定计费 Google Cloud 项目以X-Goog-User-Project头发送某些 API 在使用--access-token或 ADC 时必需--enable-commands/--enable-commands-exact/--disable-commands按点分路径启用/禁用命令前缀限制 CLI 可用面--no-input别名--non-interactive永不交互式提问出错即失败适合 CI--colorauto\|always\|never、-v/--verbose、--home输出着色、详细日志、覆盖配置/数据根目录等价GOG_HOME组合示例在 CI 中安全地批量恢复未读先预览再执行# 预览将影响哪些消息不联网写操作 gog gmail unread -q in:inbox from:bossexample.com --max 100 -n --json # 确认无误后正式执行仅保留主结果字段 gog gmail unread -q in:inbox from:bossexample.com --max 100 --json --results-only与相关命令的关系gog gmail mark-read同文件同机制的逆向操作移除UNREAD标签而非添加参数结构messageId...、--query、--max默认 100完全一致docs/commands/gog-gmail-mark-read.mdgog gmail archive/gog gmail trash同样走gmailBulkLabelOp区别仅在增删的标签组合archive额外提供--thread按线程操作的模式该模式不可与--query同时使用否则以退出码 2 报 --thread cannot be used with --querygog gmail search只读搜索线程unread --query是「搜索 批量改标签」的写操作版本二者共享 Gmail 查询语法命令树上下文完整的 Gmail 子命令get、send、drafts、labels、thread、settings 等见 docs/commands/gog-gmail.md全部命令索引见 docs/commands/README.md。这些文档页均由gog schema --json自动生成页首注明 Do not edit this page by hand; runmake docs-commands因此文档中的标志定义与源码中的结构体 tag 始终一致。小结gog gmail unread的语义模型非常清晰把「标记未读」实现为「批量给消息添加UNREAD系统标签」通过Users.Messages.BatchModify按 1000 条一批发送天然获得幂等性重复添加同一标签无副作用与批量效率。配合--query --max的限额机制、--dry-run预览、JSON/TSV 输出与--readonly等安全开关它既可以人工交互式使用也可以安全地嵌入脚本和 Agent 工作流例如 gogcli 的 Agent 技能gog-inbox-triage就涉及未读邮件的优先级处理参见 docs/agent-skills.md。测试文件 internal/cmd/gmail_archive_test.go 对 dry-run 请求内容、--max校验、分页令牌防死循环等均做了断言为该行为提供了可直接运行的验证依据。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
gogcli `gog gmail unread`：在终端把 Gmail 消息批量标记为未读的完整指南
gogcligog gmail unread在终端把 Gmail 消息批量标记为未读的完整指南【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli在 Google Workspace 终端化工具 gogcli 中gog gmail unread是 Gmail「Organize」组下的消息状态管理命令用于把已读消息重新标记为未读即给消息重新加上UNREAD标签。它支持按消息 ID 精确操作也支持用 Gmail 搜索查询语query批量处理并内置--dry-run预览、JSON/TSV 机器可读输出与--max限额保护。读完本文你可以掌握该命令的完整用法与参数、它在源码层的执行链路Users.Messages.BatchModify分批调用、标签名到标签 ID 的解析、分页防死循环保护以及它与gog gmail mark-read、gog gmail archive等同类批量操作的异同。命令概览gog gmail unread的规范用法如下mail/email与mark-unread分别为gmail与unread的别名可互换使用gog gmail (mail,email) unread (mark-unread) [messageId ...] [flags]命令注册在 internal/cmd/gmail.go 中帮助文本为 Mark messages as unread归属 Organize 分组mark-unread是其显式别名// internal/cmd/gmail.go Unread GmailUnreadCmd cmd: name:unread aliases:mark-unread group:Organize help:Mark messages as unread它在 gog gmail 父命令下的完整子命令列表中与mark-read标记已读、archive归档、trash移入垃圾箱并列构成一组消息组织操作。核心参数说明命令本身只有三个直接参数全部定义在 internal/cmd/gmail_archive.go 的GmailUnreadCmd结构体中// GmailUnreadCmd marks messages as unread. type GmailUnreadCmd struct { MessageIDs []string arg: optional: name:messageId help:Message IDs to mark as unread Query string name:query short:q help:Mark all messages matching this query as unread Max int64 name:max aliases:limit help:Max messages (with --query) default:100 }参数类型默认值说明[messageId ...]位置参数可多个可选—要标记为未读的消息 ID与--query二选一二者都缺省时命令以用法错误退出-q,--querystring—使用 Gmail 搜索查询语法匹配消息把全部命中结果标记为未读--max,--limitint64100使用--query时允许处理的最大消息数别名--limit关键行为约束来自同一文件的gmailBulkLabelOp实现必须提供目标既没有位置消息 ID、也没有--query时返回用法错误 provide message IDs or --query--max必须为正--query模式下--max 0会在发起任何 API 请求前就以退出码 2 报 --max must be 0。这一点有测试直接验证internal/cmd/gmail_archive_test.go 中的TestGmailBulkOps_QueryInvalidMaxFailsBeforeDryRun包含unread zero用例消息 ID 会被归一化位置参数先经normalizeGmailMessageIDinternal/cmd/webid.go处理因此可以容忍 Gmail Web URL 形式的输入而非裸 ID归档线程模式的测试用例中就传入了完整的https://mail.google.com/...链接并期望其被解析为 thread ID。两种典型用法按消息 ID 标记未读——把之前读过、想重新处理的邮件恢复成未读状态gog gmail unread 18ab12cd34ef5678 gog gmail unread 18ab12cd34ef5678 18ab99cd00ef1122 # 支持一次传多个用查询批量标记——例如把收件箱里发件人为某人、且本周内的邮件全部恢复未读gog gmail unread --query in:inbox from:aliceexample.com after:2026-09-09 gog gmail unread -q in:inbox older_than:7d is:read --max 50 -n # 先预览前 50 条--query使用的是 Gmail 搜索语法in:inbox、is:unread、from:、after:等与gog gmail search使用的查询语法一致。底层执行链路从 ID 到UNREAD标签gog gmail unread的Run方法只有一行核心逻辑把「加UNREAD标签」委托给共用的批量标签操作函数// internal/cmd/gmail_archive.go func (c *GmailUnreadCmd) Run(ctx context.Context, flags *RootFlags) error { return gmailBulkLabelOp(ctx, flags, c.MessageIDs, c.Query, c.Max, []string{UNREAD}, nil, marked as unread, gmail.unread) }对比同文件中的姊妹命令可以看到差异全部体现在「增/删哪些标签」上mark-read移除UNREAD标签trash加TRASH并移除INBOXarchive只移除INBOX而unread只添加UNREAD、不删除任何标签。dry-run 输出中的操作名gmail.unread也因此在测试 internal/cmd/gmail_archive_test.go 中被断言为added_labels: [UNREAD]、removed_labels: []。gmailBulkLabelOp的完整执行流程如下归一化与校验把位置参数归一化为消息 ID校验「ID 或 query 至少其一」与--max 0dry-run 拦截若带--dry-run别名--dryrun/--noop/--preview通过dryRunExitinternal/cmd/dryrun.go打印包含op、message_ids、query、max、added_labels、removed_labels的结构化请求描述后以退出码 0 结束不访问网络解析账号并构建 Gmail 客户端requireAccount(flags)依据-a/--account账号邮箱、别名或auto确定目标账号gmailService构建服务实例收集消息 ID--query模式下调用searchMessageIDs分页搜索结果与位置参数 ID 合并搜索为空则输出 No messages foundJSON 模式下输出{action:marked as unread,count:0}标签名解析为标签 IDfetchLabelNameToIDinternal/cmd/gmail_labels.go拉取账号标签列表建立名称→ID 映射再由resolveLabelIDsinternal/cmd/gmail_labels_utils.go解析。UNREAD是系统标签该步对其是幂等确认分批调用 BatchModify按每批最多 1000 个 IDGmail API 的users.messages.batchModify上限构造BatchModifyMessagesRequest{Ids, AddLabelIds: [UNREAD]}循环发送任一失败会报 batch modify failed at offset N输出结果非 JSON 模式打印Marked as unread N messages单数消息省略 sJSON 模式输出action、count、addedLabels、removedLabels四个字段的对象。搜索分页的两个细节--query模式下的searchMessageIDsinternal/cmd/gmail_archive.go有两个值得注意的工程细节每页最多取 500 条批大小取min(remaining, 500)并只请求messages(id),nextPageToken字段避免拉取消息正文重复分页令牌保护通过pageTokenGuard检测服务端异常地重复返回相同nextPageToken会导致死循环第 2 次即报错 repeated page token。internal/cmd/gmail_archive_test.go 中的TestSearchMessageIDsRejectsRepeatedPageToken、TestSearchMessageIDsRejectsRepeatedEmptyPageToken与TestGmailArchiveCmd_QueryRejectsRepeatedPageToken用假 HTTP 服务专门覆盖了这一场景。机器可读输出与 Agent 安全开关gog gmail unread继承 gogcli 全部根级标志以下与脚本/Agent 场景最相关完整列表见 docs/commands/gog-gmail-unread.md标志说明-n,--dry-run别名--dryrun/--noop/--preview不修改任何数据打印将要执行的动作并以成功码退出-j,--json别名--machine以 JSON 输出到 stdout最适合脚本消费-p,--plain别名--tsv输出稳定、可解析的 TSV 文本无颜色--results-onlyJSON 模式下只输出主结果去掉nextPageToken等外层字段--select,--pick别名--projectJSON 模式下按逗号分隔的字段路径做 best-effort 选择--wrap-untrusted在 JSON/raw 输出中为抓取到的文本字段包裹外部不可信内容标记供 Agent 消费时防提示注入--readonly运行时阻断一切变更类 API 请求配合auth add还会请求只读 OAuth 作用域--gmail-no-send拦截 Gmail 发送类操作Agent 安全开关-a,--account别名--acct指定账号邮箱、别名或auto多账号场景必用--client指定 OAuth 客户端名选择对应的存储凭据与令牌桶--access-token直接使用给定的 access token绕过存储的 refresh token约 1 小时过期--quota-project指定计费 Google Cloud 项目以X-Goog-User-Project头发送某些 API 在使用--access-token或 ADC 时必需--enable-commands/--enable-commands-exact/--disable-commands按点分路径启用/禁用命令前缀限制 CLI 可用面--no-input别名--non-interactive永不交互式提问出错即失败适合 CI--colorauto\|always\|never、-v/--verbose、--home输出着色、详细日志、覆盖配置/数据根目录等价GOG_HOME组合示例在 CI 中安全地批量恢复未读先预览再执行# 预览将影响哪些消息不联网写操作 gog gmail unread -q in:inbox from:bossexample.com --max 100 -n --json # 确认无误后正式执行仅保留主结果字段 gog gmail unread -q in:inbox from:bossexample.com --max 100 --json --results-only与相关命令的关系gog gmail mark-read同文件同机制的逆向操作移除UNREAD标签而非添加参数结构messageId...、--query、--max默认 100完全一致docs/commands/gog-gmail-mark-read.mdgog gmail archive/gog gmail trash同样走gmailBulkLabelOp区别仅在增删的标签组合archive额外提供--thread按线程操作的模式该模式不可与--query同时使用否则以退出码 2 报 --thread cannot be used with --querygog gmail search只读搜索线程unread --query是「搜索 批量改标签」的写操作版本二者共享 Gmail 查询语法命令树上下文完整的 Gmail 子命令get、send、drafts、labels、thread、settings 等见 docs/commands/gog-gmail.md全部命令索引见 docs/commands/README.md。这些文档页均由gog schema --json自动生成页首注明 Do not edit this page by hand; runmake docs-commands因此文档中的标志定义与源码中的结构体 tag 始终一致。小结gog gmail unread的语义模型非常清晰把「标记未读」实现为「批量给消息添加UNREAD系统标签」通过Users.Messages.BatchModify按 1000 条一批发送天然获得幂等性重复添加同一标签无副作用与批量效率。配合--query --max的限额机制、--dry-run预览、JSON/TSV 输出与--readonly等安全开关它既可以人工交互式使用也可以安全地嵌入脚本和 Agent 工作流例如 gogcli 的 Agent 技能gog-inbox-triage就涉及未读邮件的优先级处理参见 docs/agent-skills.md。测试文件 internal/cmd/gmail_archive_test.go 对 dry-run 请求内容、--max校验、分页令牌防死循环等均做了断言为该行为提供了可直接运行的验证依据。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
