Laravel通过Mailgun驱动发信设置跟踪头后未在analytics页显示怎么办？

确认实际运行的发信通道 #

• 检查.env中的MAIL_MAILER配置与config/mail.php的默认邮件驱动：
  • 如果驱动值为mailgun：Laravel 9及以上版本默认走Mailgun原生HTTP API发信，该模式下所有服务端控制参数通过API请求字段传递，你添加在Swift Message对象上的X-Mailgun-*自定义头，只会作为普通邮件头随正文发送，不会被Mailgun识别为追踪控制指令，自然无法触发统计。
  • 如果驱动值为smtp：才会走SMTP通道，此时X-Mailgun-*格式的自定义头才会被Mailgun的SMTP端点解析为控制参数。
• 注意排查静默降级问题：如果Mailgun的API密钥、发信域名配置填写错误，框架可能会自动降级到SMTP通道发信，不会抛出明确报错。

匹配对应通道的参数格式，禁止跨通道混用 #

• 走Mailgun原生API通道时，直接在Mailable的build方法中传递API专属控制参数，不需要额外添加Swift Message自定义头，正确写法示例：

  public function build()
  {
      return $this->view('emails.notify')
          ->mailgun([
              'o:tracking' => 'yes',
              'o:tracking-opens' => 'yes',
              'o:tracking-clicks' => 'yes',
              'o:tag' => ['laravel-system-send']
          ]);
  }
  

• 走SMTP通道时，所有控制参数必须用X-Mailgun-*前缀的自定义头传递，不能直接复用Postman测试时的o:*格式参数。

补全缺失的统计必填参数 #

• 仅开启追踪开关不足以让邮件出现在Analytics页面：页面的聚合统计默认优先展示打了明确标签的邮件，如果邮件没有绑定标签（API通道对应o:tag字段，SMTP通道对应X-Mailgun-Tag头），就算触发了打开、点击事件，也会被归为“未分类邮件”，在默认筛选视图中不展示。
• 修正头值格式错误：不要在头值中额外添加等号、首尾空格等多余字符，确保实际发出的邮件头为标准的[头名]: [值]格式。

排除全局配置覆盖 #

• 检查Mailgun账号下对应发信域名的全局追踪设置：如果域名层面的“默认关闭打开追踪、点击追踪”开关被开启，邮件中添加的追踪指令会被全局配置覆盖，导致追踪事件不触发。
• 检查项目全局服务提供者代码：排查是否存在全局监听Swift消息的逻辑，错误覆盖了Mailable中添加的自定义头。

核对数据查看条件 #

• Mailgun的Analytics数据存在5-15分钟的统计延迟，发信后不会立刻展示对应数据。
• 检查Analytics页面的筛选条件，确认选择了正确的发信域名、时间范围、标签匹配规则，避免因为筛选条件错误看不到对应数据。

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