Laravel中Mailgun自定义标签添加失败问题排查求助

尝试为邮件添加自定义Mailgun标签，参考Laravel官方文档及诸多示例但始终无法生效。TestMail类代码如下：

<?php

namespace App\Mail;

use App\Models\User;
use Illuminate\Mail\Mailable;

class TestMail extends Mailable
{
    public function build()
    {
        echo 'build';

        $this->withSymfonyMessage(function ($message) {
            echo 'tag';
            $message->getHeaders()->addTextHeader('X-Mailgun-Tag', 'test');
        });

        return $this;
    }

    public function handle(User $recipient)
    {
        $body = 'test body';
        $subject = 'test subject';

        $this->html($body);
        $this->subject($subject);
        $this->from(config('mail.from.default.address'), config('mail.from.default.name'));
        $this->to($recipient->email, $recipient->first_name);

        return $this;
    }
}

执行时能看到build输出，却看不到tag输出；邮件可正常发送至Mailgun，但日志中的tags数组为空。需解决两个问题：

1. 如何检查Laravel发送的邮件是否已附加X-Mailgun-Tag头部？
2. Mailgun端是否需要额外开启相关配置？

一、修复withSymfonyMessage闭包不执行的问题 #

你的代码中使用了自定义的handle方法设置邮件参数，但Laravel的Mailable类依赖build方法完成邮件构建流程。withSymfonyMessage注册的回调只会在Laravel内部处理Symfony邮件实例时触发，若跳过标准构建流程直接调用handle，回调不会执行。

调整代码如下：

class TestMail extends Mailable
{
    protected $recipient;

    // 通过构造函数传入收件人
    public function __construct(User $recipient)
    {
        $this->recipient = $recipient;
    }

    public function build()
    {
        echo 'build';

        // 把原handle中的邮件配置逻辑移到build方法内
        $this->html('test body')
             ->subject('test subject')
             ->from(config('mail.from.default.address'), config('mail.from.default.name'))
             ->to($this->recipient->email, $this->recipient->first_name);

        $this->withSymfonyMessage(function ($message) {
            echo 'tag';
            $message->getHeaders()->addTextHeader('X-Mailgun-Tag', 'test');
        });

        return $this;
    }
}

调用方式：使用Laravel标准邮件发送流程，确保build方法被正确触发：

Mail::to($user)->send(new TestMail($user));

二、检查邮件头部的三种方法 #

1. 本地日志记录
   修改.env配置，将邮件发送改为日志模式：

   MAIL_MAILER=log
   

   发送邮件后，打开storage/logs/laravel.log，搜索X-Mailgun-Tag即可确认头部是否存在。

2. 拦截SMTP请求
   使用Mailhog、Charles等工具拦截SMTP请求，查看邮件原始头部内容，直接验证X-Mailgun-Tag是否已添加。

3. 回调内打印头部
   在withSymfonyMessage闭包中直接打印头部信息到日志：

   $this->withSymfonyMessage(function ($message) {
       $headers = $message->getHeaders();
       $headers->addTextHeader('X-Mailgun-Tag', 'test');
       // 输出所有头部到laravel日志
       logger($headers->toString());
       echo 'tag';
   });
   

   查看storage/logs/laravel.log即可看到完整头部信息。

三、Mailgun端配置说明 #

Mailgun无需额外开启配置，只要请求携带符合规则的X-Mailgun-Tag头部，标签就会被识别并显示在日志中。注意两个限制：

• 单封邮件最多添加3个标签，超出部分会被忽略。
• 标签名称仅支持字母、数字、下划线、连字符，长度不超过128字符。

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