如何在GCP Compute Engine实例中用Python调用Gmail API发送邮件

核心原因 #

你选择的服务账号（机器人账号）属于服务器到服务器认证，但Gmail API是用户专属服务，服务账号本身没有关联Gmail邮箱，必须通过域范围授权模拟Google Workspace（原G Suite）域内的用户身份，才能调用Gmail API发送邮件。直接使用users/me会因服务账号无对应邮箱触发预检查失败。

完整实现步骤 #

1. 配置域范围授权（需Google Workspace管理员操作） #

• 进入Google Cloud控制台，找到目标服务账号，复制其客户端ID（在服务账号详情页的「高级」板块）。
• 登录Google Workspace管理员后台，进入安全 > API控制 > 域范围授权。
• 添加新授权：
  • 粘贴服务账号的客户端ID。
  • 输入Gmail API授权范围：https://mail.google.com/,https://www.googleapis.com/auth/gmail.send
  • 勾选「启用」并保存。

2. 配置GCE实例服务账号权限 #

• 返回GCP控制台，找到目标Compute Engine实例，编辑实例详情。
• 在「服务账号」板块，确认选择的是已配置域范围授权的服务账号，且该账号拥有roles/iam.serviceAccountTokenCreator权限（用于生成模拟用户的凭证）。

3. 修正Python代码 #

替换原有认证逻辑，实现服务账号模拟用户身份，示例代码如下：

from google.oauth2 import service_account
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
import base64
from email.mime.text import MIMEText

# 需模拟的Google Workspace域内有效用户邮箱
USER_EMAIL = "your-user@your-domain.com"
# 最小化授权范围（仅发送邮件）
SCOPES = ["https://www.googleapis.com/auth/gmail.send"]

def create_message(sender, to, subject, message_text):
    """构造邮件消息"""
    message = MIMEText(message_text)
    message["to"] = to
    message["from"] = sender
    message["subject"] = subject
    raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
    return {"raw": raw}

def send_message(service, user_id, message):
    """发送邮件"""
    try:
        message = service.users().messages().send(userId=user_id, body=message).execute()
        print(f"邮件发送成功，ID: {message['id']}")
        return message
    except HttpError as error:
        print(f"发送失败: {error}")
        return None

def main():
    # 从GCE元数据服务器自动获取服务账号凭证，无需本地密钥文件
    credentials = service_account.Credentials.from_service_account_info(
        {},  # 空字典表示读取元数据服务器的凭证
        scopes=SCOPES,
        subject=USER_EMAIL  # 关键：指定要模拟的用户身份
    )
    
    # 构建Gmail API服务实例
    service = build("gmail", "v1", credentials=credentials)
    
    # 创建并发送测试邮件
    message = create_message(USER_EMAIL, "recipient@example.com", "测试邮件", "这是通过GCE服务账号模拟用户发送的测试邮件")
    send_message(service, USER_EMAIL, message)

if __name__ == "__main__":
    main()

4. 关键注意事项 #

• 必须使用Google Workspace账号：个人Gmail账号无法配置域范围授权，仅企业/教育版Google Workspace支持该功能。
• 不可省略subject参数：这是服务账号切换到用户身份的核心配置，缺失会导致仍以服务账号自身身份调用API，触发原错误。
• 权限最小化原则：仅发送邮件时，使用https://www.googleapis.com/auth/gmail.send范围即可，无需全邮箱权限。
• 元数据服务器访问：确保GCE实例所在网络允许访问元数据服务器（默认开启，私有网络需确认路由配置）。

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