# Интеграция с почтовым клиентом

## Общая информация

Для подключения почтового клиента к dbmail следует пройти несколько шагов:

1. Настроить почту, с которой должна осуществляться рассылка.
2. Настроить конфигурационный файл проекта.
3. Настроить роли сервера.
4. Создать учётную запись и профиль в SQL Server Management Studio (SSMS).
5. Проверить работоспособность рассылки при помощи SQL-запроса.

## Настройка почты

Настройка почты, с которой должна осуществляться рассылка, хорошо описана [здесь](https://www.advantshop.net/help/pages/email-google-yandex). К рассмотрению рекомендуется раздел "Примеры настроек для различных почтовых сервисов" для "Почта Яндекс", включая такие подпункты как "Пароли приложения" и "Возможные ошибки при использовании @yandex.ru и SSL настройки".

## Настройка конфигурационного файла проекта

### Настройки сервиса электронной почты и смс сообщений

Чтобы отправка писем на почту работала, необходимо подключить почтовый ящик в разделе **applications.post.emails**.

!!! note
     Раздел applications { post { }} конфигурационного файла ./config/production.js

-   _**protocol**_ – используемый веб-протокол (по умолчанию `'http'`).
-   _**host**_ – имя хоста (по умолчанию `'localhost'`).
-   _**port**_ – порт для запуска (по умолчанию – `3066`).
-   _**route**_ – используемый маршрут (по умолчанию `'/api/v2.0/post'`).
-   _**script**_ – путь к модулю, запускающему сервис (по умолчанию `'ecosoft-lexema8/post'`).
-   _**attachmentRequestTimeout**_ – максимальное время ожидания загрузки файла в миллисекундах (по умолчанию `1000`).
- _**defaultEmailId**_ – идентификатор почтового ящика, который используется по умолчанию.
- _**emails**_ – словарь с описанием используемых почтовых ящиков. Ключом является уникальный идентификатор почтового ящика, а значением – объект со свойствами:
    * *host* – имя хоста smtp-сервера.
    * *port* – порт smtp-сервера.
    * *secure* – включить/выключить доставку по электронной почте с использованием TLS/STARTTLS (по умолчанию `false`). Доступные значения: `true`, `false`. (Для 'smtp.yandex.ru' значение должно быть `true`)
    * *user* – логин.
    * *pass* – пароль.
    * *userName* – имя отображаемое при отправке почты.

### Пример

``` js
applications: {
  // ...
  post: {
    defaultEmailId: 'default',
    emails: {
      default: {
        host: 'smtp.gmail.com',
        port: 587,
        secure: false,
        user: 'lexemaecm@gmail.com',
        pass: 'password',
        userName: 'Lexema'
      }
    },
  // ...
}
```

## Настройка ролей сервера
   
Для дальнейшей настройки в SSMS потребуется назначить текущем пользователю роль _sysadmin_ (или использовать пользователя с такой ролью). Для этого необходимо открыть "Обозреватель объектов". В нижней его части раскрыть папку "Безопасность" -> "Имена для входа (Logins)" -> кликнуть правой кнопкой мыши (ПКМ) по логину интересующего пользователя -> выбрать пункт "Свойства" и перейти в раздел "Роли сервера". Слева от роли sysadmin должна стоять галочка.

## Учётная запись и профиль в SSMS

Настройку dbmail в SSMS можно произвести двумя путями: с помощью SQL-запросов и с помощью интерфейса самой программы SSMS. Ниже приведена инструкция по настройке при помощи интерфейса. Требующиеся для аналогичной настройки на текущем и последующих шагах команды можно найти [здесь](https://habr.com/ru/post/179819/).

В SSMS необходимо открыть "Обозреватель объектов". В нижней его части раскрыть папку "Управление" и кликнуть ПКМ по пункту "Компонент Database Mail" и выбрать действие "Настроить компонент Database Mail". 

![Рисунок 1 "Настроить компонент Database Mail"](component-step1.jpg)

Далее необходимо создать учётную запись и профиль. Обязательные поля выделены красными прямоугольниками.

![Рисунок 2.1 Учетная запись. Обязательные поля](component-step20.jpg)

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

![Рисунок 2.2 Учетная запись. Пример](component-step2.jpg)

![Рисунок 3.1 Профиль. Обязательные поля](component-step30.jpg)

В поле "Профиль по умолчанию" (Default Profile) можно выбрать "Да" (Yes), если на проекте используется только этот профиль.

![Рисунок 3.2 Профиль. Пример](component-step3.jpg)

## Проверка работоспособности рассылки при помощи SQL-запроса

Ниже приведен запрос для первой отправки сообщения от подключенной почты при помощи dbmail. Непосредственно отправка письма осуществляется при помощи выполнения команды ```exec msdb.dbo.sp_send_dbmail```, остальные служат для донастройки (при необходимости) и проверки статуса отправки письма (```msdb.dbo.sysmail_allitems```, ```msdb.dbo.sysmail_event_log```)

``` sql
-- в настройках нужно указать созданный профиль:
--update DocflowSettings set EMailProfile='bitedo'

-- Сначала включим Service broker – он необходим для создания очередей писем, используемых DBMail
IF (SELECT is_broker_enabled FROM sys.databases WHERE [name] = 'msdb') = 0
  ALTER DATABASE msdb SET ENABLE_BROKER WITH ROLLBACK AFTER 10 SECONDS
GO
-- Включим непосредственно систему DBMail
sp_configure 'show advanced options', 1; -- если стоит 0, то следующая настройка не сработает
GO
RECONFIGURE;
GO
sp_configure 'Database Mail XPs', 1
GO
RECONFIGURE
GO

-- Далее нужно проверить, запущена ли служба DBMail:
EXECUTE msdb.dbo.sysmail_help_status_sp
-- И если она не запущена (ее статус не «STARTED»), то запустить ее запросом
EXECUTE msdb.dbo.sysmail_start_sp
-- ищем здесь свой @profile_name
EXECUTE msdb.dbo.sysmail_help_principalprofile_sp --@principal_name = 'bitedo'

-- отправим тестовое сообщение
exec msdb.dbo.sp_send_dbmail @profile_name = 'bitedo' -- отправитель
                                   , @recipients = 'user@lexema.ru' -- получатели, указывается через ;
                                   , @subject = 'theme' -- тема
                                   , @body = 'hello world' -- содержание
                                   , @body_format = 'html'
                                   
-- если статус sent – значит отправлено
select * from msdb.dbo.sysmail_allitems 
--where sent_status not like 'failed' 
order by mailitem_id desc

-- если возникли ошибки, см. логи:
select * from msdb.dbo.sysmail_event_log order by log_id desc
```

## Преодоление СПАМ-фильтра

Письма с созданного почтового ящика могут быть не отправлены по причине сработавшего СПАМ-фильтра почтового провайдера. В логах такая ошибка описана следующим образом:

```
The mail could not be sent to the recipients because of the mail server failure. (Sending Mail using Account 10 (2021-06-24T14:52:04). Exception Message: Cannot send mails to mail server. (Transaction failed. The server response was: 5.7.1 [2] Message rejected under suspicion of SPAM; https://ya.cc/1IrBc 1624528324-AOJQDun5U8-q32WauIb).)
```

Существует несколько рекомендаций, описанных в статье на сайте [carrotquest](https://www.carrotquest.io/blog/kak-ne-popast-v-spam/). В случае, если после выполнения приведенных рекомендаций отправка писем остается проваленной, можно обратиться в службу поддержки почтового сервиса.