Отправка почты из Laravel: частые ошибки новичков

К концу этой инструкции вы отправите первое письмо из Laravel через SMTP и увидите его во входящих (или в перехватчике вроде Mailtrap). На чистой настройке уйдёт 10–15 минут. Проверено на Laravel 11.x и Laravel 10.x — различия по почте между ними минимальны и отмечены отдельно.

Почта в Laravel устроена вокруг компонента Mail и драйверов транспорта. Вы описываете подключение в config/mail.php и .env, формируете класс письма (Mailable) и вызываете фасад Mail. Большинство проблем новичка — не в коде письма, а в настройке подключения и в кешировании.

Что нужно иметь до начала

• Установленный проект на Laravel 10.x или 11.x и доступ к терминалу в его корне (там, где лежит artisan).
• PHP 8.1+ для Laravel 10, PHP 8.2+ для Laravel 11.
• SMTP-доступ: хост, порт, логин и пароль. Для тестов удобно завести бесплатный ящик-песочницу (например, Mailtrap) — письма туда приходят, но реальным адресатам не уходят.
• Права на запись в файл .env и на очистку кеша конфигурации.

Если реального SMTP пока нет, для самой первой проверки подойдёт драйвер log: письмо не отправится, но запишется в лог. Это отсекает вопрос «код виноват или почтовый сервер».

Шаг 1. Прописываем подключение в .env

Откройте .env в корне проекта и заполните блок почты. Значения ниже — пример для SMTP-песочницы, подставьте свои:

MAIL_MAILER=smtp
MAIL_HOST=sandbox.smtp.example.com
MAIL_PORT=2525
MAIL_USERNAME=YOUR_SMTP_LOGIN
MAIL_PASSWORD=YOUR_SMTP_PASSWORD
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

Проверка: значения сохранены, вокруг адреса с пробелами или спецсимволами стоят двойные кавычки. Пустой MAIL_FROM_ADDRESS — частая причина ошибки при отправке, письмо без отправителя большинство серверов отклоняет.

Порт и шифрование должны совпадать

Здесь спотыкаются чаще всего. Порт и тип шифрования — это пара, а не два независимых параметра.

• Порт 587 — обычно MAIL_ENCRYPTION=tls (STARTTLS).
• Порт 465 — обычно MAIL_ENCRYPTION=ssl.
• Порт 25 или 2525 — часто без шифрования или tls, зависит от провайдера.

Если поставить порт 465 и tls, соединение зависнет и вывалится по таймауту. Точные требования смотрите в панели вашего почтового провайдера, а не угадывайте.

Шаг 2. Сбрасываем кеш конфигурации

Это тот шаг, из-за которого «я всё поменял, а ничего не изменилось». Если вы когда-либо запускали php artisan config:cache, Laravel читает настройки из закешированного файла, а не из .env. Правки в .env при этом игнорируются.

php artisan config:clear

Проверка: в терминале появится строка вроде Configuration cache cleared successfully. После этого Laravel снова читает .env напрямую.

Правило, которое экономит часы: правите .env — сразу выполняйте config:clear. На проде под config:cache любое изменение переменной окружения без пересборки кеша не подхватывается.

Шаг 3. Создаём класс письма

Mailable¹ — это класс, описывающий одно письмо: тему, отправителя и содержимое. Сгенерируйте его командой:

php artisan make:mail WelcomeMail

Файл появится в app/Mail/WelcomeMail.php. Приведите его к такому виду (синтаксис Laravel 10.x/11.x с методами envelope и content):

<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class WelcomeMail extends Mailable
{
    use Queueable, SerializesModels;

    // Данные, которые передаём в письмо
    public function __construct(public string $userName)
    {
    }

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Добро пожаловать',
        );
    }

    public function content(): Content
    {
        // Шаблон письма лежит в resources/views/emails/welcome.blade.php
        return new Content(
            view: 'emails.welcome',
        );
    }
}

Создайте шаблон resources/views/emails/welcome.blade.php:

<p>Здравствуйте, {{ $userName }}.</p>
<p>Ваш аккаунт создан.</p>

Проверка: оба файла на месте, имя view в классе (emails.welcome) через точку соответствует пути к blade-файлу.

Шаг 4. Отправляем письмо

Для теста удобно отправить прямо из tinker, не создавая маршрут:

php artisan tinker

И внутри tinker:

use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Mail;

Mail::to('test@example.com')->send(new WelcomeMail('Иван'));

Проверка: команда не выбросила исключение и вернула управление. Письмо должно появиться в вашей SMTP-песочнице через несколько секунд. Если используете драйвер log — проверьте storage/logs/laravel.log, там будет тело письма.

Ловушка с очередями

Трейт Queueable в классе письма сам по себе ничего не откладывает — письмо уходит синхронно. Но если вы вызвали Mail::to(...)->queue(...) или у вас Mailable реализует ShouldQueue, письмо кладётся в очередь. И тут новичок пишет: «tinker отработал без ошибок, а письма нет».

Причина: очередь по умолчанию (драйвер database или redis) требует запущенного воркера. Без него задание просто лежит в таблице.

• Для первых тестов держите QUEUE_CONNECTION=sync в .env — тогда всё отправляется сразу.
• Если очередь нужна, запустите воркер: php artisan queue:work — и не закрывайте терминал.

Если не получилось

Пять ошибок, которые вы реально увидите, и что с ними делать.

Если ничего не помогает, временно переключите MAIL_MAILER=log. Появилось письмо в логе — код и Mailable в порядке, проблема в SMTP. Не появилось — ищите ошибку в коде отправки или в кеше конфига.

Что делать дальше

Первое письмо ушло — дальше стоит:

• Вынести отправку в очередь через ShouldQueue, чтобы медленный SMTP не тормозил HTTP-ответ пользователю, и настроить воркер под supervisor на проде.
• Настроить SPF, DKIM и DMARC на домене отправителя — без них письма с реальных адресов уходят в спам. Это настройка DNS, а не Laravel.
• Посмотреть на драйвер failover в config/mail.php, если нужна отказоустойчивость между несколькими SMTP.

Локализация писем и вложения — отдельная тема, здесь мы довели дело только до первого доставленного письма.