Gmail API使用过滤器标记发件人邮件为垃圾邮件报错

首先明确你的第一个疑问：Gmail API的过滤器创建接口本身就不支持在addLabelIds字段传入SPAM标签，这是接口的硬限制，只是没有在公开文档里明确标注。
你通过labels.list接口查到SPAM是垃圾邮件对应的标签ID没有问题，但过滤器接口的addLabelIds只允许传入用户自定义标签、CATEGORY开头的系统分类标签，SPAM、TRASH这类由Gmail反垃圾、删除逻辑管控的系统标签，都不支持通过过滤器自动添加，你在官方调试工具里复现报错已经能证明这点，和你其余代码逻辑无关。

要实现指定发件人的后续邮件自动进入垃圾邮件箱，有两种成熟方案：

方案1：调用屏蔽发件人接口（最匹配你的需求） #

这个方案和你在Gmail网页端手动选择「屏蔽该发件人」的效果完全一致，配置完成后该地址发来的所有邮件会自动归入垃圾邮件箱，不需要你额外做轮询或实时处理，稳定性最高。
核心调用代码如下：

block_config = {
    "address": from_email
}
create_result = service.users().settings().blockedAddresses().create(
    userId='me',
    body=block_config
).execute()

接口调用成功后会返回屏蔽规则的唯一ID，后续如果需要取消屏蔽，调用对应delete接口传入该ID即可。

方案2：匹配新邮件后手动修改标签（适合复杂规则场景） #

如果你除了匹配发件人，还要叠加关键词匹配、附件判断等更复杂的规则，没法用单一的屏蔽规则覆盖，可以按如下逻辑实现：

• 要么通过watch接口订阅账号的新邮件推送，要么按固定周期拉取收件箱的未处理新邮件
• 按你的业务规则对新邮件做筛选匹配
• 对命中规则的邮件，调用messages.modify接口调整标签，这个接口是完全支持操作SPAM标签的，不会出现你之前遇到的参数错误，示例代码：

label_adjust = {
    "addLabelIds": ["SPAM"],
    "removeLabelIds": ["INBOX"]
}
service.users().messages().modify(
    userId='me',
    id=matched_message_id,
    body=label_adjust
).execute()

避坑提醒：不要尝试用过滤器把邮件转发到垃圾邮件别名地址这类偏方，很容易触发账号的风控限制，稳定性极差。

内容的提问来源于stack exchange，提问作者Alenna Spiro