使用Gmail API编程发信显示已发送但未送达的问题求助

AI 小北

2026-6-21

问题解决方案：Gmail API发送邮件显示已发送但收件人未收到

先明确几个猜测的验证结果

猜测2排除：Gmail API的messages.send接口是实际触发邮件投递流程的，并非仅添加“SENT”标签。客户端显示已发送，说明Google已接收并标记该邮件为已发送状态。
猜测3优先级最高：未发布的测试模式Google Cloud应用，Gmail API会限制仅能发送给OAuth同意屏幕中添加的测试用户。如果收件人不在测试列表内，邮件会被Google拦截，不会投递到收件方服务器。
猜测1确实可能：邮件头的Received字段是Gmail API自动添加的，本身不会直接导致拦截，但如果你的域名未配置正确的邮件认证（SPF/DKIM/DMARC），会让收件方系统判定邮件来源可疑而丢弃。

具体解决步骤

1. 将Google Cloud应用从测试模式切换到生产模式

登录Google Cloud Console，打开你的项目
导航到API和服务 > OAuth同意屏幕
点击“发布应用”，完成OAuth应用验证流程（需提供应用信息、隐私政策链接等）
发布后，应用不再受测试用户限制，可发送邮件给任意收件人

2. 检查并完善域名邮件认证配置（SPF/DKIM/DMARC）

因为你使用的是公司域名绑定Gmail的邮箱，必须确保DNS记录配置正确：

SPF记录：添加或更新域名的TXT记录为：
```
v=spf1 include:_spf.google.com ~all
```
DKIM配置：
1. 登录Google Workspace管理控制台（admin.google.com）
2. 导航到应用 > Google Workspace > Gmail > 已验证的域
3. 选择你的域名，点击“生成新的DKIM密钥”
4. 将生成的DKIM密钥添加到域名的DNS TXT记录中
DMARC记录：添加域名的TXT记录，指导收件方处理未通过认证的邮件，示例：
```
v=DMARC1; p=quarantine; sp=quarantine; rua=mailto:dmarc@yourdomain.in
```

3. 优化邮件构造代码

当前代码存在几个可能影响邮件可信度的问题，调整如下：

取消注释HTML内容的添加，确保邮件同时包含纯文本和HTML版本（符合RFC标准，提升邮件可信度）
确保From字段使用已验证的域名邮箱，与Gmail配置一致

调整后的create_general_message函数示例：

def create_general_message(username, to_email, from_email):
    # 使用MIMEMultipart支持多部分内容
    message = MIMEMultipart('alternative')
    message['Subject'] = f'Namaste {username}'
    message['From'] = from_email
    message['To'] = to_email
    # 添加纯文本内容
    text_content = 'Menu'
    message.attach(MIMEText(text_content, 'plain'))
    # 添加HTML内容
    with open('Email Code.html', 'r') as file:
        html_content = file.read()
    message.attach(MIMEText(html_content, 'html'))
    # 生成base64编码的raw内容
    return {"raw": base64.urlsafe_b64encode(message.as_bytes()).decode()}

4. 验证邮件投递状态

发送邮件后，调用Gmail API获取邮件详情，检查关键头信息：

# 在send_message.execute()后添加
message_detail = service.users().messages().get(userId="me", id=send_message["id"], format="full").execute()
# 打印关键头信息
for header in message_detail['payload']['headers']:
    if header['name'] in ['X-Gm-Message-State', 'X-Failed-Recipients', 'Authentication-Results']:
        print(f"{header['name']}: {header['value']}")

X-Gm-Message-State：如果包含sent，说明Google已成功投递
Authentication-Results：可查看SPF/DKIM是否通过认证
X-Failed-Recipients：如果存在，说明收件方服务器退回了邮件，会显示退回原因

测试建议

先发送邮件到你自己的另一个邮箱（比如个人Gmail），查看邮件的“显示原始内容”，确认SPF/DKIM认证结果
检查收件邮箱的垃圾邮件、已删除邮件和被拦截邮件文件夹
使用邮件检测工具验证域名的SPF/DKIM/DMARC配置是否正确

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