Laravel Job使用dispatch调度时X-SMTPAPI头部未添加问题

我在给SendGrid邮件添加分类的X-SMTPAPI头部时遇到异常：使用dispatch_now()同步执行邮件任务时，头部能正常附加；但改用dispatch()异步调度到队列执行时，头部完全消失。

相关代码 #

路由调度代码

Route::get('send-test-email', function(){
    // ini_set("memory_limit", "2048M");
    $arr["fname"] = 'Testfirst';
    $arr["lname"] = 'Lastname';
    $arr["mail"] = 'testf1@mailinator.com';
    
    $emailJob = new SendEmail($arr);

    // dispatch_now($emailJob);
    dispatch($emailJob);
    die('ere');
});

邮件任务代码

$email = new CompleteMail($this->details);
Mail::mailer('noreply')
    ->to($this->details['mail'],$this->details['full_name'])
    ->send($email);

Mailable的build方法代码

$this->withSwiftMessage(function ($message) use ($header) {
    $message->getHeaders()->addTextHeader('X-SMTPAPI', '{"category": "EXAMPLE_CATEGORY"}');
});

原因分析 #

异步任务入队时，Mailable实例会被序列化存储到队列驱动中。withSwiftMessage的闭包回调在序列化过程中可能丢失（尤其是当队列使用JSON序列化器时），或者在队列执行环境中，SwiftMessage的构建上下文发生变化，导致回调无法触发。

解决方案 #

方案1：将头部逻辑移到任务的发送回调中

直接在任务的邮件发送代码里添加头部，绕开Mailable序列化的问题：

$email = new CompleteMail($this->details);
Mail::mailer('noreply')
    ->to($this->details['mail'], $this->details['full_name'])
    ->send($email, function ($message) {
        $message->getHeaders()->addTextHeader('X-SMTPAPI', '{"category": "EXAMPLE_CATEGORY"}');
    });

方案2：修复Mailable的序列化问题

如果坚持在Mailable内部处理，需要确保头部内容不依赖闭包引用，同时检查队列序列化配置：

1. 修改Mailable，把头部内容转为类属性：

class CompleteMail extends Mailable
{
    protected $details;
    protected $smtpApiHeader;

    public function __construct($details)
    {
        $this->details = $details;
        $this->smtpApiHeader = '{"category": "EXAMPLE_CATEGORY"}';
    }

    public function build()
    {
        $header = $this->smtpApiHeader;
        $this->withSwiftMessage(function ($message) use ($header) {
            $message->getHeaders()->addTextHeader('X-SMTPAPI', $header);
        });

        // 其他邮件构建逻辑
        return $this->view('emails.your-template');
    }
}

2. 确保队列使用PHP序列化器（避免JSON序列化丢弃闭包），在.env中设置：

QUEUE_SERIALIZER=php

方案3：使用SendGrid官方工具包

直接使用SendGrid官方提供的Laravel集成包，它会自动处理X-SMTPAPI头部的生成与附加，避免手动处理的序列化风险。配置完成后，只需在Mailable中设置分类即可。

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