#события

При отправке почтовых событий в 1С-Битрикс разработчики часто используют старый API CEvent::Send(), не зная о современном классе Bitrix\Main\Mail\Event и его двух принципиально разных методах отправки. Неправильный выбор метода приводит к блокировке выполнения скрипта при проблемах с почтовым сервером или избыточной нагрузке на базу данных.

Метод send(): отложенная отправка

Метод send() добавляет событие в очередь отправки (таблица b_event). Агент Битрикс обработает событие позже:

use Bitrix\Main\Mail\Event;

// Добавление в очередь с автоматическим выбором шаблона
$result = Event::send([
    'EVENT_NAME' => 'ORDER_CONFIRM',
    'LID' => 's1',
    'C_FIELDS' => [
        'ORDER_ID' => $orderId,
        'USER_EMAIL' => $email,
        'ORDER_LIST' => $orderHtml,
    ],
]);

// Проверка результата
if ($result->isSuccess()) {
    $eventId = $result->getId();
} else {
    $errors = $result->getErrorMessages();
}

Метод send() возвращает объект Result с методами проверки успешности и получения ошибок, что упрощает обработку по сравнению со старым API.

Отправка конкретного почтового шаблона

Для отправки определённого шаблона используйте параметр MESSAGE_ID:

// Отправка конкретного шаблона (ID из таблицы b_event_message)
$result = Event::send([
    'EVENT_NAME' => 'ORDER_CONFIRM',
    'LID' => 's1',
    'MESSAGE_ID' => 5, // ID конкретного шаблона
    'C_FIELDS' => [
        'ORDER_ID' => $orderId,
        'USER_EMAIL' => $email,
    ],
]);

Без MESSAGE_ID система выберет все активные шаблоны по EVENT_NAME и LID. С MESSAGE_ID будет использован только указанный шаблон, даже если есть другие для этого типа события.

Метод sendImmediate(): немедленная отправка

Метод sendImmediate() отправляет письмо синхронно, минуя очередь:

use Bitrix\Main\Mail\Event;

// Немедленная отправка с конкретным шаблоном
$sendResult = Event::sendImmediate([
    'EVENT_NAME' => 'CRITICAL_ALERT',
    'LID' => 's1',
    'MESSAGE_ID' => 12, // Опционально: конкретный шаблон
    'C_FIELDS' => [
        'MESSAGE' => 'Критическая ошибка в системе',
        'TIME' => date('Y-m-d H:i:s'),
    ],
]);

// Результат - строковая константа
if ($sendResult === Event::SEND_RESULT_SUCCESS) {
    // Отправлено успешно
} elseif ($sendResult === Event::SEND_RESULT_ERROR) {
    // Ошибка отправки
} elseif ($sendResult === Event::SEND_RESULT_TEMPLATE_NOT_FOUND) {
    // Шаблон не найден
}

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

Метод sendImmediate() возвращает строку, в отличие от send(), а не объект Result.

Обработка вложений

Оба метода поддерживают массив вложений в параметре FILE:

$result = Event::send([
    'EVENT_NAME' => 'DOCUMENT_READY',
    'LID' => ['s1', 's2'], // Множественные сайты
    'C_FIELDS' => ['DOC_NUMBER' => '123'],
    'FILE' => [
        456, // ID из b_file (не копируется)
        '/path/to/new.pdf', // Новый файл (будет скопирован)
    ],
]);

Система автоматически определяет тип вложения: числовые значения считаются ID файлов, строки - путями к файлам для копирования.

Итог

Используйте send() для пользовательских сценариев и sendImmediate() для фоновых задач. Параметр MESSAGE_ID позволяет точно контролировать, какой шаблон будет использован.