# Почта — Решение проблем

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

Секции руководства организованы по типам проблем. Для каждой проблемы приводится:

1. **Симптом** — что описывает пользователь
2. **Что проверить** — шаги диагностики
3. **Решение** — что сделать
4. **Когда обращаться в поддержку 1Ф** — если проблему не удаётся решить на месте

## 1. SMTP и доставка писем

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

**Не отправляются письма (ошибка SMTP)**

- **Симптом:** «не работает отправка почты», «ошибка SMTP: Failed to connect to SMTP host».
- **Что проверить:** настройки почтового сервера (адрес, порт, SSL/TLS), доступность SMTP-сервера (можно ли с сервера 1Ф подключиться к SMTP по telnet), резолвинг DNS-сервера, 
- **Когда обращаться в поддержку 1Ф:** если сервер доступен, но 1Ф не отправляет — обратиться в поддержку 1Ф с текстом ошибки.

**Письма не доставляются на определённые домены**

- **Симптом:** «письма не приходят на @domain.ru, на другие домены — всё работает».
- **Что проверить:** настройки SPF/DKIM/DMARC для домена отправителя, наличие bounce-сообщений (отбивок) от почтового сервера получателя, размер отправляемого письма на соответствие лимитам.
- **Когда обращаться в поддержку 1Ф:** если bounce содержит ошибку политики (SPF fail, DMARC reject) — вопрос к администратору DNS.

**Дублирование писем при отправке смартом**

- **Симптом:** «смарт-действие "Отправить email" дублирует отправку», «при смарт-отправке приходит два одинаковых письма».
- **Что проверить:** настройку смарт-действия (не дублируется ли действие на одно событие), событие-триггер (не срабатывает ли дважды, например, при сохранении + при переходе), логи отправки.
- **Когда обращаться в поддержку 1Ф:** если действие одно и событие одно, но письмо уходит дважды — зафиксировать как баг.

**Не приходят уведомления на почту**

- **Симптом:** «перестали приходить уведомления на почту», «портал не отправляет уведомления».
- **Что проверить:** пользовательские настройки уведомлений (не отключены ли email-уведомления), настройки категории (включены ли почтовые уведомления), размер очереди уведомлений, работоспособность почтового сервера.

## 2. Ошибки почтовой библиотеки (MailKit)

С версии 2.268 платформа использует open-source библиотеку MailKit, что устраняет ряд устаревших ошибок MailBee, но накладывает новые требования к таймаутам и аутентификации.

> С версии **2.268** платформа использует open-source библиотеку **MailKit/MimeKit** вместо коммерческой MailBee.NET. Старые ошибки `MailBee.MailBeeSocketTimeoutException` и `LicenseKey is for an older version of MailBee.NET` после обновления исчезают. Если они встречаются — стенд не обновлён.

**Таймауты подключения к почтовому серверу**

- **Симптом:** в логах массово ошибки сокета IMAP/POP3/SMTP — таймауты подключения (`ServiceNotConnectedException`, `Socket connection has timed out`). До 2.268 та же проблема выглядела как `MailBee.MailBeeSocketTimeoutException`.
- **Что проверить:** доступность почтового сервера (IMAP/POP3/SMTP), нагрузку на почтовый сервер, количество почтовых ящиков, подключённых к 1Ф, настройки timeout в конфигурации (`ImapTimeout`, по умолчанию 40 секунд).
- **Когда обращаться в поддержку 1Ф:** если таймауты массовые и стабильные — проблема инфраструктуры или конфигурации.

**Ошибки аутентификации на почтовом сервере**

- **Симптом:** в логах ошибка аутентификации (`Authentication failed`, «не удаётся подключиться к ящику»).
- **Что проверить:** корректность логина/пароля ящика, использование «пароля приложения» (для Mail.ru / Yandex / Gmail), двухфакторную аутентификацию на стороне провайдера, срок действия пароля.
- **Решение:** обновить пароль ящика в AdminSPA → Почтовые ящики. После обновления — сбросить счётчик неудачных попыток.

**OutOfMemoryException при проверке сервисного IMAP-ящика**

- **Симптом:** в логах или при ручной проверке ящика — `OutOfMemoryException`. Письма в сервисном ящике (категории с подключённым email-адресом) не разбираются в задачи.
- **Когда возникает:** на ящиках с большим количеством писем. Платформа до версии 2.268 при обходе UID-набора `1:*` разворачивала диапазон в полный список UID, что приводило к нехватке памяти.
- **Что проверить:** версию системы (проблема устранена в **2.268**), размер ящика (количество писем), наличие в логах ошибки `OutOfMemoryException` при разборе большого ящика.
- **Решение:** обновить платформу до 2.268 или новее. После обновления проверка сервисных ящиков работает без ограничения по размеру — список писем больше не загружается целиком в память.
- **Когда обращаться в поддержку 1Ф:** если ошибка наблюдается на 2.268+ — обратиться в поддержку 1Ф с логом и версией.

**Лицензия MailBee (устарело)**

- **Симптом:** в логах исторических стендов до 2.268 — `LicenseKey is for an older version of MailBee.NET`.
- **Решение:** обновить платформу до 2.268 или новее — лицензионный ключ MailBee.NET больше не требуется, библиотека заменена на open-source MailKit.

## 3. Почтовые ящики — подключение и настройка

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

**Запрос ИБ-аудита: как хранятся пароли почтовых ящиков**

- **Симптом:** пользователь (ИТ-департамент, служба ИБ) в рамках аудита спрашивает, как платформа хранит пароли от почтовых ящиков — в открытом виде или зашифрованы, и каким алгоритмом.
- **Корректный ответ для первой линии:**
  > В актуальной версии пароли почтовых ящиков хранятся в БД в зашифрованном виде (AES, симметричное шифрование). Расшифровка происходит в памяти приложения при подключении к почтовому серверу. Ключ шифрования — мастер-ключ платформы, а не часть сборки: в базовой поставке это `Settings.EncKey` в настройках, в сертифицированной сборке (1F Certificate Edition) ключ вынесен в отдельный файл и в базе не хранится. Пароли защищены от прямого чтения из БД, но уровень защиты не эквивалентен HSM или внешнему хранилищу ключей.
  Пароли пользовательских ящиков хранятся в таблице `EmailMailBoxes`, сервисных ящиков категорий — в `ServiceMailBoxes` (у сервисных дополнительно ставится флаг `IsEncrypted = true`). Пароли, записанные в старом формате, читаются наравне с новыми, а их перевод на новый механизм выполняется отдельной утилитой вручную — это верно для полной сборки; в сертифицированной сборке (1F Certificate Edition) прежний формат изъят, такие значения не читаются — см. [Хранение паролей ящиков](https://help.1forma.ru/domains/mail/admin.md#хранение-паролей-ящиков). Подробнее — в [бизнес-документации](https://help.1forma.ru/domains/mail/business.md) (раздел «Хранение паролей»).

- ⚠️ **Чего не делать:** не давать клиенту ответ «пароли в открытом виде». Это устаревшая информация — шифрование есть; вопрос только в том, на какой версии установлена платформа. Если клиент работает на сборке существенно старше 2.268 — уточнить версию инсталляции и при сомнениях поднять с командой разработки.
- **См. также:** раздел ниже про добавление через AdminSPA и миграцию.

**Ящик не подключается: пароль сохранён в старом формате (сертифицированная сборка)**

- **Симптом:** на сертифицированной сборке (1F Certificate Edition) ящик не подключается, а в журнале — отказ вида «ящик id=…: пароль хранится в старом формате…». Это не сбой авторизации: значение пароля сохранено прежним форматом, который в этой сборке изъят.
- **Что не поможет:** настройка `MailBoxesLegacyReEncryptionCompleted` (в этом профиле не читается — отказ безусловен) и утилита перешифровки (её в поставке нет).
- **Решение:** заменить пароль ящика — форма редактирования ящика → «Пароль» → сохранить: при сохранении нового значения пароль перезапишется актуальным форматом. Если таких ящиков много, перевод остатка выполняется на исходной площадке, на полной сборке, до формирования дампа.
- ⚠️ **Чего не делать:** не просить сохранить форму ящика без ввода нового пароля — значение при этом не меняется, остаток остаётся прежним.

**Не удаётся добавить почтовый ящик**

- **Симптом:** «не добавляется почтовый ящик», «ошибка авторизации при добавлении».
- **Что проверить:** тип почтового сервера (IMAP/Exchange/etc.), корректность логина/пароля, порты SSL/TLS, использование «пароля приложения» (для Mail.ru / Yandex), валидность TLS-сертификата почтового сервера (после перехода на MailKit проверка строгая).
- **Решение при ошибке TLS-сертификата:** обходной путь — добавить домен почтового сервера в ключ `SettingsCustom` `DisableCertificateCheckForMailDomains` (список доменов через запятую). ⚠️ Снижает защищённость соединения — применять только для доверенных серверов и по согласованию.

**Пароль не шифруется при добавлении через AdminSPA**

- **Симптом:** «при добавлении почтового ящика через AdminSPA пароль хранится в открытом виде».
- **Когда обращаться в поддержку 1Ф:** баг безопасности — обратиться в поддержку 1Ф. Миграция ServiceMailBoxIsEncrypted должна зашифровать пароли.

**Миграция ServiceMailBoxIsEncrypted падает**

- **Симптом:** «ошибка при миграции ServiceMailBoxIsEncrypted: Deprecated», «кодовая миграция падает».
- **Когда обращаться в поддержку 1Ф:** обратиться в поддержку 1Ф с версией системы и текстом ошибки.

**Как подключить вкладку «Почта» пользователю**

- **Симптом:** «как включить почту для пользователя?»
- **Решение:** вкладка «Почта» появляется после добавления хотя бы одного почтового ящика пользователю. Добавить ящик: Профиль → Почта → Добавить ящик (или через AdminSPA → Почтовые ящики).

## 4. Смарт-действия с почтой

Проблемы со смарт-действиями почты включают сбои при отправке писем группам получателей, ошибки отображения разделов SMART в админке и проблемы разбора входящих сообщений.

**Смарт-действие «E-mail на группу» не срабатывает**

- **Симптом:** «не работает смарт-действие отправки email на группу».
- **Что проверить:** не пуста ли группа получателей, прописаны ли email-адреса у участников, корректны ли настройки полей «Кому», «Тема», «Тело» в действии, срабатывает ли событие-триггер.

**Раздел SMART в почте открывается пустым**

- **Симптом:** «в разделе SMART в почте — пусто», «не работает кнопка smart в админке в почте».
- **Что проверить:** версию системы (в 2.266 был известный баг), наличие правил в настройках mail smart.

**Не работает разбор писем с почты в категорию**

- **Симптом:** «входящие письма не разбираются в категорию», «mail smart не создаёт задачи».
- **Что проверить:** настроены ли правила mail smart (Администрирование → Почта → Smart), подключён ли почтовый ящик к категории, соответствуют ли фильтры входящим письмам, запущена ли фоновая задача MailSyncJob.
- **Когда обращаться в поддержку 1Ф:** если правила настроены, ящик привязан, но задачи не создаются.

**Не понятно, на каком письме падает смарт-фильтр после получения**

- **Симптом:** в логе ошибок массовые записи `Exception while executing Smart after receiving email` с источником `Job`.
- **Что проверить:** в тексте ошибки после этой фразы указаны `EmailId`, отправитель `From` и, если тема заполнена, `Subject` — это письмо, на котором упал смарт-фильтр. По `EmailId` письмо находится в таблице `Emails` или открывается в почтовом клиенте. Если вместо данных письма в подробностях стоит `Failed to load email info`, письмо сохранено, но перечитать его не удалось — смотреть исходный стек ниже. На стендах до 2.268 в записи есть только текст ошибки без данных письма.
- **Когда обращаться в поддержку 1Ф:** если падения массовые и не привязаны к конкретному письму.

**Сервисный ящик создаёт задачи от имени робота, а не отправителя**

**Симптом:** после включения проверки подлинности отправителя (заполнен `ServiceMailTrustedAuthservIds` или режим `enforce`) задачи из писем создаются от системного робота; исполнители и подписчики из `To`/`CC` не назначаются.

**Что проверить:**

- Есть ли в исходнике письма заголовок `Authentication-Results` от доверенного MTA (его `authserv-id` должен быть в `ServiceMailTrustedAuthservIds`).
- Проходят ли `SPF`/`DKIM`/`DMARC` и совпадает ли проверенный домен с доменом в `From`.
- Не ведётся ли рассылка с субдомена — для него нужна отдельная настройка аутентификации.
- Режим `ServiceMailSenderAuthMode`: `auto`/`audit` не меняют авторство (только журнал), `enforce` применяет проверку всегда.

**Решение:** настроить входящий шлюз так, чтобы он проставлял заголовок `Authentication-Results` для доверенных доменов, и указать его `authserv-id` в `ServiceMailTrustedAuthservIds`. Для легитимной рассылки с субдомена — настроить для него `SPF`/`DKIM`/`DMARC`.

**Когда обращаться в поддержку 1Ф:** если шлюз ставит корректный `Authentication-Results`, но письма всё равно обрабатываются от робота — приложить исходник письма и значения настроек.

**Письма со сложной HTML/CSS-разметкой (Outlook/Word) не разбираются**

- **Симптом:** отдельные входящие письма (обычно из Outlook или Word, со сложной inline-CSS вёрсткой) не разбираются в задачи; в логах — ошибка обработки HTML-разметки письма.
- **Что проверить:** версию системы — устранено в v2.268.481; если ниже, письма со сложной HTML-разметкой могут не приниматься.
- **Решение:** обновить систему до v2.268.481 или выше — приём письма больше не прерывается при ошибке обработки его HTML-разметки, письмо сохраняется.

## 5. Интерфейс почтового клиента

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

**Ошибка при открытии почтовых папок (Mail.ru)**

- **Симптом:** «при включённой "умной сортировке" на Mail.ru — ошибка при открытии папок».
- **Решение:** отключить «умную сортировку» на стороне Mail.ru (Настройки → Все настройки → Общие → Умная сортировка).

**Связанное письмо не отображается в задаче**

- **Симптом:** «не вижу связанного письма в задаче».
- **Что проверить:** способ привязки письма (через smart, вручную, через drag&drop), наличие прав у пользователя на просмотр писем.

**Письма приходят без номера задачи в теме**

- **Симптом:** «письма приходят без номера задачи в теме».
- **Что проверить:** настройки шаблона темы письма в Настройках категории → Почта → Шаблон темы (включён ли тег номера задачи).

**Ошибка при просмотре почтового ящика сервера**

- **Симптом:** «ошибка при просмотре п/я почтового сервера в AdminSPA».
- **Что проверить:** права администратора, доступность почтового сервера.

## 6. Шаблоны почтовых уведомлений

### 4.4 «Вложить письмо файлом» — `.eml` открывается некорректно в Thunderbird/Outlook

**Симптом:** в задаче, созданной через смарт-действие «Создать задачу» с опцией «Вложить письмо файлом», прикреплённый `Email.eml` при открытии во внешнем почтовом клиенте показывается как нечитаемый текст (HTML-код виден прямо в теле, форматирование не применяется). В исходнике отсутствуют транспортные заголовки `Return-Path`, `Received`, `Message-Id`, `DKIM-Signature`, `Received-SPF`; `Content-Type: text/plain` объявлен у тела, которое фактически содержит base64-закодированный HTML.

**Версии:** баг присутствовал до **2.268.356**. Исправлен в 2.268.356 и старше — `.eml` теперь отдаётся как оригинальный MIME-источник письма (если он сохранён), с полными транспортными заголовками и корректной MIME-структурой.

**Что проверить (если симптом наблюдается на 2.268.356+):**

- Сборка платформы не ниже 2.268.356 (`SELECT [Value] FROM Settings WHERE [Key] = 'AppBuildVersion'`).
- У письма-источника в БД должен быть сохранён оригинал — поле `Emails.Source` должно быть непустым:
  ```sql
  SELECT TOP 1 LEN([Source]), CHARINDEX('Return-Path', [Source])
  FROM Emails WHERE Id = @EmailId;
  ```
  Если `LEN([Source]) = 0` (или поле NULL) — это исходящее письмо или старое входящее без сохранённого исходника. В этом случае система пересобирает письмо заново: транспортные заголовки восстановить нельзя (их у самой 1Ф нет), но HTML-тело корректно объявляется как `text/html`. Это **штатное** поведение для писем без источника, не баг.

- Если на актуальной сборке у входящего письма пустой `Emails.Source` — отдельный случай для обращения в поддержку 1Ф (могло сломаться сохранение исходника при приёме письма).

**Когда обращаться в поддержку 1Ф:** баг на сборке ниже 2.268.356 — обновить платформу. На актуальной сборке с непустым `Emails.Source`, но всё равно битым `.eml` — обращаться как с новым дефектом.

---

Сбои в работе шаблонов почтовых уведомлений выражаются в отсутствии внешних ссылок на задачи или ошибках согласования после обновления системы.

**Шаблоны почтовых уведомлений — кастомизация и ошибки**

- **Симптом:** «нужно изменить шаблон уведомления», «в письмах-уведомлениях из 1Ф нет внешней ссылки на задачу».
- **Что проверить:** настройки шаблонов уведомлений (Администрирование → Уведомления → Шаблоны), наличие тега `{ExternalLink}` в переменных шаблона, настройку внешнего URL системы (AdminSPA → Настройки → Общие → Внешний URL).
- **Когда обращаться в поддержку 1Ф:** если шаблон корректен, переменные подставляются, но ссылки всё равно нет — обратиться в поддержку 1Ф.

**Ошибка «нет шаблона письма» после обновления**

- **Симптом:** «после обновления на 2.266: ошибка при акцепте подписи — нет шаблона письма», «невозможно вынести резолюцию, хотя встроенные шаблоны отключены».
- **Что проверить:** версию системы (воспроизводится на 2.266), статус встроенных шаблонов (отключены ли), наличие пользовательского шаблона для действия (акцепт подписи / резолюция).
- **Когда обращаться в поддержку 1Ф:** обратиться в поддержку 1Ф с указанием версии (регрессия после обновления).

## 7. Фоновые задачи отправки почты (Jobs)

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

**Ошибка EmailJobSend / EmailJobSendSecondary в однопоточном режиме**

- **Симптом:** «ошибка при запуске джобов EmailJobSend, EmailJobSendSecondary в однопоточном режиме».
- **Что проверить:** логи фоновых задач (точный текст ошибки), конфигурацию потоков (однопоточный vs многопоточный режим), наличие застрявших писем в очереди.
- **Когда обращаться в поддержку 1Ф:** обратиться в поддержку 1Ф с логами (вероятная проблема конкурентного доступа).

**Ошибка получения параметров действия «Отправить email» в пакете**

- **Симптом:** «System.Exception: Не удалось получить параметры действия Отправить email в пакете 'название пакета'».
- **Что проверить:** существование указанного пакета действий, не был ли пакет переименован/удалён/повреждён после обновления, настройки привязки смарт-действия к пакету.
- **Когда обращаться в поддержку 1Ф:** обратиться в поддержку 1Ф с полным текстом исключения и названием пакета.

## 8. Интерфейс администрирования почты

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

**Не работает интерфейс почты в старой админке**

- **Симптом:** «не работает интерфейс почты в старой админке», «страница почты в старой админке не загружается».
- **Что проверить:** использование старой админки (рекомендовать переход на AdminSPA), версию системы (старая админка может быть устаревшей).
- **Решение:** рекомендовать использовать AdminSPA для управления почтой. Если клиент не может перейти — обратиться в поддержку 1Ф.

**Ошибка при настройке привязки пакетов к почтовым папкам**

- **Симптом:** «Почта → Смарт → Привязки пакетов действий к почтовым папкам — ошибка при нажатии на созданную строку».
- **Что проверить:** версию системы, воспроизводимость на чистой привязке, консольные ошибки в браузере (F12).
- **Когда обращаться в поддержку 1Ф:** баг интерфейса — обратиться в поддержку 1Ф с версией и скриншотом.

**Не видны адреса получателей в отправленных письмах**

- **Симптом:** «в отправленных письмах не видны адреса получателей».
- **Что проверить:** версию системы, масштаб проблемы (для всех пользователей или одного), отображение получателей при открытии самого письма.
- **Когда обращаться в поддержку 1Ф:** баг отображения — обратиться в поддержку 1Ф.

## 9. Аутентификация, доступ и смарт-переменные в почте

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

**Восстановление пароля — страница перезагружается при вводе кода**

- **Симптом:** «после отправки кода восстановления на почту страница ввода кода перезагружается», «не удаётся восстановить пароль».
- **Что проверить:** воспроизводимость в другом браузере, консольные ошибки (F12), версию системы и тип интерфейса портала (новый / старый).
- **Когда обращаться в поддержку 1Ф:** обратиться в поддержку 1Ф. Как временный обходной путь — сбросить пароль через AdminSPA.

**Попытки входа в отключённый почтовый ящик**

- **Симптом:** «почтовый ящик временно отключён, но в логах видны попытки входа».
- **Что проверить:** фоновую синхронизацию (MailSyncJob может пытаться подключиться к отключённому ящику), статус ящика в AdminSPA (действительно ли отключён).
- **Решение:** если ящик отключён корректно, попытки входа — штатное поведение MailSyncJob, который проверяет все ящики. Для полной остановки — удалить ящик или отключить job для конкретного ящика.

**Как получить email получателя в смартах раздела «Почта»**

- **Симптом:** «как в смарте Почты получить email-адрес получателя?», вопрос по настройке.
- **Что проверить:** тип смарт-действия (обработка входящих или отправка), доступные переменные в контексте смарта (документация: [Настройка почты](https://help.1forma.ru/domains/mail/admin.md)).
- **Решение:** в контексте смарт-обработки почты доступны переменные письма (отправитель, получатели, тема). Конкретный набор переменных зависит от типа действия. При отсутствии нужной переменной — обратиться в поддержку 1Ф как запрос на доработку.

## Чеклист для первичной диагностики

Для проведения первичной диагностики неполадок в работе почтовой службы рекомендуется последовательно проверить ключевые параметры окружения.

1. **Тип проблемы** — отправка, приём, подключение ящика, смарт-обработка, интерфейс
2. **Версия системы**
3. **Тип почтового сервера** — Exchange, IMAP, SMTP (провайдер: Yandex, Mail.ru, MS Exchange и т.д.)
4. **Текст ошибки** — точная формулировка из логов / экрана
5. **Один пользователь или все**
6. **Работало ли раньше** — и что изменилось (обновление, смена сервера и т.д.)

## Когда обращаться в поддержку 1Ф

Обращаться в поддержку 1Ф следует при критических ошибках в фоновых заданиях, багах интерфейса или проблемах безопасности.

- Массовые MailBee-таймауты (инфраструктура)
- Ошибка лицензии MailBee (замена ключа)
- Миграция ServiceMailBoxIsEncrypted падает
- Пароли почтовых ящиков не шифруются (безопасность)
- Дублирование писем при одном смарт-действии (баг)
- Mail smart не разбирает письма при корректных настройках
- Ошибка «нет шаблона письма» после обновления (регрессия 2.266)
- Ошибка EmailJobSend в однопоточном режиме
- Ошибка получения параметров действия в пакете отправки email
- Баги интерфейса привязки пакетов к почтовым папкам
- Восстановление пароля — страница перезагружается

**Связанные документы:**

- [Почта — бизнес-логика](https://help.1forma.ru/domains/mail/business.md) — бизнес-логика почты
- [Почта — администрирование](https://help.1forma.ru/domains/mail/admin.md) — настройка почты и smart-обработка