API: Почта

Базовый путь: /api/v1/mail

Служба Уведомления (notifications) — шлюз исходящей SMTP-почты: API, Event Receivers и тестовый запуск из админки. Это не cron-служба; в UI нет расписания — достаточно включить канал и настроить SMTP. Подробнее для администратора: Службы → notifications.

Отправка писем через SMTP портала. Требуется:

• настроенный SMTP (админка → Настройки → SMTP / Почта);
• включённая служба notifications (Админка → Службы);
• JWT-авторизация.

Тест SMTP (POST /admin/settings/smtp/test) проверяет соединение независимо от того, включена ли служба.

POST /mail/send

Поставить письмо в очередь (по умолчанию) или отправить сразу.

Права:

• portal_admin — всегда;
• остальные пользователи — только если в SMTP-настройках включено allowAuthenticatedSend.

{
  "to": "user@company.local",
  "cc": ["cc@company.local"],
  "bcc": [],
  "subject": "Тема письма",
  "text": "Текст",
  "html": "<p>HTML</p>",
  "replyTo": "noreply@company.local",
  "async": true
}

• to — строка или массив email;
• text или html — обязательно хотя бы одно;
• async: true (по умолчанию) — задание в portal_jobs, ответ 202 с jobId;
• async: false — немедленная отправка (только portal_admin).

Ответ (async):

{
  "success": true,
  "data": {
    "async": true,
    "jobId": "uuid",
    "status": "pending"
  }
}

Типы заданий (worker)

job_type	Описание
notifications.sendEmail	Прямая отправка: to, subject, text/html
notifications.sendEventEmail	Письмо по событию Event Receiver

Event Receiver для почты

{
  "eventName": "listItem.created",
  "title": "Почта при создании элемента",
  "serviceKey": "notifications",
  "jobType": "notifications.sendEventEmail",
  "config": {
    "to": "admin@company.local",
    "subject": "Событие: {{eventName}}",
    "text": "Пользователь {{userLogin}}, ресурс {{resourceType}} {{resourceId}}"
  }
}

Подстановки в шаблоне: {{eventName}}, {{userLogin}}, {{userId}}, {{resourceType}}, {{resourceId}}, {{details}}.

Админка: SMTP

Метод	Путь
GET	/admin/settings/smtp
PUT	/admin/settings/smtp
GET	/admin/settings/smtp-status
POST	/admin/settings/smtp/test — { "to": "..." }

Настройки хранятся в portal_services.config службы notifications. Опциональный fallback — переменные SMTP_* в .env.