Laravel框架集成Mailgun发送邮件报501错误如何解决

问题现象 #

基于Laravel框架开发的应用，在使用Mailgun作为邮件服务提供商实现自动发信功能时，触发生产环境报错，核心报错信息如下：

[2022-06-25 13:52:41] production.ERROR: Expected response code "250/251/252" but got code "501", with message "501 Invalid command or cannot parse to address". {"exception":"[object] (Symfony\\Component\\Mailer\\Exception\\TransportException(code: 501): Expected response code \"250/251/252\" but got code \"501\", with message \"501 Invalid command or cannot parse to address\". at /var/www/main/vendor/symfony/mailer/Transport/Smtp/SmtpTransport.php:308)
[stacktrace]
#0 /var/www/main/vendor/symfony/mailer/Transport/Smtp/SmtpTransport.php(182): Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport->assertResponseCode()
#1 /var/www/main/vendor/symfony/mailer/Transport/Smtp/SmtpTransport.php(240): Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport->executeCommand()
#2 /var/www/main/vendor/symfony/mailer/Transport/Smtp/SmtpTransport.php(201): Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport->doRcptToCommand()
#3 /var/www/main/vendor/symfony/mailer/Transport/AbstractTransport.php(68): Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport->doSend()
#4 /var/www/main/vendor/symfony/mailer/Transport/Smtp/SmtpTransport.php(136): Symfony\\Component\\Mailer\\Transport\\AbstractTransport->send()
#5 /var/www/main/vendor/laravel/framework/src/Illuminate/Mail/Mailer.php(521): Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport->send()
#6 /var/www/main/vendor/laravel/framework/src/Illuminate/Mail/Mailer.php(285): Illuminate\\Mail\\Mailer->sendSymfonyMessage()
#7 /var/www/main/vendor/laravel/framework/src/Illuminate/Mail/Mailable.php(210): Illuminate\\Mail\\Mailer->send()
#8 /var/www/main/vendor/laravel/framework/src/Illuminate/Support/Traits/Localizable.php(19): Illuminate\\Mail\\Mailable->Illuminate\\Mail\\{closure}()
#9 /var/www/main/vendor/laravel/framework/src/Illuminate/Mail/Mailable.php(211): Illuminate\\Mail\\Mailable->withLocale()
#10 /var/www/main/vendor/laravel/framework/src/Illuminate/Mail/Mailer.php(307): Illuminate\\Mail\\Mailable->send()
#11 /var/www/main/vendor/laravel/framework/src/Illuminate/Mail/Mailer.php(253): Illuminate\\Mail\\Mailer->sendMailable()
#12 /var/www/main/vendor/laravel/framework/src/Illuminate/Mail/PendingMail.php(124): Illuminate\\Mail\\Mailer->send()
#13 /var/www/main/app/Http/Controllers/MetricController.php(39): Illuminate\\Mail\\PendingMail->send()
......（剩余堆栈省略）

从堆栈可以定位到，报错触发点是MetricController.php的sendEmailWithCoupon方法调用发信逻辑时，SMTP协议执行RCPT TO（指定收件人）命令被服务端拒绝。

根因说明 #

SMTP返回的501 Invalid command or cannot parse to address错误，核心原因是发信请求里携带的邮箱地址不合法，Mailgun的SMTP服务无法解析，和邮件内容、服务连通性无关。

排查&修复方案 #

按优先级逐一排查以下场景即可解决：

• 检查报错对应的控制器方法（app/Http/Controllers/MetricController.php第39行附近）的发信代码，打印所有传入to()（收件人）、cc()（抄送人）、bcc()（密送人）、from()（发件人）方法的参数，确认不存在空值、null、非字符串类型的非法值，没有传入全角字符、中文、多余空格、缺@后缀的格式错误邮箱。
• 检查.env中的邮件配置项：确认MAIL_FROM_ADDRESS配置为合法邮箱格式，没有多余的引号、空格；MAIL_HOST、MAIL_PORT、MAIL_USERNAME、MAIL_PASSWORD和Mailgun后台对应区域的SMTP参数完全匹配，欧盟区和美国区的凭据不可混用。
• 如果需要发送带收件人姓名的邮件，不要手动拼接"姓名 <邮箱>"格式的字符串，使用Laravel官方支持的参数格式传参，避免特殊字符未做RFC编码导致解析失败：

// 单个带姓名的收件人正确写法
Mail::to('user@example.com', '张某某')->send(new CouponMailable());

// 批量收件人正确写法
$recipients = [
    ['email' => 'user1@example.com', 'name' => '用户1'],
    ['email' => 'user2@example.com', 'name' => '用户2']
];
$mail = Mail::to($recipients[0]['email'], $recipients[0]['name']);
foreach (array_slice($recipients, 1) as $recipient) {
    $mail->cc($recipient['email'], $recipient['name']);
}
$mail->send(new CouponMailable());

• 本地调试时可临时将MAIL_DRIVER改为log，触发发信后查看storage/logs下的日志，检查生成的邮件头里所有地址字段是否合法，排除隐式传入的非法地址（比如全局配置的回复地址、系统退信地址配置错误）。

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