gogcligog gmail mark-read命令详解在终端批量将 Gmail 邮件标记为已读【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog gmail mark-read是 gogcliGoogle Workspace in your terminal提供的 Gmail 邮件整理命令用于将一个或多个消息标记为已读也支持通过 Gmail 搜索语法按条件批量处理。本文以 gog-gmail-mark-read.md 为骨架结合 internal/cmd/gmail_archive.go 等源码讲解该命令的完整用法、全部参数含义、底层批处理原理GmailBatchModifyMessagesAPI 与标签解析机制以及它与gog gmail unread、gog gmail archive等相邻命令的组合实战。读完本文你将能够在终端中完成单封/多封/按查询批量三种粒度的已读标记并掌握--dry-run、--json、--plain等输出与安全控制手段。命令概览定位、别名与所属分组在 gogcli 的命令树中mark-read是gog gmail的组织整理Organize子命令与archive归档、unread标记未读、thread线程操作同组。从 gmail.go 的注册代码可以看到它的完整定义Read GmailReadCmd cmd: name:mark-read aliases:read-messages group:Organize help:Mark messages as read命令定义中包含三层别名方便不同习惯的开发者调用顶层命令gmail的别名是mail、email子命令mark-read的别名是read-messages因此官方 Usage 中写明了等价写法gog gmail (mail,email) mark-read (read-messages) [messageId ...] [flags]。例如以下四条命令完全等价gog gmail mark-read 18f2a3b4c5d6e7f8 gog gmail mail mark-read 18f2a3b4c5d6e7f8 gog gmail email read-messages 18f2a3b4c5d6e7f8 gog email read-messages 18f2a3b4c5d6e7f8基本用法按消息 ID 标记已读命令的核心参数是[messageId ...]——一个或多个消息 ID支持同时传入多个# 标记单个消息为已读 gog gmail mark-read 18f2a3b4c5d6e7f8 # 一次标记多个消息 gog gmail mark-read 18f2a3b4c5d6e7f8 18f2a3b4c5d6e7f9 18f2a3b4c5d6e7fa从源码看消息 ID 在进入批处理前会经过normalizeGmailMessageIDwebid.go规范化该函数会识别 Gmail 网页版链接并提取其中真正的消息 ID。也就是说如果你从浏览器地址栏复制了形如https://mail.google.com/mail/u/0/#inbox/18f2a3b4c5d6e7f8的链接或包含message_id、msg、permmsgid查询参数的长链接命令也能自动解析出十六进制 ID 后照常工作无需手动抠 ID。按查询批量标记--query 与 --max只传 ID 适合精确操作要批量清理收件箱时用-q/--query传入 Gmail 搜索语法即可把匹配到的消息全部标记为已读# 将来自某发件人的全部邮件标记为已读 gog gmail mark-read --query from:newsletterexample.com # 将 7 天前的促销类邮件标记为已读 gog gmail mark-read --query category:promotions older_than:7d # 仅处理前 50 封匹配邮件默认上限 100 gog gmail mark-read --query label:unread in:inbox --max 50--max/--limit默认100用于限制批量处理的规模避免一次改动过多邮件。底层通过 searchMessageIDs 分页拉取匹配的消息 ID每页最多 500 条用nextPageToken翻页只请求messages(id),nextPageToken字段凑齐--max上限后停止因此批量场景下也只会改动查询匹配且数量受限的消息。需要注意的是消息 ID 与查询二选一即可但至少提供其一。若两者都为空源码会直接返回provide message IDs or --query的用法错误若提供了--query但--max不大于 0同样会返回--max must be 0的校验错误见 gmail_archive.go。完整 Flags 参考以下是gog gmail mark-read支持的全部标志与文档一致按用途分组说明。目标选择Flag类型默认值说明[messageId ...]string列表要标记为已读的消息 ID位置参数-q--querystring将匹配该 Gmail 搜索查询的所有消息标记为已读--max--limitint64100配合--query时的最大消息数身份与认证Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时过期-a--account--acctstring账户邮箱、别名或auto用于已认证的 Google API 命令--clientstringOAuth 客户端名称选择存储的凭据和令牌桶--quota-projectstring用于计费的 Google Cloud 项目以X-Goog-User-Project头发送与--access-token或 ADC 配合时部分 API 需要行为与安全控制Flag类型默认值说明-n--dry-run--dryrun--noop--previewbool不实际改动打印预期操作并以成功状态退出-y--force--assume-yes--yesbool跳过破坏性命令的确认--readonlyboolfalse在运行时阻止修改类 API 请求auth add也会请求只读 OAuth scope--gmail-no-sendboolfalse阻止 Gmail 发送类操作Agent 安全开关--disable-commandsstring逗号分隔的禁用命令列表支持点路径--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI 可用范围--enable-commands-exactstring逗号分隔的精确启用命令列表父命令不会自动启用子命令--no-input--non-interactive--noninteractivebool永不提示无法继续时直接失败适合 CI输出格式Flag类型默认值说明-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本化-p--plain--tsvboolfalse向 stdout 输出稳定、可解析的纯文本TSV无颜色--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径。多数命令推荐用--fields--wrap-untrustedboolfalseJSON/raw 输出中将抓取的文本字段包上外部不可信内容标记--colorstringauto颜色输出auto\|always\|never全局通用Flag类型默认值说明-h--helpkong.helpFlag显示上下文相关的帮助信息--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出底层原理一次批量标记的完整调用链GmailReadCmd.Rungmail_archive.go的实现非常简洁它把所有工作委托给了共享的批处理函数gmailBulkLabelOpfunc (c *GmailReadCmd) Run(ctx context.Context, flags *RootFlags) error { return gmailBulkLabelOp(ctx, flags, c.MessageIDs, c.Query, c.Max, nil, []string{UNREAD}, marked as read, gmail.read) }这里的参数值得展开解释addLabels为nil不新增标签removeLabels为[UNREAD]——标记为已读在 Gmail 标签体系中的本质就是从消息上移除UNREAD标签。与之对称gog gmail unread别名mark-unread则是addLabels[UNREAD], removeLabelsnil。理解了这一点就能明白为什么标记已读的最终落点是 Gmail API 的Users.Messages.BatchModify。gmailBulkLabelOpgmail_archive.go的完整流程如下规范化 ID对传入的每个消息 ID 调用normalizeGmailMessageID过滤空值入参校验ID 和--query至少提供一个--max必须大于 0Dry-run 短路若开启--dry-run调用dryRunExitdryrun.go打印message_ids、query、max、added_labels、removed_labels、action等预期操作并以退出码 0 结束——此阶段不会触碰认证/钥匙串也不会发出任何 API 请求非常适合在脚本中先做安全检查认证与服务通过requireAccount(flags)选定账户再gmailService(ctx, account)建立 Gmail 服务收集 ID若给了--query用searchMessageIDs分页搜索每页 500 条字段裁剪为messages(id),nextPageToken再与显式传入的 ID 合并若最终没有 IDJSON 模式输出{action:marked as read,count:0}文本模式输出No messages found并正常返回标签解析fetchLabelNameToIDgmail_labels.go拉取账户标签名到 ID 的映射resolveLabelIDsgmail_labels_utils.go把UNREAD这类标签名解析成标签 ID分批修改将 ID 列表按每 1000 个一批切分GmailBatchModifyMessages的单次上限构造gmail.BatchModifyMessagesRequest{Ids, RemoveLabelIds}并调用svc.Users.Messages.BatchModify(me, req)gmail_archive.go任一偏移处失败都会带上batch modify failed at offset N的错误信息结果输出JSON 模式输出action、count、addedLabels、removedLabels文本模式输出如Marked as read 3 messagescapitalizeFirst对动作词首字母大写。输出示例# 文本输出 $ gog gmail mark-read 18f2a3b4c5d6e7f8 18f2a3b4c5d6e7f9 Marked as read 2 messages # JSON 输出--json $ gog gmail mark-read --query from:alertsexample.com --max 10 --json {action:marked as read,count:10,addedLabels:[],removedLabels:[UNREAD]} # 干跑模式--dry-run不发出任何请求 $ gog gmail mark-read 18f2a3b4c5d6e7f8 --dry-run # 输出包含 message_ids / query / max / action / 标签信息的预期操作描述批量上限与分页值得注意的工程细节在searchMessageIDs批量处理上限虽然默认 100、可用--max调大但搜索分页单页最多 500 条而BatchModifyMessages每次最多 1000 个 ID因此超大规模批量会被自动切分为多个 API 调用命令在循环中累加total并在最终结果中如实汇报处理总数。与其他命令的组合工作流mark-read属于Organize分组与相邻命令形成完整的邮件整理工具箱gog gmail search别名find/query/ls/list先用搜索确认待处理范围再决定是否批量已读mark-read的--query与gog gmail search使用相同的 Gmail 查询语法两者可相互验证匹配集合gog gmail unread别名mark-unread标记未读与mark-read在标签操作上互为镜像加/减UNREADgog gmail archive归档移除INBOX标签可将已读 归档串联完成收件箱清零gog gmail messages/gog gmail thread面向单条消息或线程的更细粒度操作如thread支持按线程整体修改。典型场景——把收件箱里所有来自自动通知的发件人的邮件读掉并归档# 先预览匹配数量干跑不真正改动 gog gmail mark-read --query from:noreplyexample.com --max 500 --dry-run # 确认无误后批量标记已读 gog gmail mark-read --query from:noreplyexample.com --max 500 # 结合归档命令清理收件箱 gog gmail archive --query from:noreplyexample.com --max 500在 CI 或 Agent 场景下建议固定使用--no-input遇到需要交互的确认时直接失败而非挂起、--json结构化解析配合--dry-run先验证再执行并通过--gmail-no-send、--readonly或--enable-commands收紧命令执行边界。注意事项与边界条件必须提供消息 ID 或--query否则命令报用法错误二者都提供时--query匹配的 ID 会排在显式 ID 之前被处理--query模式下--max必须大于 0否则报--max must be 0标记已读是修改类操作会被--readonly模式在运行时拦截如需只读审计请改用gog gmail get、gog gmail raw、gog gmail search等 Read 组命令单次 API 调用上限 1000 条、搜索单页 500 条是 Gmail API 的限制命令内部已自动分页/分块处理无需用户干预mark-read只移除UNREAD标签不会移动邮件位置、不会删除邮件清空收件箱请配合archive删除请使用gog gmail trash未登录或令牌失效时命令会经由requireAccount报出认证错误请先用gog auth add/gog auth list确认账户状态。相关文档父命令gog gmail命令索引Command index镜像命令gog gmail unread、gog gmail archive、gog gmail trash的文档位于 docs/commands 目录下对应文件实现源码internal/cmd/gmail_archive.go、internal/cmd/gmail.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gogcli `gog gmail mark-read` 命令详解：在终端批量将 Gmail 邮件标记为已读
gogcligog gmail mark-read命令详解在终端批量将 Gmail 邮件标记为已读【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog gmail mark-read是 gogcliGoogle Workspace in your terminal提供的 Gmail 邮件整理命令用于将一个或多个消息标记为已读也支持通过 Gmail 搜索语法按条件批量处理。本文以 gog-gmail-mark-read.md 为骨架结合 internal/cmd/gmail_archive.go 等源码讲解该命令的完整用法、全部参数含义、底层批处理原理GmailBatchModifyMessagesAPI 与标签解析机制以及它与gog gmail unread、gog gmail archive等相邻命令的组合实战。读完本文你将能够在终端中完成单封/多封/按查询批量三种粒度的已读标记并掌握--dry-run、--json、--plain等输出与安全控制手段。命令概览定位、别名与所属分组在 gogcli 的命令树中mark-read是gog gmail的组织整理Organize子命令与archive归档、unread标记未读、thread线程操作同组。从 gmail.go 的注册代码可以看到它的完整定义Read GmailReadCmd cmd: name:mark-read aliases:read-messages group:Organize help:Mark messages as read命令定义中包含三层别名方便不同习惯的开发者调用顶层命令gmail的别名是mail、email子命令mark-read的别名是read-messages因此官方 Usage 中写明了等价写法gog gmail (mail,email) mark-read (read-messages) [messageId ...] [flags]。例如以下四条命令完全等价gog gmail mark-read 18f2a3b4c5d6e7f8 gog gmail mail mark-read 18f2a3b4c5d6e7f8 gog gmail email read-messages 18f2a3b4c5d6e7f8 gog email read-messages 18f2a3b4c5d6e7f8基本用法按消息 ID 标记已读命令的核心参数是[messageId ...]——一个或多个消息 ID支持同时传入多个# 标记单个消息为已读 gog gmail mark-read 18f2a3b4c5d6e7f8 # 一次标记多个消息 gog gmail mark-read 18f2a3b4c5d6e7f8 18f2a3b4c5d6e7f9 18f2a3b4c5d6e7fa从源码看消息 ID 在进入批处理前会经过normalizeGmailMessageIDwebid.go规范化该函数会识别 Gmail 网页版链接并提取其中真正的消息 ID。也就是说如果你从浏览器地址栏复制了形如https://mail.google.com/mail/u/0/#inbox/18f2a3b4c5d6e7f8的链接或包含message_id、msg、permmsgid查询参数的长链接命令也能自动解析出十六进制 ID 后照常工作无需手动抠 ID。按查询批量标记--query 与 --max只传 ID 适合精确操作要批量清理收件箱时用-q/--query传入 Gmail 搜索语法即可把匹配到的消息全部标记为已读# 将来自某发件人的全部邮件标记为已读 gog gmail mark-read --query from:newsletterexample.com # 将 7 天前的促销类邮件标记为已读 gog gmail mark-read --query category:promotions older_than:7d # 仅处理前 50 封匹配邮件默认上限 100 gog gmail mark-read --query label:unread in:inbox --max 50--max/--limit默认100用于限制批量处理的规模避免一次改动过多邮件。底层通过 searchMessageIDs 分页拉取匹配的消息 ID每页最多 500 条用nextPageToken翻页只请求messages(id),nextPageToken字段凑齐--max上限后停止因此批量场景下也只会改动查询匹配且数量受限的消息。需要注意的是消息 ID 与查询二选一即可但至少提供其一。若两者都为空源码会直接返回provide message IDs or --query的用法错误若提供了--query但--max不大于 0同样会返回--max must be 0的校验错误见 gmail_archive.go。完整 Flags 参考以下是gog gmail mark-read支持的全部标志与文档一致按用途分组说明。目标选择Flag类型默认值说明[messageId ...]string列表要标记为已读的消息 ID位置参数-q--querystring将匹配该 Gmail 搜索查询的所有消息标记为已读--max--limitint64100配合--query时的最大消息数身份与认证Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时过期-a--account--acctstring账户邮箱、别名或auto用于已认证的 Google API 命令--clientstringOAuth 客户端名称选择存储的凭据和令牌桶--quota-projectstring用于计费的 Google Cloud 项目以X-Goog-User-Project头发送与--access-token或 ADC 配合时部分 API 需要行为与安全控制Flag类型默认值说明-n--dry-run--dryrun--noop--previewbool不实际改动打印预期操作并以成功状态退出-y--force--assume-yes--yesbool跳过破坏性命令的确认--readonlyboolfalse在运行时阻止修改类 API 请求auth add也会请求只读 OAuth scope--gmail-no-sendboolfalse阻止 Gmail 发送类操作Agent 安全开关--disable-commandsstring逗号分隔的禁用命令列表支持点路径--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI 可用范围--enable-commands-exactstring逗号分隔的精确启用命令列表父命令不会自动启用子命令--no-input--non-interactive--noninteractivebool永不提示无法继续时直接失败适合 CI输出格式Flag类型默认值说明-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本化-p--plain--tsvboolfalse向 stdout 输出稳定、可解析的纯文本TSV无颜色--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径。多数命令推荐用--fields--wrap-untrustedboolfalseJSON/raw 输出中将抓取的文本字段包上外部不可信内容标记--colorstringauto颜色输出auto\|always\|never全局通用Flag类型默认值说明-h--helpkong.helpFlag显示上下文相关的帮助信息--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出底层原理一次批量标记的完整调用链GmailReadCmd.Rungmail_archive.go的实现非常简洁它把所有工作委托给了共享的批处理函数gmailBulkLabelOpfunc (c *GmailReadCmd) Run(ctx context.Context, flags *RootFlags) error { return gmailBulkLabelOp(ctx, flags, c.MessageIDs, c.Query, c.Max, nil, []string{UNREAD}, marked as read, gmail.read) }这里的参数值得展开解释addLabels为nil不新增标签removeLabels为[UNREAD]——标记为已读在 Gmail 标签体系中的本质就是从消息上移除UNREAD标签。与之对称gog gmail unread别名mark-unread则是addLabels[UNREAD], removeLabelsnil。理解了这一点就能明白为什么标记已读的最终落点是 Gmail API 的Users.Messages.BatchModify。gmailBulkLabelOpgmail_archive.go的完整流程如下规范化 ID对传入的每个消息 ID 调用normalizeGmailMessageID过滤空值入参校验ID 和--query至少提供一个--max必须大于 0Dry-run 短路若开启--dry-run调用dryRunExitdryrun.go打印message_ids、query、max、added_labels、removed_labels、action等预期操作并以退出码 0 结束——此阶段不会触碰认证/钥匙串也不会发出任何 API 请求非常适合在脚本中先做安全检查认证与服务通过requireAccount(flags)选定账户再gmailService(ctx, account)建立 Gmail 服务收集 ID若给了--query用searchMessageIDs分页搜索每页 500 条字段裁剪为messages(id),nextPageToken再与显式传入的 ID 合并若最终没有 IDJSON 模式输出{action:marked as read,count:0}文本模式输出No messages found并正常返回标签解析fetchLabelNameToIDgmail_labels.go拉取账户标签名到 ID 的映射resolveLabelIDsgmail_labels_utils.go把UNREAD这类标签名解析成标签 ID分批修改将 ID 列表按每 1000 个一批切分GmailBatchModifyMessages的单次上限构造gmail.BatchModifyMessagesRequest{Ids, RemoveLabelIds}并调用svc.Users.Messages.BatchModify(me, req)gmail_archive.go任一偏移处失败都会带上batch modify failed at offset N的错误信息结果输出JSON 模式输出action、count、addedLabels、removedLabels文本模式输出如Marked as read 3 messagescapitalizeFirst对动作词首字母大写。输出示例# 文本输出 $ gog gmail mark-read 18f2a3b4c5d6e7f8 18f2a3b4c5d6e7f9 Marked as read 2 messages # JSON 输出--json $ gog gmail mark-read --query from:alertsexample.com --max 10 --json {action:marked as read,count:10,addedLabels:[],removedLabels:[UNREAD]} # 干跑模式--dry-run不发出任何请求 $ gog gmail mark-read 18f2a3b4c5d6e7f8 --dry-run # 输出包含 message_ids / query / max / action / 标签信息的预期操作描述批量上限与分页值得注意的工程细节在searchMessageIDs批量处理上限虽然默认 100、可用--max调大但搜索分页单页最多 500 条而BatchModifyMessages每次最多 1000 个 ID因此超大规模批量会被自动切分为多个 API 调用命令在循环中累加total并在最终结果中如实汇报处理总数。与其他命令的组合工作流mark-read属于Organize分组与相邻命令形成完整的邮件整理工具箱gog gmail search别名find/query/ls/list先用搜索确认待处理范围再决定是否批量已读mark-read的--query与gog gmail search使用相同的 Gmail 查询语法两者可相互验证匹配集合gog gmail unread别名mark-unread标记未读与mark-read在标签操作上互为镜像加/减UNREADgog gmail archive归档移除INBOX标签可将已读 归档串联完成收件箱清零gog gmail messages/gog gmail thread面向单条消息或线程的更细粒度操作如thread支持按线程整体修改。典型场景——把收件箱里所有来自自动通知的发件人的邮件读掉并归档# 先预览匹配数量干跑不真正改动 gog gmail mark-read --query from:noreplyexample.com --max 500 --dry-run # 确认无误后批量标记已读 gog gmail mark-read --query from:noreplyexample.com --max 500 # 结合归档命令清理收件箱 gog gmail archive --query from:noreplyexample.com --max 500在 CI 或 Agent 场景下建议固定使用--no-input遇到需要交互的确认时直接失败而非挂起、--json结构化解析配合--dry-run先验证再执行并通过--gmail-no-send、--readonly或--enable-commands收紧命令执行边界。注意事项与边界条件必须提供消息 ID 或--query否则命令报用法错误二者都提供时--query匹配的 ID 会排在显式 ID 之前被处理--query模式下--max必须大于 0否则报--max must be 0标记已读是修改类操作会被--readonly模式在运行时拦截如需只读审计请改用gog gmail get、gog gmail raw、gog gmail search等 Read 组命令单次 API 调用上限 1000 条、搜索单页 500 条是 Gmail API 的限制命令内部已自动分页/分块处理无需用户干预mark-read只移除UNREAD标签不会移动邮件位置、不会删除邮件清空收件箱请配合archive删除请使用gog gmail trash未登录或令牌失效时命令会经由requireAccount报出认证错误请先用gog auth add/gog auth list确认账户状态。相关文档父命令gog gmail命令索引Command index镜像命令gog gmail unread、gog gmail archive、gog gmail trash的文档位于 docs/commands 目录下对应文件实现源码internal/cmd/gmail_archive.go、internal/cmd/gmail.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考