使用Gmail API跟踪邮件投递状态的.NET C#实现方案咨询

根据你的业务发送量级，可选择以下两种最优实现方案：

方案1：主动轮询（适合低发送量场景） #

如果单天发件量低于1000封，优先用该方案，实现成本最低：

• 首先给你的Gmail API账号新增https://www.googleapis.com/auth/gmail.metadata权限，保证可以读取邮件标签和元数据
• 调用Send接口拿到返回的outmsg.Id后，按阶梯间隔轮询查询邮件状态（首次间隔30秒，后续逐步拉长间隔，最长查询周期建议设为72小时，超过未收到退回可默认投递成功）
• 核心判定逻辑：邮件被退回时Gmail会自动给该邮件添加FAILED系统标签，同时邮件头会附带X-Failed-Recipients字段说明退回原因，查询示例代码如下：

public async Task<(bool IsBounced, string BounceReason)> CheckMailStatusAsync(GmailService service, string gmailMsgId)
{
    var getRequest = service.Users.Messages.Get("me", gmailMsgId);
    // 只请求需要的字段，降低API配额消耗
    getRequest.Fields = "labelIds,payload.headers";
    var mailInfo = await getRequest.ExecuteAsync();

    // 匹配退回标签
    if (mailInfo.LabelIds.Contains("FAILED"))
    {
        var bounceHeader = mailInfo.Payload.Headers.FirstOrDefault(h => h.Name == "X-Failed-Recipients");
        return (true, bounceHeader?.Value ?? "未知退回原因");
    }
    return (false, string.Empty);
}

• 如果需要匹配业务侧的发件记录，建议发件时在邮件头部添加自定义追踪字段，查询退回邮件时解析该字段即可快速关联业务数据

方案2：Pub/Sub推送（适合高发送量场景） #

如果单天发件量超过1000封，轮询会占用大量API配额，推荐用推送方案：

• 在Google Cloud控制台开启Pub/Sub服务，创建主题和订阅，给Gmail官方服务账号授予主题发布权限
• 调用Gmail API的Users.Watch接口绑定你的Gmail账号和Pub/Sub主题，配置仅监听FAILED标签对应的邮件新增事件
• 后端编写Pub/Sub订阅消费逻辑，收到推送后即可直接拿到退回邮件的ID，无需主动轮询
• 该方案优势是实时性高、配额消耗极低，缺点是需要额外配置Pub/Sub服务

注意：邮件本身是异步传输协议，部分服务商的退信通知可能延迟数小时甚至更久才会返回Gmail服务器，两种方案都无法做到绝对实时的状态返回。

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