使用服务账号连接Gmail API时遇Error 400: failedPrecondition错误求助

问题根源 #

你碰到的Error 400: Precondition check failed., failedPrecondition，本质是服务账号无法合法访问指定的Gmail资源，核心问题出在域范围委派配置不到位和代码中目标用户指定错误。

修复步骤 #

1. 修正代码中的目标用户 #

服务账号本身没有Gmail邮箱，不能用"me"指代，必须明确指定要访问的域内真实用户邮箱（比如user@yourdomain.com）。修改代码：

resp, err := gmailService.Users.Messages.List("user@yourdomain.com").Do()

2. 补全域范围委派的关键配置 #

你已经做了全域授权，但要确认两个细节：

• 配置时填写的客户端ID必须是服务账号自己的（可在服务账号详情页找到，不是OAuth客户端的ID）。
• 作用域保留https://www.googleapis.com/auth/gmail.readonly即可，多余的modify和mail.google.com/权限没必要，也解决不了问题。

3. 调整服务账号权限配置 #

给服务账号分配群组管理员角色完全没用，这个角色和Gmail访问无关。不需要给服务账号额外加Workspace角色，只要确保你要模拟的域内用户本身能正常使用Gmail就行。另外，务必在Google Cloud控制台的服务账号详情页，开启域范围委派开关（这步很容易漏）。

4. 验证凭证与环境变量 #

• 确认GOOGLE_APPLICATION_CREDENTIALS环境变量指向的是正确的服务账号JSON密钥文件，路径没写错。
• 可以加一行代码验证环境变量是否加载正常：

fmt.Println("Credentials path:", os.Getenv("GOOGLE_APPLICATION_CREDENTIALS"))

5. 显式指定模拟用户（可选，更稳定） #

为了确保服务账号正确模拟目标用户，创建Gmail服务时可以显式加上模拟配置：

gmailService, err := gmail.NewService(context.Background(),
    option.WithScopes(gmail.GmailReadonlyScope),
    option.WithCredentialsFile(os.Getenv("GOOGLE_APPLICATION_CREDENTIALS")),
    option.WithSubject("user@yourdomain.com"), // 这里填要模拟的用户邮箱
)

验证 #

改完后重启应用，运行代码看是否能正常返回邮件列表。

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