Отправка писем в Битрикс: CEvent и Mail\Event

Отправка писем в 1С-Битрикс идёт через систему почтовых событий: старый класс CEvent и его современный аналог \Bitrix\Main\Mail\Event. Разберём оба варианта, чем они отличаются и как правильно передать переменные в шаблон письма.

Отправка через CEvent (D6)

<?php

CEvent::Send('NEW_ORDER', 's1', [
    'ORDER_ID' => $orderId,
    'ORDER_SUM' => $orderSum,
    'EMAIL' => $userEmail,
]);

Первый параметр — символьный код почтового события, заранее настроенного в разделе Сервисы → Почтовые события. Второй — код сайта. Третий — ассоциативный массив переменных, доступных в шаблоне письма как #ORDER_ID#, #ORDER_SUM# и так далее.

Отправка через Bitrix\Main\Mail\Event (D7)

<?php

use Bitrix\Main\Mail\Event;

Event::send([
    'EVENT_NAME' => 'NEW_ORDER',
    'LID' => 's1',
    'C_FIELDS' => [
        'ORDER_ID' => $orderId,
        'ORDER_SUM' => $orderSum,
        'EMAIL' => $userEmail,
    ],
]);

Функционально методы делают одно и то же — ищут активный почтовый шаблон для события, подставляют переменные и ставят письмо в очередь отправки. D7-вариант предпочтителен в новом коде, поскольку использует пространство имён и не требует подключения глобальных классов явным порядком, характерным для D6.

Нужна помощь с Битрикс?

Синхронная и отложенная отправка

Оба метода по умолчанию не отправляют письмо мгновенно в момент вызова — событие ставится в очередь, а фактическая отправка выполняется агентом при следующем заходе крона. Обычно это происходит в течение нескольких секунд, но при высокой нагрузке или отключённом кроне письма могут накапливаться в очереди. Проверить очередь можно в разделе Сервисы → Почтовые события → Просмотр событий.

Проверка результата отправки

<?php

use Bitrix\Main\Mail\Event;

$result = Event::send([
    'EVENT_NAME' => 'NEW_ORDER',
    'LID' => 's1',
    'C_FIELDS' => ['ORDER_ID' => $orderId],
]);

if (!$result->isSuccess()) {
    foreach ($result->getErrors() as $error) {
        AddMessage2Log($error->getMessage(), 'mail.event');
    }
}

Event::send возвращает объект результата, у которого можно проверить успешность постановки в очередь и получить список ошибок — например, если для указанного кода события не настроено ни одного активного шаблона.

Передача HTML в переменную письма

Если переменная содержит HTML-разметку (например, готовую таблицу товаров заказа), она подставится в шаблон как есть — почтовый шаблон сам решает, куда и как её вставить. Экранировать HTML в этом случае не нужно, а вот пользовательский ввод, который не должен интерпретироваться как разметка (например, имя покупателя), стоит пропускать через htmlspecialchars перед передачей, чтобы в письме не оказалось случайно вставленных тегов.

Множественные получатели одного события

Один код события может быть настроен на отправку сразу нескольким адресатам — например, уведомление о заказе клиенту и копия менеджеру. Это настраивается в самом шаблоне почтового события через поле Email отправителя и список получателей, а не через повторный вызов Event::send с разными адресами.

Частые ошибки

Опечатка в коде события. Метод не найдёт активный шаблон и письмо не отправится, а результат не проверяется в коде.
Ожидание мгновенной отправки. Письмо ставится в очередь, а не отправляется синхронно внутри вызова.
Пользовательский текст без экранирования. Ввод из формы попадает в письмо как разметка, если не был предварительно очищен.
Результат отправки не проверяется. Ошибка в настройке шаблона остаётся незамеченной, пока пользователь не пожалуется, что письмо не пришло.

Итог

Для новых проектов на 1С-Битрикс стоит использовать \Bitrix\Main\Mail\Event::send вместо устаревшего CEvent::Send — интерфейс почти идентичен, но D7-вариант возвращает объект результата с явной проверкой ошибок. В обоих случаях письмо не отправляется мгновенно, а ставится в очередь для последующей обработки агентом.

Теги: API Разработка