如何通过Python调用Gmail API设置邮件委派？

一、「Installed App」是什么？ #

Installed App（安装型应用）是Google OAuth 2.0定义的客户端类型，专门给运行在本地设备（电脑、手机）的应用用的，和部署在服务器上的Web App对应。这类应用的凭据是单独生成的JSON文件，和服务账号的凭据格式完全不同——你现在用服务账号的凭据套了原本给Installed App写的代码，才会触发ValueError: Client secrets must be for a web or installed app这个错误。

二、问题根源：代码逻辑和凭据类型不匹配 #

你之前的操作方向是对的：设置邮件委派的Gmail API Scope确实要求用带全域权限的服务账号，但你复用了Google Quickstart里给桌面应用写的OAuth授权代码，这套代码只认Installed App/OAuth Web App的凭据，根本处理不了服务账号的JSON文件。

三、修复步骤 #

1. 先确认服务账号配置没问题 #

• 确保在Google Workspace管理后台给服务账号开了全域委派，并且添加了正确的Scope：https://www.googleapis.com/auth/gmail.settings.sharing（这是设置邮件委派必须的Scope）
• 下载的是服务账号的凭据文件（从「IAM与管理」→「服务账号」页面生成的，不是OAuth客户端的凭据）

2. 重写授权逻辑适配服务账号 #

放弃Quickstart里的桌面应用OAuth流程，改用服务账号的域委派授权，核心代码示例：

from google.oauth2 import service_account
from googleapiclient.discovery import build

# 配置参数
SCOPES = ['https://www.googleapis.com/auth/gmail.settings.sharing']
# 替换成你的服务账号凭据路径
SERVICE_ACCOUNT_KEY_PATH = './service-account-key.json'
# 替换成你要操作的域内用户邮箱（服务账号需要代这个用户执行操作）
TARGET_USER = 'john@yourdomain.com'
# 替换成要设置的委派邮箱
DELEGATE_EMAIL = 'jane@yourdomain.com'

# 加载服务账号凭据并生成委派授权
credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_KEY_PATH, scopes=SCOPES
)
# 关键：指定要模拟的域内用户
delegated_creds = credentials.with_subject(TARGET_USER)

# 构建Gmail API客户端
gmail_service = build('gmail', 'v1', credentials=delegated_creds)

# 执行设置委派操作
delegation_body = {
    'delegateEmail': DELEGATE_EMAIL,
    'verificationStatus': 'accepted'
}
response = gmail_service.users().settings().delegates().create(
    userId=TARGET_USER, body=delegation_body
).execute()

print(f"委派设置成功：{response}")

3. 核心注意点 #

• 服务账号本身没有独立的邮箱权限，必须通过with_subject()指定域内的一个有效用户（这个用户需要有管理自身邮件委派的权限）
• 两类凭据别搞混：
  • 桌面应用OAuth凭据：包含client_id、client_secret字段
  • 服务账号凭据：包含client_email、private_key字段

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