Методы отправки писем в Битрикс: от Mail::send до почтовых событий

Раздел: CMS разработка -> Разработка для 1С-Битрикс

Отправка писем из кода Битрикса

Основное эффективное решение: \Bitrix\Main\Mail\Mail::send()

Класс Mail предоставляет универсальный метод для отправки как простых, так и сложных писем. Он автоматически использует настроенный в системе способ доставки (почтовая функция или SMTP).

Пример отправки простого письма:

use Bitrix\Main\Mail\Mail;

$result = Mail::send([
    'TO'      => 'user@example.com',
    'SUBJECT' => 'Привет, Битрикс!',
    'BODY'    => 'Это тестовое сообщение.',
]);

if ($result) {
    echo "Письмо отправлено успешно";
} else {
    echo "Ошибка отправки";
}

Пояснение: Массив содержит ключи TO (получатель), SUBJECT (тема), BODY (тело). Можно добавить FROM, CC, BCC, CONTENT_TYPE (по умолчанию text/plain).

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

  • Письмо не доходит или попадает в спам. Проверить настройки почты в административной части (Настройки > Настройки продукта > Почтовые настройки). Убедиться, что указан корректный FROM, совпадающий с доменом.
  • Кодировка тела письма искажена. Явно задать параметр CHARSET (например, 'UTF-8').
  • Ошибка "Mailer error". Включить отладку: $mailer = new \Bitrix\Main\Mail\Mailer(); var_dump($mailer->getErrors());.

Как отправить простое текстовое письмо без использования API Битрикса?

Можно использовать нативную PHP-функцию mail(). Подходит для быстрых прототипов, но не рекомендуется из-за отсутствия интеграции с настройками Битрикса.

$to      = 'user@example.com';
$subject = 'Тема письма';
$message = 'Текст письма';
$headers = 'From: no-reply@mysite.ru' . "\r\n" .
           'Content-type: text/plain; charset=UTF-8' . "\r\n";

if (mail($to, $subject, $message, $headers)) {
    echo "Отправлено";
} else {
    echo "Ошибка";
}
  • Проблема: не учитываются настройки SMTP из конфига Битрикса, письма могут отправляться через локальный sendmail с ограничениями.
  • Решение: перенастроить функцию mail() через .settings.php (поле mail), но проще использовать штатный класс Mail.

Как настроить отправку писем через внешний SMTP-сервер?

Настройка SMTP производится в файле bitrix/.settings.php. Пример:

'mail' => [
    'value' => [
        'smtp' => [
            'host' => 'smtp.gmail.com',
            'port' => 465,
            'protocol' => 'ssl',
            'login' => 'user@gmail.com',
            'password' => 'пароль_приложения',
        ],
    ],
],

После сохранения файла все письма, отправляемые через Mail::send(), пойдут через указанный SMTP.

  • Ошибка соединения. Проверить хост, порт и протокол. Для Gmail требуется пароль приложения, а не обычный.
  • Письма не отправляются. Включить логгирование: добавить 'debug' => true в массив smtp.

Как отправлять письма асинхронно, в фоновом режиме, не замедляя ответ пользователю?

Для этого используется агент Битрикса. Создаётся функция, которая вызывает Mail::send(), и регистрируется агент.

// в файле /local/php_interface/init.php
function sendAsyncMail($to, $subject, $body) {
    \Bitrix\Main\Mail\Mail::send([
        'TO' => $to,
        'SUBJECT' => $subject,
        'BODY' => $body,
    ]);
    return "sendAsyncMail(\"$to\", \"$subject\", \"$body\")";
}

// регистрация агента:
\CAgent::AddAgent(
    "sendAsyncMail(\"user@example.com\", \"Тема\", \"Тело\");",
    "", // модуль
    "N", // периодичность
    60, // интервал в секундах
    date("Y-m-d H:i:s"), // дата первого запуска
    "Y", // активен
    date("Y-m-d H:i:s") // дата последнего запуска
);
  • Проблема: агент выполняется только при хите на сайт, если трафика нет, письмо задержится.
  • Решение: использовать cron для вызова cron_events.php.
  • Ошибка: агент не запускается – проверить, что функция возвращает строку вызова самой себя для повторения.

Как отправить письмо с использованием почтовых событий (шаблонов) CEvent?

Метод CEvent::Send() удобен, когда нужно использовать готовые шаблоны писем из административной части.

$eventName = 'MY_NEW_EVENT'; // тип события
$fields = [
    'EMAIL_TO' => 'user@example.com',
    'USER_NAME' => 'Иван',
];
$event = new CEvent;
$result = $event->Send($eventName, SITE_ID, $fields);

if ($result) {
    echo "Событие отправлено";
} else {
    print_r($event->LAST_ERROR);
}

Предварительно нужно создать тип почтового события в админке (Почтовые события > Типы почтовых событий) и шаблон для него.

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

Расширенные примеры отправки писем

Пример 1. Отправка HTML-письма с вложением

Пример 
use Bitrix\Main\Mail\Mail;

$filePath = $_SERVER['DOCUMENT_ROOT'] . '/upload/invoice.pdf';
$attachment = [
    'CONTENT' => file_get_contents($filePath),
    'FILENAME' => 'invoice.pdf',
    'CONTENT_TYPE' => 'application/pdf',
];

$result = Mail::send([
    'TO'      => 'client@example.com',
    'SUBJECT' => 'Счёт на оплату',
    'BODY'    => '<h1>Здравствуйте!</h1><p>Ваш счёт во вложении.</p>',
    'CONTENT_TYPE' => 'text/html',
    'ATTACHMENT'   => [$attachment],
]);

if ($result) {
    echo "Письмо с вложением отправлено";
} else {
    echo "Ошибка отправки";
}
Результат: true (при успехе) или false (при ошибке).

Пример 2. Отправка письма с несколькими получателями и скрытой копией (BCC)

Пример 
use Bitrix\Main\Mail\Mail;

$result = Mail::send([
    'TO'      => 'manager1@example.com, manager2@example.com',
    'SUBJECT' => 'Уведомление для менеджеров',
    'BODY'    => 'Важная информация.',
    'BCC'     => 'archive@example.com',
]);

if ($result) {
    echo "Письмо отправлено";
} else {
    var_dump($result);
}
Результат: true.

Пример 3. Отправка письма с пользовательскими заголовками (Reply-To, Message-ID)

Пример 
use Bitrix\Main\Mail\Mail;

$result = Mail::send([
    'TO'      => 'user@example.com',
    'SUBJECT' => 'Ответ на обращение',
    'BODY'    => 'Текст ответа',
    'HEADERS' => [
        'Reply-To' => 'support@mysite.com',
        'Message-ID' => '<msg123@mysite.com>',
    ],
]);

if (!$result) {
    $mailer = new \Bitrix\Main\Mail\Mailer();
    print_r($mailer->getErrors());
}
Результат: true при успехе. Массив ошибок при неудаче.

Пример 4. Отправка письма с использованием DKIM-подписи

Для включения DKIM необходимо настроить DNS-запись, а затем в .settings.php добавить:

Пример 
'mail' => [
    'value' => [
        'dkim' => [
            'domain' => 'mysite.com',
            'private_key' => '/path/to/private.key',
            'selector' => 'default',
        ],
    ],
],

Все последующие письма будут подписываться автоматически. Проверка подписи производится получателем.

Результат: подпись добавляется в заголовки письма, видно в исходном тексте письма.

Пример 5. Отправка письма с кодировкой UTF-8 и сменой имени отправителя

Пример 
use Bitrix\Main\Mail\Mail;

$result = Mail::send([
    'TO'      => 'user@example.com',
    'SUBJECT' => 'Проверка кодировки',
    'BODY'    => 'Сообщение на русском языке',
    'FROM'    => 'Иван Иванов <ivan@mysite.com>',
    'CHARSET' => 'UTF-8',
]);

if (!$result) {
    $errors = \Bitrix\Main\Mail\Mailer::getErrors();
    foreach ($errors as $error) {
        echo $error->getMessage();
    }
}
Результат: true. Если ошибка, выведется сообщение (например, 'Invalid address').
Почта Bitrix PHP

Почта Bitrix PHP - comments

En
Bitrix php mail (php)