Почтовые события в Битрикс: очередь, cron или сразу

Вы вызываете CEvent::Send, функция возвращает ID, а письма в ящике нет. Или оно приходит с большой задержкой, когда клиент уже написал в поддержку. Причина почти всегда одна: в Битрикс почтовое событие не равно отправке. Ниже три способа доставить письмо, цена каждого и места, где всё ломается. Ориентир: «1С-Битрикс: Управление сайтом», ядро main 22.x и новее, PHP 8.x. Перед боем прогоните примеры на копии сайта.

Путь письма: три остановки

Вызов Send ничего не отправляет. Он ставит событие в очередь.

1. Код вызывает CEvent::Send или Bitrix\Main\Mail\Event::send. Событие с полями попадает в таблицу b_event. Метод возвращает ID записи, а не результат отправки.
2. Агент или cron берёт необработанные события, ищет активные шаблоны по типу события и сайту (LID), подставляет поля.
3. Готовое письмо уходит в mail() или в переопределённую вами custom_mail.

Ломаться может на любой остановке, и диагностика у каждой своя.

Send возвращает ID записи в очереди, а не факт отправки. Проверка результата в коде после него проверяет очередь, а не почту.

Три способа доставки

Очередь и агенты на хитах

Режим по умолчанию: очередь разбирается в обычных запросах посетителей. Настройка не нужна, но на тихом сайте письмо ждёт следующего хита, а медленный SMTP может затормозить чужой запрос.

<?php
use Bitrix\Main\Mail\Event;

// Ставим письмо в очередь: запись попадает в b_event
$result = Event::send([
    'EVENT_NAME' => 'MYSHOP_CALLBACK_REQUEST',
    'LID'        => 's1',
    'C_FIELDS'   => [
        'EMAIL_TO' => 'manager@example.com',
        'NAME'     => 'Анна',
        'PHONE'    => '+7 000 000-00-00',
    ],
]);

if (!$result->isSuccess()) {
    // Это ошибка постановки в очередь, а не отправки
    AddMessage2Log(implode('; ', $result->getErrorMessages()), 'myshop');
}

Очередь и cron

Вызовы те же, меняется только запускающий механизм. Агенты уходят с хитов на cron. Выигрыш: письма уходят вне запросов посетителей и с понятной задержкой. Цена: cron становится критичной точкой, потому что вместе с ним встают все агенты сайта, а не только почта.

// bitrix/php_interface/dbconn.php
define('BX_CRONTAB_SUPPORT', true);

* * * * * /usr/bin/php -f /var/www/example/bitrix/modules/main/tools/cron_events.php

Путь к php и к сайту замените своими. Подробности о режиме агентов на cron смотрите в документации вашей версии.

Немедленная отправка

Event::sendImmediate принимает тот же массив параметров, но отправляет письмо в текущем запросе. Подходит для письма, без которого пользователь не двинется дальше: код подтверждения, сброс пароля. Цена: человек ждёт ответа SMTP-сервера, а возвращаемое значение и ошибки нужно проверять самим. Какие значения возвращает метод, сверьте в документации своей версии.

Сравнение способов

Когда что выбирать

• Есть доступ к cron на сервере: очередь и cron для всех обычных писем. Это базовый вариант для магазина.
• Хостинг без cron и живой трафик: агенты на хитах, но следите за задержкой.
• Пользователь не может продолжить без письма (код, сброс пароля): sendImmediate только для таких писем, остальное в очередь.

Что ломается

• Событие есть, письма нет. Нет активного шаблона под этот тип события и сайт, либо LID в вызове не совпадает с привязкой шаблона.
• Приходит два одинаковых письма. На один тип события для сайта активны два шаблона, уходят оба.
• Лишние копии. Параметр DUPLICATE по умолчанию равен Y, и при заданном адресе копий в настройках главного модуля письмо уйдёт и туда.
• Очередь растёт. Включён BX_CRONTAB_SUPPORT, а cron не запущен или упал. Проверьте запросом ниже.
• Письма в спаме. Отправка через mail() без SPF и DKIM. Обычное решение: SMTP через custom_mail в init.php (сигнатуру сверьте с документацией). Настройка DNS-записей здесь не разбирается.
• Тестовая копия пишет клиентам. База из бэкапа содержит реальные адреса, и первый же тестовый заказ уходит настоящему покупателю.

-- Необработанные события: если число растёт, очередь не разбирается
-- Имена полей сверьте через DESCRIBE b_event на своей версии
SELECT ID, EVENT_NAME, LID, DATE_INSERT, SUCCESS_EXEC
FROM b_event
WHERE SUCCESS_EXEC = 'N'
ORDER BY ID
LIMIT 20;

От последней проблемы защищает обработчик в /local/php_interface/init.php. Возврат false из OnBeforeEventAdd отменяет добавление события. Константу MYSHOP_IS_PROD определите сами, например в dbconn.php боевого сервера.

<?php
use Bitrix\Main\EventManager;

EventManager::getInstance()->addEventHandler(
    'main',
    'OnBeforeEventAdd',
    function (&$event, &$lid, &$arFields, &$messageId, &$files, &$languageId) {
        // На копии сайта письма в очередь не ставим
        if (!defined('MYSHOP_IS_PROD') || MYSHOP_IS_PROD !== true) {
            return false;
        }
    }
);

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

Начните с трёх проверок на боевом сайте:

1. Выполните запрос выше и посмотрите, сколько событий висит необработанными.
2. Измерьте задержку: разницу между DATE_INSERT и DATE_EXEC у свежих записей. Если она больше минуты, переводите очередь на cron.
3. Добавьте обработчик против отправки с тестовых копий. Настройка SPF, DKIM и DMARC для домена отправителя и инвалидация очереди после сбоя SMTP остаются отдельными темами.

Агент — функция ядра Битрикс, которая выполняется по расписанию: на хите посетителя или по cron. Разбор очереди почтовых событий делает именно такой агент. LID — идентификатор сайта в Битрикс, например s1.