Тип почтового события — это каркас уведомления: он задаёт набор макросов, которые потом подставляются в шаблоны писем и заполняются при отправке. Собственный тип нужен, когда штатных событий (регистрация, заказ, обратная связь) не хватает для вашей бизнес-логики.
Что такое тип почтового события и когда он нужен
В 1С-Битрикс почтовая подсистема состоит из трёх сущностей. Не путайте их — это ключ к пониманию всей настройки:
- Тип почтового события (
b_event_type) — описание уведомления: символьный код, название, язык и список доступных макросов. - Шаблон письма (
b_event_message) — конкретное письмо (тема, тело, отправитель, получатель), привязанное к типу события. - Событие (
b_event) — факт отправки: запись в очереди, которую разбирает агент рассылки и превращает в письмо по шаблону.
Один тип может иметь несколько шаблонов (например, отдельные для разных сайтов или языков). Создавать новый тип нужно, когда у вас появляется новое бизнес-уведомление со своим набором данных: письмо менеджеру о брошенной корзине, уведомление о смене статуса заявки в сервисе, оповещение партнёра о начислении бонусов.
Создание нового типа через административный интерфейс
Самый простой путь — визарды админки. Перейдите в Настройки → Настройки продукта → Почтовые события → Типы почтовых событий и нажмите «Добавить тип почтового события».
- Задайте Идентификатор типа — символьный код латиницей в верхнем регистре, например
NEW_SERVICE_REQUEST. По нему тип вызывается из кода, менять его после начала эксплуатации нежелательно. - Укажите Название — понятное описание для администраторов (отображается в списке событий).
- Выберите Сортировку — порядок в списках выбора.
- Выберите Язык / Сайт при необходимости — если тип нужен только для одной языковой версии.
- В поле Описание перечислите доступные макросы. Это критично: администратор, который будет верстать шаблон, увидит здесь список подстановок.
- Нажмите «Сохранить».
После сохранения тип появится в списке. Теперь к нему можно привязывать шаблоны писем — они настраиваются в соседнем пункте меню «Почтовые события».
Макросы: как описать поля будущего письма
Макрос — это плейсхолдер вида #FIELD_NAME#, который заменяется на реальное значение в момент отправки. Набор макросов вы придумываете сами исходя из данных уведомления. Служебные макросы доступны всегда:
| Макрос | Назначение |
|---|---|
#EMAIL_FROM# | Адрес отправителя, заданный в шаблоне |
#EMAIL_TO# | Адрес получателя |
#SITE_NAME# | Название сайта |
#SERVER_NAME# | Доменное имя сайта |
#DEFAULT_EMAIL_FROM# | E-mail по умолчанию из настроек главного модуля |
Свои макросы вы просто перечисляете в описании типа, например #ORDER_ID#, #USER_NAME#, #STATUS#. Никакой отдельной «регистрации» полей нет: важно лишь, чтобы имена макросов в шаблоне точно совпадали с ключами массива, который вы передаёте при отправке. Регистр имеет значение.
Программное создание типа и отправка события
Для типового решения удобнее создавать тип из кода — например, в обработчике установки модуля или в миграции. Используется класс CEventType:
$et = new CEventType(); $et->Add(array('LID' => 'ru', 'EVENT_NAME' => 'NEW_SERVICE_REQUEST', 'NAME' => 'Новая заявка в сервис', 'DESCRIPTION' => "#ORDER_ID# - номер заявки\n#USER_NAME# - имя клиента\n#STATUS# - статус"));
Затем добавьте хотя бы один шаблон письма классом CEventMessage (поля EVENT_NAME, LID, EMAIL_FROM, EMAIL_TO, SUBJECT, BODY_TYPE, MESSAGE). В теле и теме используйте свои макросы.
Отправка события с подстановкой данных:
CEvent::Send('NEW_SERVICE_REQUEST', SITE_ID, array('ORDER_ID' => 512, 'USER_NAME' => 'Иван Петров', 'STATUS' => 'В работе'));
Ключи массива передаются без символов # — Битрикс сам оборачивает их при подстановке. Метод Send() не отправляет письмо мгновенно, а ставит его в очередь b_event; фактическую рассылку выполняет агент CEvent::CheckEvents().
Проверка отправки и отладка
После настройки убедитесь, что письма реально уходят:
- Отправьте тестовое событие (через код или через штатное действие, вызывающее событие).
- Проверьте очередь: Настройки → Настройки продукта → Почтовые события → Отправляемые сообщения. Записи в статусе
Nещё не разосланы,Y— обработаны,F— ошибка. - Если очередь не разбирается — проверьте, включён и работает ли агент рассылки и корректно ли настроен режим отправки (агент на хитах или cron).
- Ошибки доставки смотрите в Журнале событий сайта (Настройки → Инструменты → Журнал событий).
Для локальной проверки шаблона удобно временно выставить в шаблоне тестовый адрес получателя и включить логирование почты на уровне сервера, чтобы видеть итоговое письмо с уже подставленными макросами.
Частые ошибки
- Макрос не подставляется, в письме остаётся
#FIELD#. Имя ключа в массивеSend()не совпадает с макросом в шаблоне или отличается регистром. Проверьте посимвольно. - Письмо не приходит вообще. К типу события не привязан ни один шаблон, либо шаблон отключён (не активен), либо не совпадает
SITE_ID/LIDв вызове и в шаблоне. - Событие «висит» в очереди со статусом N. Не работает агент рассылки. При отправке по cron проверьте, что задание запускается; при агентах на хитах — что сайт получает трафик.
- Дубли писем. Событию соответствуют несколько активных шаблонов для одного сайта — каждый порождает отдельное письмо. Это штатное поведение, но часто оказывается неожиданным.
- Тип создан, но не виден в списке. Указан язык/сайт, отличный от текущего фильтра, либо тип добавлен с пустым
EVENT_NAME. Идентификатор обязателен. - Кириллица в идентификаторе. Символьный код типа должен быть латиницей и в верхнем регистре — иначе вызовы из кода будут ненадёжны.
Итог
Создание собственного типа почтового события сводится к трём шагам: завести тип с понятным идентификатором и описанием макросов, привязать к нему шаблон письма с этими макросами и вызвать отправку через CEvent::Send(), передав данные без символов #.
Ключевое правило — строгое совпадение имён макросов между шаблоном и передаваемым массивом. Для тиражируемых решений создавайте тип и шаблоны программно (в установщике модуля), а после настройки обязательно проверяйте очередь отправляемых сообщений и Журнал событий.