ДОКУМЕНТАЦИЯ
ПОЧТА · § 013
Покупатель оплатил товар - на его email автоматически уходит письмо с подтверждением: ID заказа, что купил, на какой ник, на сколько и когда. Всё через твой SMTP, без внешних сервисов и подписок.
§ 013.01
Чек по email - это не просто формальность
Доверие. Покупатель видит письмо с реквизитами заказа сразу после оплаты - это снимает 90% вопросов "а оплатилось ли".
Доказательство покупки. Если игрок утверждает что не получил товар, у него есть письмо с ID заказа - не надо рыться в логах сервера.
Юридическая сторона. При приёме платежей онлайн чек на email формально считается чеком о приёме. У платёжки свой чек, но твоё письмо - это подтверждение со стороны магазина.
Маркетинг. В шаблон письма можно вставить кнопку "перейти на сервер", промокод на следующую покупку, ссылку на TG-канал - всё что подкручивает retention.
§ 013.02
Логика отправки в backend
Письмо отправляется автоматически в момент когда платёжная система прислала вебхук об успешной оплате. На это влияет несколько проверок:
Включить отправку
SMTP должен быть включён в настройках. Если выключен - письма не уходят, даже если все остальные поля заполнены.
Почта покупателя
У платежа должен быть email покупателя (он указывается на витрине магазина). Без email письму просто некуда уходить.
Не demo
Демо-платежи (созданные через "Тест" в админке) не шлют письма - чтобы не спамить себе при отладке.
Не отправлено ранее
Защита от дублей: если письмо уже ушло, повторно не отправится. В админке есть кнопка "переотправить" если что-то пошло не так.
§ 013.03
Любой провайдер: Gmail, Yandex, Mail.ru, корпоративный, свой
Тебе нужны 4 параметра: хост, порт, логин, пароль. Ниже примеры популярных провайдеров.
Gmail (через App Password)
SMTP CONFIG
host: smtp.gmail.com
port: 587
secure: false # STARTTLS на 587
user: твой-аккаунт@gmail.com
password: # App Password, не основной пароль аккаунта
※ Включи 2FA в Google-аккаунте, потом сгенерируй App Password: myaccount.google.com/apppasswords. Основной пароль аккаунта в SMTP не работает - Google его блокирует.
Yandex (через пароль приложения)
SMTP CONFIG
host: smtp.yandex.ru
port: 465
secure: true # SSL на 465
user: твой-аккаунт@yandex.ru
password: # пароль приложения, не основной
※ В Яндекс ID включи "Пароли приложений", создай новый для "Почты": id.yandex.ru/security. Без этого SMTP вернёт authentication failed.
Mail.ru (через пароль для внешних приложений)
SMTP CONFIG
host: smtp.mail.ru
port: 465
secure: true
user: твой-аккаунт@mail.ru
password: # пароль для внешних приложений из настроек безопасности
Про "secure" и порты
port 465 = SSL/TLS на момент подключения, ставь secure: true. port 587 = STARTTLS (шифрование добавляется после), ставь secure: false. Порт 25 в 99% случаев заблокирован у провайдеров - не используй.
§ 013.04
Все настройки в одном месте.
Открой админ-панель и иди в "Настройки -> Email". Заполни поля:
Включить отправку
Главный переключатель. Если выключен - письма не уходят, можно использовать чтобы временно отключить отправку без удаления настроек.
SMTP-хост / Порт / Защищённое соединение
Из шага 01 - адрес SMTP-сервера и порт. Чекбокс secure для SSL (порт 465).
Логин / Пароль
Логин (обычно полный email) и пароль приложения.
Почта отправителя
У большинства провайдеров обязан совпадать с user (иначе письмо отклонят как спуфинг).
Имя отправителя
Его увидит покупатель в инбоксе. Например "Donate Server" или название твоего магазина.
§ 013.05
Проверка перед боевой эксплуатацией
В админке под формой SMTP есть кнопка "Отправить тестовое письмо". Введи свой email и нажми - на адрес уйдёт демо-чек с фейковыми данными.
Возможные ответы:
ok: true
Письмо ушло. Проверь почту (включая папку "Спам" если первый раз). Тема будет с префиксом "[ТЕСТ]".
400 ValidationError
Не заполнен host или fromEmail. Вернись в настройки и проверь поля.
502 SMTP error
SMTP-сервер не принял подключение или авторизацию. Самые частые причины ниже.
§ 013.06
HTML с плейсхолдерами, которые backend подставит из данных платежа
Он состоит из двух частей:
SUBJECT
Тема письма
Одна строка, поддерживает плейсхолдеры. Например: "Чек по заказу #{paymentIdShort}".
HTML
Тело письма
Полноценный HTML с инлайн-стилями. Все плейсхолдеры экранируются для безопасности (защита от HTML-инъекций через ник игрока).
Минимальный пример тела письма:
HTML
<div style="font-family: sans-serif; padding: 24px;"> <h2>Спасибо за покупку!</h2> <p>Заказ {paymentIdShort} на ник {nickname}</p> <p>Товар: {productName} x {quantity}</p> <p>Сумма: {totalAmount} {currency}</p> <p>Оплачено: {paidAt} через {providerName}</p> <p>Вход на сервер: {shopIp}</p> </div>
※ В админке есть предпросмотр - сразу видно как будет выглядеть письмо с подставленными данными. Не нужно гонять тестовые письма для каждого изменения вёрстки.
§ 013.07
Полный список того, что можно подставить в subject и html
{paymentId}
Полный ID заказа в системе.
{paymentIdShort}
Короткий ID (первые 8 символов) для понятного отображения.
{nickname}
Никнейм покупателя на сервере.
{email}
Email покупателя.
{productName}
Название товара.
{quantity}
Итоговое количество единиц товара.
{userSelectedCount}
Сколько штук покупатель выбрал на витрине.
{productPrice}
Цена за единицу.
{totalAmount}
Итоговая сумма платежа.
{currency}
Валюта платежа (RUB, USD и т.д.).
{providerName}
Платёжная система ("ЮKassa", "Heleket", и т.д.).
{paidAt}
Дата и время оплаты в формате DD.MM.YYYY HH:mm (МСК).
{shopName}
Название магазина из настроек.
{shopIp}
IP сервера для входа.
{shopUrl}
Адрес магазина.
{contactEmail}
Email для связи с поддержкой.
§ 013.08
Самые частые проблемы при первой настройке
Authentication failed
Используешь основной пароль аккаунта вместо пароля приложения. Gmail/Yandex/Mail.ru блокируют SMTP по обычному паролю - нужен App Password / пароль приложения.
Connection timeout
VPS не может подключиться к SMTP-серверу. Чаще всего хостер блокирует исходящий порт 25 или 465. Попробуй сменить порт (587 вместо 465) или открыть тикет в саппорт хостера.
Письма в спаме
Норма для первой пары писем с нового домена. Если есть свой домен - настрой SPF, DKIM и DMARC в DNS. С Gmail/Yandex как отправитель этой проблемы обычно нет.
550 from-address not allowed
fromEmail не совпадает с user. Большинство провайдеров требует чтобы отправитель совпадал с аутентифицированным аккаунтом.
Письмо не пришло, но ok: true
SMTP принял сообщение, но дальше что-то отвалилось. Проверь логи backend (docker compose logs backend) - там видно что отправилось и кому.
§ 013.09
SMTP настроен, чеки уходят
※ Письма не доходят даже после теста? Пиши в Telegram @zWork1 - с реальным конкретным провайдером всегда быстрее разобраться, чем по общим симптомам.