如何在PHP中通过Gmail API追踪邮件送达、打开、点击、退信等状态

一、官方API能力说明 #

谷歌提供了对应的程序化邮件状态追踪能力，根据账号类型不同可选用的接口有差异：

• 若为Google Workspace管理员账号，可使用Reports API Gmail Activity 报告接口拉取域内发送邮件的系统级状态，包括投递成功、退信、被拦截等，需要额外申请https://www.googleapis.com/auth/admin.reports.audit.readonly权限，数据更新最多有15分钟延迟
• 若为个人Gmail账号，无法使用管理员级别的Reports API，只能通过原生Gmail API搭配自行埋点实现状态追踪

二、各类状态的具体实现方法 #

1. 退信（Bounced）、被拦截（Blocked）、送达状态 #

• 方案1（低延迟）：通过users.watch接口为发件人邮箱配置webhook，监听发件人收件箱的新邮件通知。退信、拦截通知都会以系统邮件形式发送到发件人地址，收到新邮件后判断是否为退信/拦截通知，解析内容匹配对应原始邮件ID即可更新状态
• 方案2（无需配置webhook）：定时调用$service->users_messages->get接口拉取已发送邮件的详情，判断返回结果的labelIds字段，若包含BOUNCE、FAILED标签即可判定为退信/发送失败；若收到收件方的已读回执也可作为送达参考，注意已读回执需要收件方主动确认才会返回

2. 已打开（Opened）、已点击（Clicked）状态 #

Gmail API原生没有提供这类用户行为的追踪能力，需要在邮件内容层自行埋点实现：

• 打开追踪：在邮件HTML内容中插入1px尺寸的透明像素图片，图片地址为你的业务服务端接口，地址参数携带当前邮件的唯一标识，用户打开邮件加载图片时会触发你的接口请求，即可记录打开事件
• 点击追踪：将邮件内所有跳转链接替换为你的业务服务端跳转接口地址，参数携带原始跳转链接与当前邮件唯一标识，用户点击链接时先请求你的接口记录点击事件，再通过302重定向到原始链接即可
  注意：若收件方邮箱默认禁用图片加载，打开追踪会存在统计误差，属于邮件追踪的通用限制

三、现有代码适配建议 #

你当前的发送逻辑无需做大幅调整，仅需要在调用sendMessage拿到返回结果后，将结果返回的邮件唯一ID与业务侧的邮件记录做关联存储即可，后续所有状态匹配都可以通过这个ID关联。

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