Gmail API权限问题：无法拉取非Workspace邮箱邮件

这个错误的核心原因是个人Gmail账号不支持服务账号的域范围委派功能，而你给公司Workspace邮箱配置的是域范围委派模式，两者的认证逻辑完全不同：

关键差异 #

Workspace域管理员可以给服务账号配置域范围委派，让服务账号模拟域内任意用户调用API；但个人Gmail账号没有域管理权限，无法使用这种模式，必须走标准的OAuth 2.0授权流程，让用户主动授权你的应用访问其邮箱数据。

具体修复步骤 #

1. 切换认证流程
   放弃服务账号的with_subject模拟用户方式，改用OAuth 2.0授权码流程：

   • 在Google Cloud Console中，创建一个桌面应用或网页应用类型的OAuth客户端ID（不是服务账号），下载client_secret.json文件。
   • 用以下逻辑获取授权后的凭据：

     from google_auth_oauthlib.flow import InstalledAppFlow
     from googleapiclient.discovery import build
     
     # 按需调整权限范围，比如只读用gmail.readonly
     SCOPES = ['https://www.googleapis.com/auth/gmail.readonly']
     
     flow = InstalledAppFlow.from_client_secrets_file(
         'client_secret.json', SCOPES)
     # 启动本地服务器引导用户授权
     credentials = flow.run_local_server(port=0)
     
     # 构建Gmail服务并调用
     service = build('gmail', 'v1', credentials=credentials)
     messages = service.users().messages().list(userId='me').execute()
     

2. 验证权限范围
   确保请求的scopes是个人账号允许的，避免使用Workspace专属的高权限范围（比如全域管理类权限）。常用的邮件读取范围gmail.readonly、gmail.modify等个人账号都支持。

3. 清除无效凭据缓存
   如果之前代码里缓存了服务账号的凭据，要删除相关缓存文件（比如token.json），避免新的授权流程被旧凭据干扰。

常见误区 #

• 不要尝试给个人账号配置域范围委派：这个功能仅对Workspace域开放，个人账号在Cloud Console里找不到相关配置入口。
• 服务账号无法直接访问个人Gmail数据：个人账号的API访问必须经过用户主动授权，不能通过服务账号静默访问。

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