Свои поля в почтовом событии: передача параметров

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

Регистрация нового типа почтового события

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

Программная регистрация типа события

<?php

use Bitrix\Main\Loader;

Loader::includeModule('main');

$eventType = new CEventType;

$eventType->Add([
    'LID' => 's1',
    'EVENT_NAME' => 'CUSTOM_LOYALTY_BONUS',
    'NAME' => 'Начисление бонусов лояльности',
    'DESCRIPTION' => '#NAME# — имя клиента; #BONUS_AMOUNT# — сумма начисления; #TOTAL_BONUS# — общий баланс',
]);

Программная регистрация типа события удобна для установки собственного модуля, когда список типов событий должен создаваться автоматически при установке, а не требовать ручной настройки администратором после установки модуля через интерфейс.

Отправка события с произвольными переменными

<?php

use Bitrix\Main\Mail\Event;

Event::send([
    'EVENT_NAME' => 'CUSTOM_LOYALTY_BONUS',
    'LID' => 's1',
    'C_FIELDS' => [
        'EMAIL' => $userEmail,
        'NAME' => $userName,
        'BONUS_AMOUNT' => $bonusAmount,
        'TOTAL_BONUS' => $totalBonus,
    ],
]);

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

Вложенные структуры и списки в переменных

<?php

$itemsHtml = '<table>';
foreach ($orderItems as $item) {
    $itemsHtml .= '<tr><td>' . htmlspecialcharsbx($item['NAME']) . '</td></tr>';
}
$itemsHtml .= '</table>';

Event::send([
    'EVENT_NAME' => 'CUSTOM_ORDER_ITEMS',
    'LID' => 's1',
    'C_FIELDS' => ['ITEMS_TABLE' => $itemsHtml],
]);

Переменная может содержать не только простое значение, но и заранее сформированный HTML-фрагмент (например, готовую таблицу товаров заказа) — почтовое событие само по себе не строит сложную структуру внутри шаблона, поэтому такие фрагменты формируются в коде до вызова Event::send и передаются уже готовым HTML.

Локализация переменных для мультиязычных сайтов

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

Тестирование нового типа события

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

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

• Переменная передана в C_FIELDS, но не описана при регистрации типа события. Значение не отображается в шаблоне, поскольку администратор не увидел эту переменную при создании шаблона.
• HTML-фрагмент для переменной не экранирован там, где должен быть просто текстом. Пользовательский контент в переменной интерпретируется как разметка, если это не задумано намеренно.
• Новый тип события не протестирован до встраивания в боевую логику. Ошибка в шаблоне или переменных обнаруживается только после реального использования.

Итог

Собственное почтовое событие с произвольным набором переменных регистрируется так же, как и штатные события Битрикса, — через административную панель или программно при установке модуля. Массив C_FIELDS при отправке через Event::send принимает любой набор ключей, соответствующих описанным при регистрации переменным, включая заранее сформированные HTML-фрагменты для сложных структур вроде таблиц.