无法通过GCP服务账号获取带路由转发的Google Workspace账号Gmail历史记录

在GCP项目中使用已启用全域委派的服务账号监控两个Google Workspace账号的收件箱，遇到以下异常：

• 调用users.getProfile可成功获取账号基本信息（含邮件总数、线程数等）；
• 调用users.history.list接口时，传入旧的startHistoryId仅返回新的historyId，无具体历史记录；
• 其他普通Workspace账号可正常获取历史记录，仅这两个启用**邮件路由转发（保留原收件箱）**的账号出现问题。

相关代码及返回结果：

获取账号信息代码 #

def authenticate_gmail_api():
    """Authenticates and returns the Gmail API service."""
    creds = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, 
                                                                  scopes=SCOPES,
                                                                  subject=USER_EMAIL) 
    return build('gmail', 'v1', credentials=creds)

service = authenticate_gmail_api()
profile = service.users().getProfile(userId='me').execute()
print(profile)

返回结果：

{'emailAddress': 'monitor1@example.com', 'messagesTotal': 1375, 'threadsTotal': 405, 'historyId': '252086'}

获取历史记录代码 #

history_response = service.users().history().list(
    userId='me',
    startHistoryId=start_history_id
).execute()

print("History Response:", history_response)

返回结果：

History Response: {'historyId': '252155'}

1. 明确指定historyTypes参数 #

users.history.list默认不会返回所有类型的历史事件，转发类账号需明确指定要捕获的事件类型。修改调用代码：

history_response = service.users().history().list(
    userId='me',
    startHistoryId=start_history_id,
    historyTypes=['messageAdded', 'messageDeleted', 'labelAdded', 'labelRemoved']
).execute()

可根据监控需求选择对应事件类型，比如仅关注新增邮件可只填['messageAdded']。

2. 验证startHistoryId有效性 #

若传入的startHistoryId过于陈旧，超出Gmail历史记录保留期限，API会直接返回最新historyId而无数据。可：

• 使用users.getProfile返回的最新historyId作为起始点；
• 向目标账号发送测试邮件，再调用history.list检查是否能捕获到messageAdded事件。

3. 确认服务账号权限配置 #

在Google Admin Console中检查：

• 服务账号的全域委派已配置正确的Gmail API权限范围，至少包含https://www.googleapis.com/auth/gmail.readonly；
• 全域委派授权已覆盖这两个目标账号，无访问限制。

4. 排查邮件转发规则细节 #

联系Workspace管理员确认：

• 转发规则是否勾选“在原收件箱保留邮件副本”；
• 是否存在自动过滤规则（如自动归档、标记垃圾邮件）导致邮件未触发收件箱历史记录；
• 路由规则是否直接转发邮件而未经过目标账号的Gmail收件箱（这种情况不会生成Gmail历史记录）。

5. 测试单条邮件访问权限 #

调用users.messages.get验证服务账号是否能读取目标账号的邮件内容：

message = service.users().messages().get(userId='me', id='MESSAGE_ID').execute()
print(message)

若能正常获取邮件详情，说明权限无问题，问题出在历史记录获取逻辑；若无法获取，需重新排查权限或账号配置。

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