Отправка почтовых событий в Битрикс D7: пошаговое руководство

Отправка писем в Bitrix CMS — важная часть бизнес-логики сайта. В этой статье рассмотрим, как правильно отправлять почтовые события через D7 API, включая работу с вложениями, обработку ошибок и мультиязычные шаблоны.

1. Классический способ (CEvent::Send)

Устаревший, но рабочий метод через ядро CEvent:

$arEventFields = [
    "EMAIL_TO" => "client@example.com",
    "ORDER_ID" => 482,
    "USER_NAME" => "Иван Иванов"
];

CEvent::Send("ORDER_CREATED", "s1", $arEventFields);

Параметры:

• ORDER_CREATED — код почтового события (настраивается в админке).

• s1 — ID сайта.

• $arEventFields — массив полей для подстановки в шаблон.

Недостатки:

• Нет поддержки D7.

• Нет удобной обработки ошибок.

• Менее гибкий, чем современные методы.

2. Современный метод (Bitrix\Main\Mail\Event)

Рекомендуемый способ для новых проектов:

use Bitrix\Main\Mail\Event;

$result = Event::send([
    "EVENT_NAME" => "ORDER_CREATED",
    "LID" => "s1", // ID сайта
    "C_FIELDS" => [
        "EMAIL" => "client@example.com",
        "ORDER_ID" => 482,
        "USER_NAME" => "Иван Иванов"
    ]
]);

if (!$result->isSuccess()) {
    $errors = $result->getErrors();
    // Логирование ошибок
}

Преимущества:

• Поддержка D7 и современных стандартов PHP.

• Возможность проверки успешности отправки.

• Гибкость в передаче данных.

3. Мгновенная отправка (sendImmediate)

Если письма не отправляются из-за задержек агентов:

Event::sendImmediate([
    "EVENT_NAME" => "TEST_EVENT",
    "LID" => "s1",
    "C_FIELDS" => [
        "EMAIL" => "test@example.com",
        "MESSAGE" => "Это тестовое письмо"
    ]
]);

Когда использовать?

• Для тестирования шаблонов.

• В критичных по времени процессах (например, подтверждение оплаты).

4. Отправка вложений (файлов)

Чтобы добавить файлы к письму:

Event::send([
    "EVENT_NAME" => "INVOICE_SENT",
    "LID" => "s1",
    "C_FIELDS" => [
        "EMAIL" => "client@example.com",
        "INVOICE_ID" => 1001
    ],
    "FILE" => [
        $_SERVER["DOCUMENT_ROOT"] . "/upload/invoices/invoice_1001.pdf",
        // Можно передать несколько файлов
    ]
]);

Важно:
Файлы должны быть доступны для чтения сервером.

5. Мультиязычные письма (LANGUAGE_ID)

Если сайт мультиязычный, можно указать язык письма:

Event::send([
    "EVENT_NAME" => "WELCOME_EMAIL",
    "LID" => "s1",
    "LANGUAGE_ID" => "en", // или "ru", "de" и т.д.
    "C_FIELDS" => [
        "EMAIL" => "user@example.com",
        "NAME" => "John"
    ]
]);

6. Динамическое изменение шаблона

Можно переопределить текст письма прямо в коде:

Event::send([
    "EVENT_NAME" => "NEWSLETTER",
    "LID" => "s1",
    "C_FIELDS" => [
        "EMAIL" => "subscriber@example.com"
    ],
    "MESSAGE_REPLACE" => [
        "subject" => "Новый заголовок письма",
        "body" => "<p>Это кастомный HTML-контент письма.</p>"
    ]
]);

7. Отправка нескольким получателям

Если нужно разослать письма с разными данными:

$recipients = [
    ["email" => "user1@example.com", "name" => "Алексей"],
    ["email" => "user2@example.com", "name" => "Мария"]
];

foreach ($recipients as $recipient) {
    Event::send([
        "EVENT_NAME" => "PERSONAL_NOTIFICATION",
        "LID" => "s1",
        "C_FIELDS" => [
            "EMAIL" => $recipient["email"],
            "NAME" => $recipient["name"]
        ]
    ]);
}

Типичные ошибки и решения

Заключение

Для новых проектов рекомендуется использовать D7 API (Bitrix\Main\Mail\Event), так как он:

• Поддерживает современные стандарты.

• Позволяет обрабатывать ошибки.

• Дает больше гибкости (вложения, мультиязычность, динамические шаблоны).

Классический метод (CEvent::Send) стоит применять только в legacy-проектах. Для мгновенной отправки используйте sendImmediate(). Всегда тестируйте шаблоны перед использованием в продакшене.