HTML邮件中Tracking Pixel打开时无法触发API端点的问题求助

我正在实现一套邮件追踪系统，将Tracking Pixel嵌入HTML邮件内容中。目前遇到的问题是：Tracking Pixel可在HTML中正常渲染，但打开邮件时关联的API端点并未被触发。

已通过本地HTML文件测试该端点，在浏览器中打开时可成功触发API端点，但将相同HTML内容作为邮件发送后，端点并未被访问。

以下是配置概述：

端点代码 #

@app.get("/track_open/{unique_id}")
def track_open(request: Request, unique_id: str, db: Session = Depends(get_db)):
    pixel = base64.b64decode("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7")
    try:
        tracking_unique_id = get_tracking_unique_id(db, unique_id)
        print(request.headers)
        if not tracking_unique_id.opened_at:
            tracking_unique_id.opened_at = datetime.datetime.now()
            db.add(tracking_unique_id)
            db.commit()
            return PlainTextResponse(content=pixel, media_type="image/gif")
        else:
            print("Already opened")
    except Exception as e:
        print(f"No Tracking record found: {str(e)}")
        return {"status": "error", "message": str(e)}

追踪URL代码片段 #

base_url = "http://127.0.0.1:8000"
# Generate the tracking pixel url
click_tracking_url = f"{base_url}/track_click/{unique_id}"
open_tracking_url = f"{base_url}/track_open/{unique_id}"

# Search for the links in the email body
soup = BeautifulSoup(content, "html.parser")
urls = [a["href"] for a in soup.find_all("a", href=True)]

# If there are links or urls in the email body, inject our click tracking url to that original link
if urls:
    for url in urls:
        # make the final tracking url
        tracking_url = f"{click_tracking_url}?url={url}"
        new_message = new_message.replace(f"{url}", f"{tracking_url}")

else:
    print("No URLs found in the email content")

# Create the email content with tracking pixel image
open_tracking_img = (
    f"<img src='{open_tracking_url}' width='1' height='1' border='0'>"
)

new_message += open_tracking_img

邮件内容 #

<h1> Weekly News  <a href="https://www.w3schools.com">Visit W3Schools.com!</a> </h1>

可能的原因 #

• 本地地址无法被邮件客户端访问：你的base_url使用http://127.0.0.1:8000，这是本地回环地址，仅本机可访问。邮件客户端运行在其他设备（甚至同一设备的沙箱环境）时，无法连接到该端点。
• 邮件客户端默认屏蔽外部图片：主流邮件客户端（Outlook、Gmail、Apple Mail等）默认阻止加载外部图片，需用户手动点击“显示图片”才会触发像素请求。
• HTTP协议被拦截：多数邮件客户端仅允许加载HTTPS资源，你的端点使用HTTP，可能被直接拦截。
• 像素标签语法兼容性问题：用单引号包裹src属性虽符合HTML规范，但部分邮件客户端解析器对单引号兼容性差，建议换成双引号。
• 异常场景未返回有效像素：若tracking_unique_id不存在或抛出异常，端点返回JSON而非图片，邮件客户端会忽略无效响应，不会记录请求。

HTML邮件中Tracking Pixel的特殊注意事项 #

• 使用公网可访问的HTTPS地址：确保追踪端点域名可公网解析且启用HTTPS，避免被客户端拦截。
• 始终返回标准1x1像素GIF：无论追踪是否成功，都要返回有效的1x1透明GIF，避免邮件客户端显示错误占位符；重复打开时也需返回像素，而非其他响应。
• 优化像素标签写法：用双引号包裹属性，添加空alt属性避免显示替代文本，可加style="display:none;"进一步隐藏：

  <img src="https://your-domain.com/track_open/xxx" width="1" height="1" border="0" alt="" style="display:none;">
  

• 处理客户端缓存：在URL末尾添加随机参数（如?t={timestamp}），避免邮件客户端缓存像素导致重复打开不触发请求。
• 尊重用户隐私设置：部分用户会永久禁用外部图片加载或使用隐私保护模式，此时追踪像素无法触发，需接受这种场景。
• 禁用JavaScript依赖：邮件客户端普遍禁用JavaScript，追踪必须依赖图片加载的纯HTML机制，不能用JS触发请求。

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