1. Документация
  2. Для разработчика сайта
  3. Функции и классы
  4. Встроенные классы

Класс Email

Методы для работы с электронной почтой. Класс создан на основе библиотеки Swift Mailer.

Email::send($data=[], &$errors=null)

Создает и отправляет электронное письмо.

  • Возвращает true, если хотя бы одному адресату письмо было доставлено, иначе false.
  • $data — данные для создания и отправки письма. Подробнее см. в таблице ниже.
  • $errors — сообщения об ошибках (array). Массив с одним из следующих ключей: noMessage, no-recipients, invalid-emails, failed-recipients — массив адресов, куда письмо отправить не удалось (не всегда срабатывает, поэтому желательно указать $data['from'], куда придет сообщение о недоставленном письме).

Пример 

Email::send([
    'from'=>'john@doe.com', 
    'to'=>'bill@smith.com', 
    'subject'=>'Уведомление', 
    'htm'=>$htm, 
]);

 

$data — данные для создания и отправки письма

ПараметрОписаниеПримечание
'to'Почтовые ящики получателей
Допустимые форматы почтовых ящиков
Строка (RFC 2822) 
'to'=>'john@doe.com'
'to'=>'John Doe <john@doe.com>'
'to'=>'john@doe.com, Bill Smith <bill@smith.com>'

Массив (Swift Mailer):

'to'=>['john@doe.com', ...]
'to'=>['john@doe.com'=>'John Doe', ...]
'to'=>['john@doe.com', 'bill@smith.com'=>'Bill Smith']

В скриптах сайта рекомендуется использовать почтовые ящики, заданные в настройках сайта, и доступные через метод Blox::info('site','emails').

'from'Почтовый ящик отправителя
'reply-to'Почтовые ящики, на которые следует посылать ответ.Формат такое же, как для параметров 'to' и 'from'.
'subject'Тема письма (string)
'htm'Сообщение в виде гипертекста (string)Создавать весь html документ не нужно — заголовок документа и остальные разделы будут созданы автоматически.
'txt'Альтернативный обычный текст (string)

необязательный параметр

Если отправляется голый текст, то предпочтительнее использовать именно этот параметр, оставив $data['htm'] пустым. Не забудьте проставить в тексте переносы строк "\n"
'together'Отправить письмо всем адресатам за один раз (boolean)По умолчанию, когда этот параметр не задан, письма будут отправлены одно за другим, отдельно каждому получателю. Если же этот параметр сделать true, то каждый получатель в полученном письме увидит почтовые ящики остальных получателей.
'attachments'Массив присоединяемых файлов (array) Элементами массива могут быть строки или массивы.

  1. Строки — пути к файлам.

    Пример: 

    $data['attachments'] = [
    'templates/aaa.xlsx',
    Blox::info('templates','dir').'/aaa.xlsx',
];

  2. Массивы. Этот способ применяется если нужно изменить имя файла или присоединить динамический контент без создания самого файла.

    Ассоциативные ключи массива:
    • 'path' — путь к файлу или 'data' — данные (динамический контент).
    • 'name' — имя присоединенного файла.
    • 'type' — MIME-тип данных.
      Этот ключ нужно применять вместе с ключом 'data', или, как минимум, правильно пишите расширение файла в ключе 'name'.

    Пример: 

    $data['attachments'] = [
    # Файл на диске
    ['path'=>'temp/aaa.txt','name'=>'orders.csv'],
    # Динамический контент
    ['data'=>$data,'name'=>'users.csv','type'=>'text/csv'], 
];

'transport'Настройки почтового транспорта Элементами массива могут быть строки или массивы.

  1. Отправка писем с помощью sendmail.exe

    Если на вашем сервере установлен агент для передачи почты sendmail, то лучше воспользоваться им непосредственно. 

    $data['transport'] = ['type'=>'sendmail'];

    Если письма не уходят из-за того, что Blox CMS не может определить путь к sendmail.exe, то этот путь нужно узнать (у хостера) и прописать в ключе 'path': 

    $data['transport'] = [
    'type'=>'sendmail', 
    'path'=>'/usr/sbin/sendmail -bs'
];
    Здесь указан стандартный путь в системах Linux/UNIX.

  2. Отправка писем с помощью SMTP

    И наконец, самый надежный метод отправки – это отправка через отдельный SMTP-сервер: 

    $data['transport'] = [
    'type'=>'smtp', 
    'host'=>'',
    'port'=>'',
    'user'=>'',
    'password'=>'',
    'encryption'=>'', # SSL, TLS, STARTTLS
];

В скриптах сайта можно импользовать значение Blox::info('site','emails','transport'), заданного в настройках сайта.

Как правильно настроить отправку почты с сайта?

Перечислим первоочередные меры, которые позволят сообщениям с сайта достигать адресатов, не попадая в спам. Допустим, вы отправляете письма с сайта www.mysite.com.

  1. Почтовый ящик для получения писем с сайта (to)
    Письма желательно отправлять на ящик, с тем же доменным именем, что и сайт, например:
    $data['to'] = 'to@mysite.com';
    Если выполнить это требование не получается, применяйте п.4 или п.5.

  2. Почтовый ящик для отправки писем с сайта (from)
    Письма желательно отправлять с ящика, с тем же доменным именем, что и сайт, например:
    $data['from'] = 'from@mysite.com';
    Не ставьте сюда реальный ящик пользователя, введенный в форму — для него используйте параметр 'reply-to'.
    Без дополнительных настроек (см. п.4 или п.5) для отправки писем не годятся ящики вида @mail.ru, @bk.ru, @list.ru, @inbox.ru от компании "Mail.ru Group".

  3. Реальный почтовый ящик отправителя (reply-to)
    $data['reply-to'] = 'xxx@zzz.com';
    Используйте параметр "ящик для ответа" (reply-to) в качестве реального ящика отправителя, тогда если получатель в своей почтовой программе нажмет на кнопку "Ответить", то ответ придет автору письма, а не на административный ящик 'from'.

Дополнительные настройки

  1. Сделайте записи SPF, DKIM, DMARC в настройках домена (DNS) сайта. Записи приведены в порядке важности:

    • SPF-запись помогает снизить риск того, что отправленное с вашего домена письмо попадет в спам. Запись содержит список адресов серверов, отвечающих за отправку почты с ящиков на вашем домене.
    • С помощью DKIM-подписи получатель письма может удостовериться в том, что оно действительно пришло от предполагаемого отправителя.
    • DMARC-запись защищает вашу рассылку от подделок.
  2. Используйте для отправки писем отдельный SMTP-сервер (см. параметр 'transport'). Естественно, ящик 'from', при этом, должен быть приписан к этому почтовому серверу.

Email::format($emails, &$invalids=null)

Преобразует почтовый ящик (ящики) в единый формат, в частности, совместимый со Swift Mailer.

Использовать данный метод перед методом Email::send() не обязательно — там ящики и так форматируются и проходят проверку.

  • Возвращает массив почтовых ящиков в едином формате, где в ключе будет стоять ящик, а в значении имя.
  • $emails — почтовые ящики в любом формате (строковый формат RFC 2822 или массив). Допустимые форматы почтовых ящиков см. в таблице выше (пункт 'from').
  • $invalids — возвращает массив неправильных ящиков.

Пример 

$emails2 = Email::format('john@doe.com, Bill Smith <bill@smith.com>');
/*
Возвращает массив:
    'john@doe.com' => '',
    'bill@smith.com' => 'Bill Smith',
*/