MailEvent::sendImmediate не отправляет письмо

Задача

Понять, почему письмо не создаёт нужную сущность, не отправляется или уходит не от того адреса.

Задача — mail\Event::sendImmediate не отправляет письмо. Почтовое событие, шаблон, LID, почтовая очередь.

Главное — не искать один универсальный метод, а сначала определить сущность, права и слой API, через который выполняется действие.

Как это устроено

Почта в коробке проходит через несколько слоёв: подключённый ящик, CRM-правило, почтовое событие, шаблон, очередь, SMTP и DNS-проверки. Ошибка на одном слое часто выглядит как проблема другого.

CRM-дело письма содержит служебные поля активности, коммуникации и тело письма. HTML и plain-текст могут отличаться, поэтому перед обработкой нужно выбрать нужное представление.

Если сценарий проверяется под администратором, отдельно повторите его под обычным пользователем. Для прав, CRM, задач, Диска и приложений это часто даёт другой результат.

Рабочий подход

Разделите входящую и исходящую почту. Для входящей проверьте ящик, правило создания CRM-сущности и уже существующие контакты. Для исходящей — шаблон, LID, отправителя, SMTP-лог и доставляемость.

Сделайте минимальный тест на одной сущности, сохраните входные данные и ответ метода, а затем расширяйте решение на массовый сценарий.

На коробке удобнее добавлять временное логирование рядом с местом выполнения кода, а в облаке — сохранять входящие и исходящие REST-запросы в свой журнал интеграции.

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

Нельзя проверять только папку «Отправленные». Письмо могло быть сформировано, но отклонено SMTP-сервером, антиспамом или политиками SPF/DKIM/DMARC.

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

Минимальный пример

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

\Bitrix\Main\Mail\Event::sendImmediate([
    'EVENT_NAME' => 'CUSTOM_EVENT',
    'LID' => 's1',
    'C_FIELDS' => [
        'EMAIL_TO' => 'client@example.com',
        'TEXT' => $text,
    ],
]);