ДОКУМЕНТАЦИЯ
ПОЧТА · § 013
Покупатель оплатил товар - на его email автоматически уходит письмо с подтверждением: ID заказа, что купил, на какой ник, на сколько и когда. Всё через твой SMTP, без внешних сервисов и подписок.
§ 013.01
Доверие. Покупатель сразу после оплаты видит письмо с реквизитами заказа и не гадает, прошла ли оплата.
Доказательство покупки. Если игрок утверждает что не получил товар, у него есть письмо с ID заказа - не надо рыться в логах сервера.
Маркетинг. В шаблон письма можно вставить кнопку "перейти на сервер", промокод на следующую покупку, ссылку на TG-канал.
§ 013.02
Логика отправки в backend
Письмо отправляется автоматически в момент когда платёжная система прислала вебхук об успешной оплате. На это влияет несколько проверок:
Включить отправку
SMTP должен быть включён в настройках. Если выключен - письма не уходят, даже если все остальные поля заполнены.
Почта покупателя
У платежа должен быть 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 у большинства хостеров заблокирован, не используй его.
§ 013.04
Открой в админ-панели "Настройки → Общее → Отправка писем (SMTP)" и заполни поля:
Включить отправку
Позволяет временно отключить письма без удаления настроек.
SMTP-хост / Порт / Защищённое соединение
Из шага 01. Защищённое соединение включается для порта 465.
Логин / Пароль
Логин (обычно полный email) и пароль приложения.
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
{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
※ Письма не доходят даже после теста? Пиши в Telegram @zWork1.