Laravel集成Mandrill/Mailchimp邮件发送的错误处理与状态排查咨询

一、先搞懂Mail::failures()为啥一直是空的 #

Laravel自带的Mail::failures()数组，只记录SwiftMailer直接投递时无法送达收件人服务器的情况——但你用的是Mandrill驱动，逻辑完全不一样：只要Laravel能把邮件请求成功发送到Mandrill的API，SwiftMailer就认为“投递完成”，所以failures()会是空的。真正的邮件投递失败（比如收件人邮箱不存在、服务器拒收）是Mandrill后台异步处理的，不会返回到Laravel的这个数组里。

二、邮件发送错误的两类处理方式 #

1. 即时错误（提交到Mandrill时的失败） #

这类错误是同步发生的，能直接通过try/catch捕获，除了你已经处理的Swift_RfcComplianceException（邮箱格式错）和Swift_TransportException（连接Mandrill失败），还要加上Mandrill自身的API异常：

try {
    Mail::send('emails.template', $data, function ($message) use ($to) {
        $message->to($to)
                ->subject('你的邮件主题');
    });

    // 走到这一步=请求已成功提交给Mandrill，进入队列等待投递
    Log::info("邮件请求已提交至Mandrill，收件人：{$to}");
} catch (Swift_RfcComplianceException $e) {
    // 收件人邮箱格式非法
    Log::error("邮箱格式错误：{$to}，详情：{$e->getMessage()}");
} catch (Swift_TransportException $e) {
    // 无法连接Mandrill服务器，或API请求被拒绝（比如网络问题）
    Log::error("邮件传输失败：{$e->getMessage()}");
} catch (\Mandrill_Error $e) {
    // Mandrill API返回的业务错误：比如密钥无效、发送配额不足、参数错误
    Log::error("Mandrill API错误：{$e->getMessage()}");
} catch (\Exception $e) {
    // 兜底捕获所有未预料的错误
    Log::error("邮件发送未知错误：{$e->getMessage()}");
}

2. 异步错误（Mandrill投递后的失败） #

Mandrill是异步处理投递的，Laravel提交请求后无法立刻知道最终结果，必须用Webhook接收状态通知：

• 登录Mandrill后台，找到Webhooks配置，添加你的Laravel项目接收地址，勾选需要监听的事件：sent（投递成功）、hard_bounce（永久失败）、soft_bounce（临时失败）、reject（Mandrill拒收）等。
• 在Laravel中写一个接口接收Webhook的POST请求，验证请求合法性（避免伪造），然后更新邮件状态到数据库或日志：

public function handleMandrillWebhook(Request $request) {
    // 验证Mandrill签名（必做，防止恶意请求）
    $signature = $request->header('X-Mandrill-Signature');
    $webhookKey = config('services.mandrill.webhook_key');
    $webhookUrl = route('mandrill.webhook');
    $payload = $request->all();

    // 用Mandrill提供的方法验证签名
    $isValid = \Mandrill::verifyWebhookSignature($signature, $webhookKey, $webhookUrl, $payload);
    if (!$isValid) {
        abort(403, '无效的Webhook请求');
    }

    // 处理每个事件
    foreach ($request->input('events') as $event) {
        $email = $event['msg']['email'];
        $status = $event['event'];
        $failReason = $event['msg']['bounce_description'] ?? '无详细原因';

        // 这里可以更新数据库中对应邮件的状态
        // 示例：MailLog::where('recipient_email', $email)->update(['status' => $status, 'reason' => $failReason]);
        Log::info("邮件状态更新：{$email} → {$status}，原因：{$failReason}");
    }

    return response()->json(['status' => 'success']);
}

三、怎么判断邮件是否真的发送成功 #

分两个阶段：

1. 提交成功 #

当Mail::send()没有抛出异常，说明邮件请求已经成功传给Mandrill，进入了Mandrill的发送队列——这只是“提交成功”，不代表收件人已经收到。

2. 最终投递成功 #

必须依赖Mandrill的Webhook事件：

• sent事件：邮件已成功投递到收件人的邮箱服务器
• hard_bounce：永久失败（比如邮箱不存在、域名无效）
• soft_bounce：临时失败（比如收件人邮箱已满、服务器暂时不可用）
• reject：Mandrill直接拒绝发送（比如收件人在黑名单、邮件内容触发垃圾邮件规则）

如果需要查询单个邮件的状态，也可以用Mandrill的messages/infoAPI，传入邮件的Mandrill ID。这个ID可以在Laravel发送后获取：

$mandrillMessageId = null;

Mail::send('emails.template', $data, function ($message) use ($to) {
    $message->to($to)->subject('测试邮件');
});

// 获取Mandrill返回的消息ID
$transport = Mail::getSwiftMailer()->getTransport();
if ($transport instanceof \Swift_MandrillTransport) {
    $response = $transport->getLastResponse();
    $mandrillResponse = json_decode($response, true);
    $mandrillMessageId = $mandrillResponse[0]['_id'] ?? null;
}

// 之后可以用这个ID调用Mandrill的messages/info接口查询状态

四、实用建议 #

• 建一个邮件日志表：记录每封邮件的收件人、提交时间、Mandrill消息ID、初始状态（提交成功/失败），再通过Webhook更新最终状态，方便后续排查问题。
• 自动清理硬 bounce 的邮箱：一旦收到hard_bounce事件，就把对应邮箱从你的邮件列表中移除，避免浪费发送配额，同时降低Mandrill的退信率。
• 定期看Mandrill后台报告：里面有详细的投递统计、退信率、垃圾邮件投诉数据，能帮你优化邮件内容和发送策略。

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