Почтовые шаблоны в Битрикс: частые ошибки

В 1С-Битрикс письмо может не отправиться даже при правильном SMTP: шаблон привязан не к тому типу события, макрос написан с ошибкой, а обработчик передаёт поле под другим именем. Ниже — практический разбор для «1С-Битрикс: Управление сайтом» из веток 24.x–25.x. Названия пунктов меню могут немного отличаться в зависимости от редакции и локализации.

Сначала разделите проблему на три слоя

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

• Событие — код или компонент создал почтовое событие нужного типа.
• Шаблон — активный шаблон выбран для нужного сайта, языка и типа события.
• Доставка — Битрикс передал письмо почтовому серверу, а сервер принял его.

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

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

Четыре подхода к диагностике

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

Ошибка 1. В шаблоне указан не тот тип события

В Битрикс шаблон привязан к событию, например к уведомлению о регистрации, восстановлению пароля или изменению статуса заказа. Похожее название не означает, что события взаимозаменяемы.

Частая ситуация: разработчик меняет шаблон «Новый заказ», а интернет-магазин отправляет событие другого типа, созданное компонентом оформления заказа или собственным обработчиком. Пользователь получает старый текст, а команда уверена, что правка не работает.

Как проверить

1. Откройте раздел с почтовыми событиями и найдите точное имя события, которое вызывает нужный сценарий.
2. Откройте список почтовых шаблонов и отфильтруйте его по этому типу события.
3. Проверьте активность шаблона и наличие привязки к нужному сайту.
4. Отправьте одно тестовое событие и сравните время создания записи с моментом отправки.

Результат проверки: у события есть запись, а для него выбран активный шаблон. Если запись появляется, но шаблонов несколько, следующим кандидатом становится конфликт настроек сайта, языка или сортировки.

Ошибка 2. Макрос выглядит правильно, но не заменяется

Поля шаблона Битрикс подставляются по именам, которые переданы в почтовое событие. Макрос #ORDER_ID# сработает только при наличии поля с таким именем. Варианты вроде #ORDERID#, #order_id# или # ORDER_ID # могут остаться в письме обычным текстом.

Не переносите макросы из одного события в другое без проверки. В письме о регистрации может быть #EMAIL#, а в уведомлении о заказе — другое поле получателя и другой набор данных. Названия зависят от конкретного события и кода, который его создаёт.

Что проверять в первую очередь

• точное написание макроса и символы подчёркивания;
• регистр букв;
• наличие поля в данных события;
• совпадение макросов в HTML- и текстовой версиях письма;
• отсутствие подстановки HTML-кода в поле, которое должно содержать обычный текст.

Надёжный тест — отправить письмо с несколькими заведомо известными полями и отдельно проверить каждое. Если одно поле подставилось, а другое осталось в виде #NAME#, проблема почти наверняка в имени или источнике данных, а не в SMTP.

Ошибка 3. Адрес получателя берут из неправильного поля

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

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

Когда использовать каждый вариант

Проверяйте получателя в исходном письме и в почтовом логе. Не делайте вывод по полю «Кому» в шаблоне: оно может содержать макрос, значение которого видно только после формирования сообщения.

Ошибка 4. Активен старый шаблон

В проекте нередко остаются несколько шаблонов одного типа: старый для основного сайта, новый для тестового, HTML-версия и текстовая версия. Администратор меняет один, а Битрикс использует другой.

Проверьте четыре признака:

1. шаблон активен;
2. он относится к нужному типу события;
3. выбран правильный сайт и язык;
4. у него нет конкурирующего шаблона с более подходящими условиями.

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

Ошибка 5. HTML-письмо ломается в почтовом клиенте

Шаблон может выглядеть нормально в одном сервисе и распадаться в другом. Причины — неподдерживаемые CSS-правила, относительные пути к изображениям, незакрытые HTML-теги и смешивание HTML с текстом без экранирования.

Для писем из Битрикс безопаснее держать разметку простой: таблицы для сетки, абсолютные URL изображений, встроенные стили и отдельную текстовую версию. Не вставляйте в шаблон JavaScript, внешние веб-шрифты и интерактивные элементы: почтовые клиенты часто их блокируют.

Макрос тоже может сломать разметку. Если пользовательское имя содержит символы HTML, оно должно проходить экранирование на этапе формирования данных или шаблона. Особенно внимательно проверяйте поля с комментариями, адресами и названиями товаров.

Ошибка 6. Письмо сформировалось, но не ушло сразу

Отправка может идти через очередь или почтовый сервер. Поэтому отсутствие письма в течение нескольких секунд не доказывает ошибку шаблона.

Проверьте:

• появилась ли запись о событии;
• создано ли почтовое сообщение;
• запускается ли агент или другой механизм обработки очереди;
• нет ли ошибки подключения к SMTP;
• не попал ли адрес отправителя или домен в фильтры почтового сервиса.

Если в очереди сообщение есть, а сервер его не принимает, редактирование макросов не поможет. Смотрите ответ SMTP и заголовки письма. Для доставки также важны SPF, DKIM и DMARC домена отправителя; их настройка относится к почтовой инфраструктуре, а не к шаблону Битрикс.

Что ломается при переносе на другой сайт

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

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

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

Какой порядок проверки выбрать

Для большинства инцидентов работает такой порядок:

1. зафиксируйте сценарий: кто инициирует отправку, какое письмо ожидается и на какой адрес;
2. найдите точный тип почтового события;
3. убедитесь, что событие создаётся;
4. проверьте активный шаблон, сайт, язык и отправителя;
5. сверьте каждый макрос с фактическими полями события;
6. отделите ошибку формирования письма от ошибки доставки;
7. проверьте HTML в нескольких почтовых клиентах и текстовую версию.

Не меняйте сразу шаблон, SMTP и код обработчика. Иначе вы потеряете причину сбоя и получите результат, который сложно воспроизвести.

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

Добавьте в чек-лист релиза один тестовый сценарий на каждое критичное письмо: регистрация, восстановление пароля, заказ и смена статуса. Храните рядом с шаблоном список поддерживаемых макросов и источник каждого поля. В рабочей системе отдельно отслеживайте количество созданных событий, сообщений в очереди и отказов SMTP. Такой мониторинг быстрее показывает, сломалась ли бизнес-логика, шаблон или доставка.