使用Gmail API与服务账号时预检查失败问题求助

问题核心 #

切换到通过gcloud配置的应用默认环境变量后，使用服务账号模拟域内用户发送邮件时触发FAILED_PRECONDITION（400）错误，此前直接使用服务账号密钥文件可正常发送。

关键原因与解决方案 #

1. 应用默认凭据的身份类型错误 #

gcloud默认执行auth application-default login生成的是个人Google用户凭据，而非服务账号凭据，这类用户凭据不支持域委派的用户模拟操作。而之前使用的服务账号密钥属于服务账号身份，具备域委派权限。

修复方式：
使用服务账号身份生成应用默认凭据，执行以下命令：

gcloud auth application-default login --impersonate-service-account=你的服务账号邮箱@你的项目ID.iam.gserviceaccount.com

如果是在非GCP环境运行，也可以直接设置环境变量指定服务账号密钥文件（符合应用默认凭据的加载逻辑）：

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/你的服务账号密钥文件.json"

2. API调用的用户参数不匹配 #

代码中调用send("me", message)时，"me"会解析为当前凭据对应的身份：

• 用服务账号密钥时，createDelegated("no-reply@mydomain.com")会让"me"指向被模拟的用户，因此正常；
• 用应用默认的用户凭据时，"me"指向的是登录的个人用户，而非目标模拟账号，触发预检查失败。

修复方式：
明确指定目标用户邮箱，替换代码中的"me"：

Message sentMessage = service.users().messages().send("no-reply@mydomain.com", message).execute();

3. 验证域委派与IAM权限 #

• 确认Admin控制台中，服务账号已被授予https://www.googleapis.com/auth/gmail.send的域委派范围；
• 确认服务账号已被分配Service Account Token Creator IAM角色（该角色是服务账号模拟域内用户的必需权限）；
• 确认被模拟的no-reply@mydomain.com账号本身具备Gmail发送权限。

修改后的核心代码片段 #

try {
    // 明确指定被模拟的用户邮箱，而非使用"me"
    Message sentMessage = service.users().messages().send("no-reply@mydomain.com", message).execute();
    System.out.println("Message id: " + sentMessage.getId());
    System.out.println(sentMessage.toPrettyString());
} catch (GoogleJsonResponseException e) {
    GoogleJsonError error = e.getDetails();
    if (error.getCode() == 403) {
        System.err.println("Unable to send message: " + e.getDetails());
    } else {
        throw e;
    }
}

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