Gmail API OAuth 2.0令牌过期：Post SMTP连接间歇性失败

问题描述 #

我在WordPress站点上使用Post SMTP插件集成Gmail API，初始设置和配置过程顺利，连接后一切正常。但遇到一个反复出现的问题：连接在几天后会失败，报错信息如下：

"error": {
  "code": 401,
  "message": "Request is missing required authentication credential. Expected OAuth 2 access token, login cookie or other valid authentication credential.",
  "errors": [
    {
      "message": "Login Required.",
      "domain": "global",
      "reason": "required",
      "location": "Authorization",
      "locationType": "header"
    }
  ],
  "status": "UNAUTHENTICATED",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "CREDENTIALS_MISSING",
      "domain": "googleapis.com",
      "metadata": {
        "service": "gmail.googleapis.com",
        "method": "caribou.api.proto.MailboxService.SendMessage"
      }
    }
  ]
}

关键信息 #

• 重新建立连接后可恢复，但几天后会再次失败。
• 未修改Gmail账户密码。
• 使用免费Gmail账户，邮件发送量远低于每日配额。
• 错误显示凭据缺失/无效，但OAuth令牌未被显式撤销，理论上应持续有效。

已尝试操作 #

• 确认无密码修改或可疑活动触发令牌撤销。
• 检查Gmail安全设置及OAuth应用权限，未发现异常。
• 查看Post SMTP日志，重新连接可临时解决问题，但会复发。

疑问 #

是什么原因导致OAuth令牌间歇性过期或失效？Post SMTP插件在令牌刷新或存储处理方面是否存在已知问题？

一、OAuth令牌失效的核心原因 #

1. 刷新令牌过期：免费Gmail账户的OAuth刷新令牌默认有效期为7天，即使未显式撤销，到期后也会自动失效。Post SMTP若未正确触发刷新流程，就会出现凭据缺失错误。
2. 插件令牌存储/刷新逻辑问题：Post SMTP部分版本存在刷新令牌未正确存储或自动刷新失败的bug，尤其是在站点启用缓存插件（如WP Rocket、W3 Total Cache）时，缓存可能干扰插件的令牌更新机制。
3. Google安全机制触发：即使未改密码，Google的异常活动检测（如异地登录、设备变更）可能静默撤销刷新令牌；另外，若OAuth应用处于"测试模式"，Google会限制令牌有效期（通常7天），且仅允许添加的测试用户使用。

二、Post SMTP插件的已知问题 #

部分用户反馈，Post SMTP在以下场景会出现令牌刷新故障：

• 站点启用了对象缓存（如Redis、Memcached），插件的令牌数据被缓存后无法及时更新。
• 插件的"OAuth 2.0设置"中，未正确勾选"自动刷新令牌"选项（部分版本默认未开启）。
• 旧版本插件存在刷新令牌请求格式错误，导致Google拒绝返回新的访问令牌。

三、解决步骤 #

1. 检查OAuth应用状态：登录Google Cloud Console，确认你的应用已从"测试模式"切换为"生产模式"，避免令牌7天过期限制。
2. 调整插件设置：
   • 进入Post SMTP的"邮件发送设置"，找到OAuth 2.0配置项，确保"自动刷新令牌"已勾选。
   • 禁用站点中可能干扰插件的缓存功能，或在缓存规则中排除Post SMTP的令牌存储路径（通常是wp_options表中以postsmtp_开头的选项）。
3. 更新插件版本：升级Post SMTP到最新稳定版，修复已知的令牌刷新bug。
4. 重置OAuth连接：完全移除现有连接，重新进行Gmail API授权流程，确保获取到有效的长期刷新令牌。
5. 检查Google账户安全日志：登录Gmail账户的"安全活动"页面，查看是否有令牌被撤销的记录，排查是否存在异常登录或权限变更。

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