1. SMTP интеграции (`outboundMail`)

Обновлено: Aug 31, 2026Раздел: Интеграции

Исходящая почта (SMTP)

Mailoo отправляет электронную почту через три отдельных уровня. У каждого уровня свои учётные данные, границы безопасности и предназначенные получатели.

::: {.contents local="" depth="2"} :::

1. SMTP интеграции (outboundMail)

Что: SMTP-настройки, сохранённые в конкретной интеграции в integration.config.outboundMail (панель управления: Подключение и настройки → Исходящая почта (SMTP)).

Кому отправляется почта: Конечным пользователям и бизнес-процессам только этой интеграции, например:

  • Создать ответ на входящие сообщения в панели управления (FORM / CONTACT_FORM).
  • Опциональное приветственное письмо после новой подписки через форму при настроенной кампании ON_EVENT / SUBSCRIBER_CREATED.
  • Транзакционная отправка одному получателю: серверный вызов POST …/webhooks/transactional/…/send (область transactional.send) --- см. transactional-email{.interpreted-text role="doc"}.
  • Оформление заказа из каталога: письмо-подтверждение покупателю после POST …/market/…/orders (тот же outboundMail интеграции Market, которой принадлежит каталог).

API: Маршруты только для владельца (Bearer) для обновления outboundMail и тестирования SMTP:

POST /api/v1/projects/{projectUid}/integrations/{integrationId}/outbound-mail/test

Поддерживаемые типы интеграций для этой панели и тестового маршрута: FORM, CONTACT_FORM и MARKET.

Безопасность: SMTP-пароли хранятся в зашифрованном виде (переменная окружения API MAIL_SMTP_ENCRYPTION_KEY). API никогда не возвращает шифротекст или открытый текст клиентам; ответы могут содержать только hasSmtpPassword.

Без резервирования: Если SMTP интеграции отсутствует, некорректен или отправка не удалась, Mailoo не подставляет глобальную почтовую службу. Создать ответ в панели управления возвращает ошибку, если SMTP не настроен; приветственные письма пропускаются с записью в журнал при недоступном SMTP; заказы из каталога возвращают emailToCustomer.status: NOT_CONFIGURED, если outboundMail не задан.

На хосте API для шифрования SMTP-паролей требуется: MAIL_SMTP_ENCRYPTION_KEY.

2. SMTP генератора предложений (отдельно от outboundMail)

Что: Почтовые настройки для каждого генератора предложений в OfferGeneratorMailSettings (не integration.config.outboundMail).

Кому отправляется почта: Заполнителям мастера (доставка клиенту) и опциональному внутреннему адресу уведомлений, настроенному на генераторе.

Почему отдельно: Генератор предложений может использовать другие фирменный стиль, лимиты ретрансляции или операторов, отличные от остальной интеграции Market.

В текущей версии SMTP генератора предложений не объединён с outboundMail интеграции.

3. Глобальный / платформенный SMTP (GLOBAL_SMTP_*, GLOBAL_MAIL_FROM)

Что: Переменные окружения только на хосте API.

Назначение: Зарезервировано для уведомлений оператора / платформы (биллинг, предупреждения безопасности, комплаенс, будущая системная почта). Не используется для писем подписчикам, подтверждений покупателям каталога или доставки генератора предложений.

Текущее поведение: Ни одна пользовательская функция не зависит от глобального SMTP в этом релизе; настройте его при внедрении платформенной рассылки.

Без резервирования: Глобальный SMTP никогда не подставляется при сбое SMTP интеграции.

Внешняя исходящая почта (сайты интеграторов)

Поддерживается: серверные или BFF-вызовы к API Mailoo, которые создают исходящее сообщение внутри интеграции и Mailoo отправляет его через outboundMail. Примеры:

  • Транзакционная отправка --- POST …/webhooks/transactional/…/send (область transactional.send): создаёт Message, TransactionalSend, синхронизацию подписчика, отслеживание, опциональные вебхуки доставки. См. transactional-email{.interpreted-text role="doc"}.
  • Создание заказа из каталога --- подтверждение покупателю после POST …/market/…/orders.

Не поддерживается: использование Mailoo как SMTP-ретранслятора без сохранения состояния или молчаливой отправки без записей сообщений в Mailoo:

  • Не встраивайте хост/пользователя/пароль outboundMail SMTP в код интегратора или публичные браузерные сборки.
  • Не ожидайте API «отправь этот сырой MIME прямо сейчас» без жизненного цикла Message / подписчик / отписка.

Интеграторам, которым нужен полный контроль над инфраструктурой доставки, следует использовать собственную почтовую службу на бэкенде. Внешний путь Mailoo --- это всегда инициирование обработки на стороне Mailoo (журналы аудита, согласие, идемпотентность), а не экспорт учётных данных.

Тестовое письмо из панели управления

В разделе Подключение и настройки → Исходящая почта (SMTP) нажмите Отправить тестовое письмо, чтобы проверить текущие значения полей (сохранять предварительно не обязательно). Mailoo отправит одно письмо на e-mail вашей учётной записи Mailoo (авторизованный пользователь). Тест сам по себе ничего не сохраняет; сохранение выполняется кнопкой Сохранить настройки SMTP.

Формат адреса отправителя (обязательно): простой e-mail (news@yourdomain.com) или отображаемое имя с адресом в угловых скобках (Newsletter <news@yourdomain.com>). Одно отображаемое имя (например, Consolieri Team) отклоняется с ошибкой 400 при сохранении и тестировании --- без addr-spec многие получатели (включая Gmail) отклоняют письмо с ошибкой From header is missing.

Успешный тест ≠ доставка: HTTP 200 / успех в интерфейсе означает, что SMTP-сервер принял сообщение. Это не гарантирует доставку удалённым MTA в почтовый ящик получателя. Асинхронные возвраты после принятия не отражаются в ответе теста.

Успешный тест в JSON содержит sentTo, а при наличии --- messageId и smtpResponse.

Если на хосте API отсутствует MAIL_SMTP_ENCRYPTION_KEY и вы вводите новый пароль SMTP в форме, сохранение и тест возвращают 503 с понятным сообщением --- установите ключ на API (одинаковый на всех репликах), например openssl rand -base64 32.

API владельца (опционально)

То же, что и тест из панели управления: POST /api/v1/projects/{projectUid}/integrations/{integrationId}/outbound-mail/test с авторизацией Bearer; тело { "outboundMail": { … } } соответствует форме поля outboundMail при PATCH.

📚