# Уведомления по электронной почте

Сервис **Webim** рассылает письма посетителям, операторам, администраторам учётной записи и во внутренние службы: пароль новому оператору, ссылку на восстановление пароля, активацию учётной записи, историю диалога, оставленное сообщение, ежедневный отчёт со статистикой, уведомления о состоянии учётной записи.

В этой статье содержатся: полный перечень писем, механизм их отправки и все параметры, которыми рассылка настраивается, включается и отключается.

!!! Note "N.B."
    Статья описывает **исходящие** уведомления. Приём входящей почты и работа канала общения с посетителями по электронной почте описаны в статье [Канал электронной почты](https://webim.ru/kb/channels/mail/email.html).

## Как устроена отправка { #architecture }

Письма отправляют два независимых компонента сервера:

| Компонент         | Какие письма отправляет                                                                                                | Как отправляет                                                     |
|-------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| **Chat Backend**  | Письма, связанные с диалогами и посетителями, а также биллинговые и служебные уведомления                                | Синхронный SMTP-клиент либо HTTP API Mailgun; отправка выносится в отдельные потоки |
| **Admin Backend** | Регистрация учётной записи, восстановление пароля, пароль нового оператора, ежедневный отчёт со статистикой, счета        | Асинхронный SMTP-клиент либо HTTP API Mailgun                      |

Отдельной очереди писем в базе данных нет: каждое письмо ставится в фоновую задачу сразу в момент события. Количество параллельных потоков отправки в **Chat Backend** ограничено параметром `threads_limit_for_mail_sending` (по умолчанию `10`).

### Способы доставки { #delivery-methods }

**Webim** поддерживает два способа доставки писем:

  * **SMTP** — письмо отправляется напрямую на почтовый сервер, указанный в настройках;

  * **Sinch/Mailgun** — письмо передаётся во внешний сервис [Sinch/Mailgun](https://www.mailgun.com/) через HTTP API (`POST https://api.mailgun.net/v3/<домен>/messages.mime`) с ключом из параметра `mailgun_key`.

Способ доставки выбирается параметром `email_method_by_email_type` в файле `main.json`. Это словарь, в котором ключ — тип письма (как правило, совпадает с именем шаблона, например `offline-message`, `recover_password_mail_temp`, `email_channel`), а значение — `smtp` или `mailgun`. Ключ `default` задаёт способ для всех типов, которые не перечислены явно. Значение по умолчанию — `{"default": "smtp"}`.

```
{
  "email_method_by_email_type": {
    "default": "smtp",
    "email_channel": "mailgun"
  }
}
```

В hosted mode Mailgun никогда не используется: все письма всегда уходят по SMTP, независимо от значения `email_method_by_email_type`.

### Повторные попытки { #retries }

При отправке по SMTP из **Chat Backend** неудачная попытка повторяется по расписанию из параметра `smtp_retry_delays` — списка задержек в секундах. По умолчанию это `[5, 60, 600]`: после первой неудачи письмо отправляется повторно через 5 секунд, затем через 60 и через 600. После исчерпания списка письмо отбрасывается, а ошибка пишется в лог.

### Из какого адреса уходят письма { #from-address }

| Конфигурация              | Поле `From`                                                                                                                                                                                                                                                                                     | Поле `Reply-To`                                                                                                                                                                                                                                                     |
|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Облачная (cloud mode)     | Служебный адрес `noreply@webim.ru`                                                                                                                                                                                                                                                              | Адрес, на который ожидается получать ответы. Адрес из `company_email` становится `Reply-To` всех писем **Chat Backend** по учётной записи, в том числе оставленного сообщения и истории для оператора, и тогда ответ на оставленное сообщение уходит не посетителю. |
| On premises (hosted mode) | Значение `smtp_from_addr` (или устаревшего `hostedmode_smtp_from_addr`) в **Chat Backend**. Письма **Admin Backend** (регистрация, восстановление пароля, пароль оператора) уходят от `default_from` в любой конфигурации, а ежедневная статистика - от `from_title`/`from_email` из `partner_settings` | Не заполняется                                                                                                                                                                                                                                                      |

Если в настройках отдела или учётной записи задан параметр **Email компании** (`company_email`), он используется как адрес для ответа в письмах посетителям.

### Тема письма { #subject }

Тема всегда начинается с префикса:

  * в письмах посетителям — название компании из **Общих настроек**, например `ООО «Сила»: история диалога.`;

  * в письмах операторам, администраторам и служебных — название сервиса, например `Webim: статистика за 01.10.2026`.

Если письмо адресовано посетителю, а название компании не заполнено, префикс не добавляется.

### Язык письма { #language }

Для писем, связанных с конкретным диалогом, используется язык этого диалога. Для остальных — значение настройки **Основной язык интерфейса** учётной записи (`default_lang`), а при её отсутствии — язык сервиса по умолчанию. Подробнее см. в статье [Языки](https://webim.ru/kb/for-admins/languages.html).

### Вложения и изображения { #attachments }

Письмо собирается в MIME-формате. Если во вложениях или в теле письма есть файлы и встроенные изображения, формируется многочастное сообщение (`multipart/related`): изображения подставляются через `Content-ID`, файлы прикладываются как вложения. Так, например, к письму с ежедневной статистикой прикладываются файл `xlsx` с отчётами и файл с историей сообщений.

## Какие письма рассылает Webim { #letters }

### Регистрация, учётные записи и пароли { #letters-accounts }

| Письмо                                   | Когда отправляется                                                          | Кому                                                   | Тема                                                        |
|------------------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------|---------------------------------------------------------------|
| Активация учётной записи                 | При регистрации новой учётной записи, если обязательная активация включена  | Адрес, указанный при регистрации                        | `Webim: регистрация на сервисе <название сайта>.`              |
| Приветственное письмо                    | При регистрации новой учётной записи, если обязательная активация выключена | Адрес, указанный при регистрации                        | `Webim: Четыре простых шага по настройке Webim.`               |
| Восстановление пароля                     | По запросу **Забыли пароль?**, если учётная запись активирована             | Адрес оператора                                         | `Webim: Забыли пароль?`                                        |
| Повторная активация вместо восстановления | По запросу **Забыли пароль?**, если учётная запись ещё не активирована      | Адрес оператора                                         | `Webim: регистрация на сервисе <название сайта>.`               |
| Пароль нового оператора                   | При создании УЗ оператора с включённой опцией отправки пароля               | Адрес оператора                                  | `Webim: для Вас создана учётная запись на сервисе Webim.`       |

Ссылка для восстановления пароля действует **24 часа** с момента запроса. Подробнее о процедуре см. в статье [Сброс пароля](https://webim.ru/kb/faq/reset-password.html).

Операторы, создаваемые автоматически при входе через [SSO и Active Directory](https://webim.ru/kb/devops/active-directory/sso-configuration.html), всегда получают письмо с паролем — отключить его нельзя.

!!! Note "N.B."
    При самостоятельной смене пароля оператором (по ссылке восстановления или в своём профиле) письмо **не** отправляется.

### Диалоги и обращения посетителей { #letters-chats }

| Письмо                             | Когда отправляется                                                                                                                                              | Кому                                                   | Тема                                                              |
|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------------|
| Оставленное сообщение              | Посетитель оставил сообщение, когда ни один оператор не был в статусе *Онлайн*                                                                                        | Адреса из поля **Для оставленных сообщений**               | `<Название компании>: вопрос от <имя посетителя>.`                   |
| История диалога посетителю         | Посетитель нажал кнопку отправки диалога на почту и указал адрес                                                                                                       | Адрес, указанный посетителем                               | `<Название компании>: история диалога.`                              |
| История диалога оператору          | Оператор отправил диалог на почту другому оператору                                                                                                                    | Адрес оператора-получателя                                 | `Webim: История диалога с с посетителем <имя>`                       |
| Непрочитанные сообщения посетителю | Оператор ответил, а посетитель не прочитал сообщение дольше заданного тайм-аута; проверка выполняется каждые 30 секунд                                                   | Адрес посетителя из полей посетителя                       | `<Название компании>: новое сообщение`                               |
| Посетитель долго ждал ответа       | Диалог закрылся после того, как посетителю было показано сообщение о занятости операторов                                                                               | Адреса из поля **Для негативных отзывов**                  | `Webim: посетитель долгое время не получал ответа от оператора.`     |
| Негативная оценка оператора        | Посетитель оценил работу оператора на 1 или 2 звезды                                                                                                                   | Адреса из поля **Для негативных отзывов**                  | `Webim: посетитель был недоволен обслуживанием оператора.`           |

Письмо о непрочитанных сообщениях не отправляется посетителям, пришедшим из внешних каналов (мессенджеры, соцсети, Email-канал): у них есть собственный способ доставки.

Письмо о том, что посетитель долго ждал ответа, отправляется не чаще, чем раз в `timeout_for_send_email_about_visitor_waiting` минут на учётную запись (по умолчанию — раз в 4 часа).

### Статистика { #letters-stats }

Каждую ночь сервис рассылает письмо **«Webim: статистика за /ДАТА/»** с отчётом за предыдущий календарный день. Рассылку выполняет задача по расписанию, отдельно на каждом сервере; письмо уходит на адреса из поля **Для ежедневных отчётов** (`stats_email`).

Полные условия отправки, состав вложений и список «живых» учётных записей описаны в статье [Ежедневная рассылка писем со статистикой](https://webim.ru/kb/for-analytics/statistics/daily-email-reports.html).

!!! Note "N.B."
    В account config присутствуют параметры `send_weekly_stats` и `send_monthly_stats`. В текущей версии сервера еженедельная и ежемесячная рассылки статистики **не реализованы**: эти параметры ни на что не влияют, по почте уходит только ежедневный отчёт.

### Биллинг и состояние учётной записи { #letters-billing }

Все эти письма, кроме счёта на оплату, отправляет **Chat Backend**, поэтому в локальной конфигурации они не рассылаются. Счёт на оплату отправляет **Admin Backend**: он уходит в любой конфигурации, если задан параметр `service_notifications_emails`.

| Письмо                                      | Когда отправляется                                                                | Кому                                                                                |
|---------------------------------------------|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| Окончание тестового периода                 | За 2 дня до окончания тестового периода                                               | Адрес из `low_balance_email`; если не задан — адрес первого администратора учётной записи |
| Окончание оплаченного периода               | За 5 дней до окончания оплаченного периода                                            | Там же                                                                                  |
| Заказ сервиса на следующий период            | При автоматическом продлении услуги                                                   | Там же                                                                                  |
| Блокировка после тестового периода           | При блокировке учётной записи по окончании тестового периода                           | Там же, плюс копия на внутренний адрес `blocked_notify_email`                            |
| Блокировка по окончании оплаченного периода  | При блокировке учётной записи по окончании оплаченного периода                         | Там же, плюс копия на `blocked_notify_email`                                             |
| Счёт на оплату                               | При выставлении счёта                                                                 | Адреса из `service_notifications_emails`                                                 |

## Ограничения hosted mode { #hosted-mode }

В hosted mode **Chat Backend** отправляет только письма, связанные с диалогами:

  * оставленное сообщение;

  * история диалога посетителю и оператору;

  * непрочитанные сообщения посетителю;

  * посетитель долго ждал ответа;

  * негативная оценка оператора;

  * дублирование push-уведомления на почту.

Письма **Admin Backend** — активация учётной записи, восстановление пароля, пароль нового оператора, ежедневный отчёт со статистикой, счёт на оплату — работают в hosted mode в полном объёме.

## Настройка в main.ini и main.json { #ini }

Параметры рассылки задаются в главных файлах настроек сервера. Общие правила их формата, расположения и объединения описаны в статье [Главные файлы настроек](https://webim.ru/kb/devops/main-ini-configuration.html); основное, что нужно помнить: `main.ini` — плоский файл вида `ключ=значение` без секций, а значения-словари (например, `email_method_by_email_type`) задаются только в `main.json`.

### Подключение к почтовому серверу { #ini-smtp }

Параметры SMTP-подключения (`smtp_server`, `smtp_port`, `smtp_username`, `smtp_password`, `smtp_encryption`, `smtp_auth_mode`, `smtp_from_addr`), а также поддерживаемые типы аутентификации описаны в статье [Интеграция с почтовыми серверами](https://webim.ru/kb/devops/smtp-integration.html).

Дополнительно на рассылку влияют:

| Параметр                          | Файл        | Значение по умолчанию | Описание                                                                                                                                      |
|-----------------------------------|-------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `smtp_timeout`                    | `main.ini`  | `5`                   | Тайм-аут соединения с SMTP-сервером и отправки письма, в секундах                                                                             |
| `smtp_retry_delays`               | `main.json` | `[5, 60, 600]`        | Задержки между повторными попытками отправки по SMTP, в секундах. Применяется только в **Chat Backend**                                       |
| `email_method_by_email_type`      | `main.json` | `{"default": "smtp"}` | Способ доставки (`smtp` или `mailgun`) для каждого типа письма                                                                                |
| `threads_limit_for_mail_sending`  | `main.ini`  | `10`                  | Количество параллельных потоков отправки писем в **Chat Backend**                                                                             |
| `default_from`                    | `main.ini`  | —                     | Служебный адрес отправителя для писем **Admin Backend** (регистрация, восстановление пароля, пароль оператора)                                |

Параметры с префиксом `hostedmode_` (`hostedmode_smtp_server`, `hostedmode_smtp_port` и другие) считаются **устаревшими**. Сервер обращается к ним в hosted mode и только если соответствующий параметр без префикса не задан. В новых установках используйте параметры без префикса.

## Параметры учётной записи { #account-config }

Эти параметры редактируются в [редакторе настроек account config](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html), а часть из них доступна администратору в Панели управления.

### Адреса получателей { #account-config-recipients }

Поля задаются в разделе **Адреса электронной почты** на странице [Общие настройки](https://webim.ru/kb/control-panel/settings-general.html#email). В каждом поле можно указать несколько адресов через запятую.

| Параметр            | Поле в Панели управления    | Назначение                                                                                                                                                               |
|---------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `offline_email`     | **Для оставленных сообщений** | Получатели оставленных сообщений. Первый адрес из списка подставляется в `Reply-To` писем, которые сервис отправляет посетителям. Reply-To выставляется только в облаке. |
| `superviser_email`  | **Для негативных отзывов**    | Получатели писем о негативной оценке оператора и о долгом ожидании ответа                                                                                                |
| `stats_email`       | **Для ежедневных отчётов**    | Получатели ежедневного отчёта со статистикой                                                                                                                             |
| `low_balance_email` | —                           | Получатели биллинговых уведомлений. Если не задан, письма уходят первому администратору учётной записи                                                                   |

### Оформление писем { #account-config-appearance }

Параметры account config, влияющие на внешний вид писем:

| Параметр         | Тип      | Значение по умолчанию | Описание                                                                                                        |
|------------------|----------|-----------------------|-----------------------------------------------------------------------------------------------------------------|
| `company_name`   | `string` | —                     | Название компании: подставляется в префикс темы и в подпись писем посетителям                                   |
| `company_email`  | `string` | `null`                | Email компании: используется как адрес для ответа в письмах посетителям. Reply-To выставляется только в облаке. |
| `mail_signature` | `string` | `null`                | Подпись в письмах посетителям                                                                                   |
| `hosturl`        | `string` | —                     | Ссылка на сайт компании в подписи                                                                               |

Параметры `company_name`, `company_email`, `mail_signature` и `hosturl` можно переопределить на уровне отдела: тогда письма по диалогам этого отдела оформляются его значениями.

### Отправка диалогов на почту { #account-config-transcripts }

| Параметр                                   | Тип       | Значение по умолчанию | Описание                                                                                          |
|--------------------------------------------|-----------|-----------------------|-------------------------------------------------------------------------------------------------|
| `show_visitor_send_chat_to_email_button`   | `boolean` | `true`                | Показывать посетителю кнопку отправки диалога на почту. При выключении сервер отклоняет такие запросы |
| `show_operator_send_chat_to_email_button`  | `boolean` | `true`                | Показывать оператору кнопку отправки диалога на почту                                               |
| `visitor_send_chat_history_per_chat_limit` | `integer` | `3`                   | Сколько раз за один диалог посетитель может отправить историю на почту                              |
| `operator_send_chat_history_per_chat_limit`| `integer` | `3`                   | Сколько раз за один диалог оператор может отправить историю на почту                                |
| `visitor_email_changing_per_chat_limit`    | `integer` | `3`                   | Сколько раз за один диалог посетитель может сменить свой адрес                                      |

При превышении любого из лимитов запрос отклоняется.

### Непрочитанные сообщения посетителю { #account-config-unread }

| Параметр                                             | Тип       | Значение по умолчанию | Описание                                                                                                   |
|------------------------------------------------------|-----------|-----------------------|------------------------------------------------------------------------------------------------------------|
| `send_unread_messages_to_visitor_by_email`           | `string`  | `always`              | `always` — всегда, `started_offline` — только для офлайн-обращений, `never` — не отправлять                    |
| `unread_chat_sending_to_visitor_by_email_timeout`    | `integer` | `600`                 | Сколько секунд сообщение должно оставаться непрочитанным, прежде чем уйдёт письмо                              |
| `unread_chat_sending_to_visitor_by_email_max_timeout`| `integer` | `86400`               | Если сообщение не прочитано дольше этого времени, письмо не отправляется: сообщение считается слишком старым   |

### Негативные оценки и ожидание ответа { #account-config-rates }

| Параметр                                        | Тип       | Значение по умолчанию | Описание                                                                                   |
|-------------------------------------------------|-----------|-----------------------|----------------------------------------------------------------------------------------------|
| `send_operator_rate_mail_immediately`           | `boolean` | `true`                | Отправлять письмо о негативной оценке сразу после оценки                                        |
| `send_operator_rate_mail_on_chat_close`         | `boolean` | `false`               | Отправлять письмо о негативной оценке при закрытии диалога                                       |
| `timeout_for_send_email_about_visitor_waiting`  | `integer` | `240`                 | Минимальный интервал между письмами о том, что посетитель долго ждал ответа, в минутах            |

### Почтовый сервер отдельной учётной записи { #account-config-smtp }

Параметр `smtp_server` типа `json` в account config позволяет задать собственный почтовый сервер для конкретной учётной записи. Если он заполнен, серверные параметры `smtp_*` для писем этой учётной записи игнорируются.

```
{
  "host": "smtp.example.local",
  "port": "25",
  "user": "postmaster@example.local",
  "pass": "qwerty123",
  "auth": "login",
  "encr": "",
  "timeout": "5",
  "retry_delays": [5, 60, 600]
}
```

Поля `auth` и `encr` принимают те же значения, что и одноимённые серверные параметры: `auth` — `login`, `plain`, `cram-md5` или пустая строка; `encr` — `tls`, `ssl` или пустая строка.

!!! Note "N.B."
    Собственный SMTP учётной записи применяется только к письмам **Chat Backend**. Письма **Admin Backend** (регистрация, восстановление пароля, пароль оператора, ежедневная статистика) всегда уходят через серверную конфигурацию SMTP (в main.ini/json).

### Статистика и Email-каналы { #account-config-misc }

| Параметр                             | Тип       | Значение по умолчанию     | Описание                                                                                                                       |
|--------------------------------------|-----------|---------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| `analytics_v2_stats`                 | `boolean` | `true`                    | Доступ к статистике. Обязательное условие ежедневной рассылки отчёта                                                           |
| `stats_w_chats`                      | `boolean` | `true`                    | Прикладывать историю диалогов к письму со статистикой                                                                          |
| `imap_check_period`                  | `integer` | `60`                      | Период опроса почтового ящика по IMAP в канале **Электронная почта через IMAP**, в секундах. Значения меньше `60` игнорируются |
| `default_email_subject`              | `string`  | `""`                      | Тема исходящих писем в Email-канале по умолчанию                                                                               |
| `broadcast_delay_between_recipients` | `json`    | `{"history-chats": 1}`    | Пауза между получателями при массовой рассылке, в секундах                                                                     |

## Как включить и отключить рассылку { #on-off }

Отдельного переключателя «отключить всю почту» нет. Рассылка управляется по типам писем:

| Что отключить                                  | Как                                                                                                                    |
|------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Всю отправку в **Chat Backend**                | Не задавать `smtp_server`/`smtp_port` и `mailgun_key`. Письма будут отбрасываться с ошибкой в логе; способ не рекомендуется |
| Оставленные сообщения                          | Очистить поле **Для оставленных сообщений** (`offline_email`)                                                               |
| Негативные оценки и письма о долгом ожидании    | Очистить поле **Для негативных отзывов** (`superviser_email`). Отдельно: `send_operator_rate_mail_immediately` и `send_operator_rate_mail_on_chat_close` в `false` |
| Ежедневный отчёт со статистикой                 | Очистить поле **Для ежедневных отчётов** (`stats_email`) либо выключить `analytics_v2_stats`                                |
| Отправку диалога посетителем                    | `show_visitor_send_chat_to_email_button` в `false`                                                                         |
| Отправку диалога оператором                     | `show_operator_send_chat_to_email_button` в `false`                                                                        |
| Непрочитанные сообщения посетителю              | `send_unread_messages_to_visitor_by_email` в `never`                                                                       |
| Дублирование push-уведомлений на почту          | Обнулить колонку `pushbyemail` в таблице `operatordevice` служебной базы данных: интерфейса для этого признака нет            |
| Письмо с активацией при регистрации             | `signup_activation_email_enabled` в `false`                                                                                |
| Внутреннее уведомление о регистрации            | Не задавать `registration_mail_jira`                                                                                        |
| Письмо с паролем новому оператору               | Снять отметку об отправке пароля при создании оператора. Для операторов, создаваемых через SSO, письмо отключить нельзя      |
| Служебные и биллинговые уведомления             | Отправляются только в облачной конфигурации; в локальной отключены по умолчанию                                              |
| Счёт на оплату                                  | Не задавать `service_notifications_emails`                                                                                   |

!!! Note "N.B."
    Отключить письма о восстановлении пароля нельзя: это часть механизма доступа к учётной записи.

---

Источник: https://webim.ru/kb/devops/email-notifications.html
