HindiBindi Mailing Admin

API документация

Все доступные REST-ручки. Админские ручки используют session Bearer token, публичная отправка использует API key.

Админка сначала делает POST /api/auth/login и дальше передает session token в Authorization: Bearer .... Внешние интеграции для отправки писем используют токены из вкладки “Ключи API”.

BASE_URL=https://mailing.hindibindi.ru
Authorization: Bearer trafara_xxx

Отправка писем

Транзакционные письма и отправка сохраненного шаблона.

POST /api/send
{
  "to": "client@example.com",
  "subject": "Hello",
  "html_body": "<p>Hi</p>",
  "text_body": "Hi",
  "project_id": 1
}

POST /api/send-template
{
  "to": "client@example.com",
  "template_id": 3,
  "variables": {"name": "Ivan"},
  "project_id": 1
}

Ключи API и проекты

Проект хранит SMTP-настройки. API key привязан к проекту.

GET  /api/projects
POST /api/projects
DELETE /api/projects/:id

GET  /api/api-keys
POST /api/api-keys
DELETE /api/api-keys/:id

Аудитории / списки получателей

Создание баз, добавление адресов, массовый импорт TXT/CSV.

GET  /api/lists
POST /api/lists
DELETE /api/lists/:id
GET  /api/lists/:id/recipients
POST /api/lists/:id/recipients
DELETE /api/lists/:id/recipients/:recipient_id
POST /api/lists/:id/recipients/import

Шаблоны

CRUD HTML-шаблонов и preview с Handlebars-переменными.

GET  /api/templates
POST /api/templates
PUT  /api/templates/:id
DELETE /api/templates/:id
POST /api/templates/:id/render

Рассылки

Запуск кампании по шаблону и аудитории, просмотр истории и активного прогресса.

GET  /api/campaigns
POST /api/campaigns
GET  /api/campaigns/active

Входящие и адреса

Генерация/создание адресов, получение списка писем, просмотр и удаление письма.

GET  /api/inbox/addresses
POST /api/inbox/addresses
DELETE /api/inbox/addresses/:id
GET  /api/inbox/emails
GET  /api/inbox/emails/:id
DELETE /api/inbox/emails/:id

SMTP deliverability guide

Настройка SMTP-модуля для нормальной доставки

Сначала выставьте DNS и PTR, потом добавляйте проект в админке и только после тестов запускайте прогрев. Рабочий API без SPF, DKIM, DMARC и reverse DNS будет отправлять письма технически, но почтовики будут чаще класть их в spam.

1. Что должно совпадать

From: адрес из домена отправки, например noreply@hindibindi.ru.
SMTP host: имя из deploy config: mailing.hindibindi.ru.
PTR/rDNS: у VPS-провайдера для IP стоит то же имя: mailing.hindibindi.ru.
DKIM: подпись должна быть для того домена, от имени которого уходят письма.

2. Пример из скринов

web/admin domain: mailing.hindibindi.ru
sender domain: hindibindi.ru
SMTP host: mailing.hindibindi.ru
SMTP port: 587
SMTP user: noreply@hindibindi.ru
server IPv4: SERVER_IPV4
PTR: mailing.hindibindi.ru
TTL: Auto
MX priority: 10

3. Порты

25/tcp нужен для приема/межсерверной SMTP-доставки, если сервер сам отправляет наружу.
587/tcp используйте в проекте админки: STARTTLS.
465/tcp используйте только если ваш SMTP реально слушает implicit TLS.
80/443 нужны для админки, API и Let's Encrypt.

DNS-записи для текущего SMTP deploy

Тип	Хост	Значение	Зачем
A	`mailing`	`SERVER_IPV4`	Админка, API и SMTP hostname.
MX	`hindibindi.ru`	`mailing.hindibindi.ru`	Входящие ответы на домен. Приоритет `10`.
TXT SPF	`hindibindi.ru`	`v=spf1 mx ip4:SERVER_IPV4 ~all`	Разрешает этому IP отправлять письма от домена.
TXT DKIM	`default._domainkey`	`v=DKIM1; h=sha256; k=rsa; p=PUBLIC_KEY`	Публичный ключ из OpenDKIM/SMTP-провайдера. Не обрезать значение.
TXT DMARC	`_dmarc`	`v=DMARC1; p=quarantine; rua=mailto:admin@hindibindi.ru; adkim=s; aspf=s`	Политика домена и отчеты. На прогреве можно начать с `p=none`.

PTR/rDNS у провайдера VPS

Откройте панель сервера, раздел IPv4 / Reverse DNS / PTR.
Для IP сервера задайте mailing.hindibindi.ru.
Проверьте, что mailing.hindibindi.ru A-записью указывает обратно на этот же IP.
Дождитесь применения. Обычно 5-30 минут, иногда дольше.

Проверка DNS

dig +short A mailing.hindibindi.ru
dig +short MX hindibindi.ru
dig +short TXT hindibindi.ru
dig +short TXT default._domainkey.hindibindi.ru
dig +short TXT _dmarc.hindibindi.ru
dig +short -x SERVER_IPV4

Проект в админке

Sender domain: hindibindi.ru
Sender name: HindiBindi Mailing
SMTP host: mailing.hindibindi.ru
SMTP port: 587
TLS/SSL: включить для 587, если сервер поддерживает STARTTLS; для 465 нужен implicit TLS.
SMTP login: noreply@hindibindi.ru.

Режим отправки

Сначала отправьте 1 письмо на Gmail, Outlook и свой ящик, проверьте заголовки SPF/DKIM/DMARC.
Новый домен: 10-20 писем в день первые 2-3 дня, потом рост до 30-50, затем +20-30% в день.
Не отправляйте одинаковый HTML сотням адресов. Меняйте тему, первый абзац и персонализацию.
В письме должен быть text-body или нормальный текстовый fallback, понятный From и рабочий reply-to.
Для холодной базы сначала используйте симуляцию кампании и маленький список, потом реальную отправку.

Диагностика после отправки

pm2 status
pm2 logs rust-custom-smtp --lines 100
curl -I https://mailing.hindibindi.ru
./target/release/rust-custom-smtp dns-check --domain hindibindi.ru --ip SERVER_IPV4

Для внешней оценки отправьте тест на mail-tester.com. Нормальная цель перед рассылкой: SPF pass, DKIM pass, DMARC pass, PTR совпадает с SMTP host, нет blacklist-срабатываний.

Ответы на вопросы

Ча.Во. / FAQ

Справочник по работе с почтовым сервером, настройке доменов, приему входящих писем и диагностике неполадок.

1. Как добавить свой домен для отправки писем и создания ящиков?

Домены в системе появляются автоматически на основе настроенных вами проектов:

Перейдите во вкладку «Проекты (SMTP)» в левом меню.
Нажмите кнопку добавления проекта или отредактируйте существующий.
В поле «Sender domain» введите имя вашего домена (например, hindibindi.ru).
После сохранения проекта этот домен автоматически появится в выпадающем списке при создании ящиков во вкладке «Входящие и Временные».

2. Как работает прием писем и почему я не вижу входящих сообщений?

Для успешного приема почты необходимо настроить две вещи:

А. MX-запись в DNS вашего домена

В панели регистратора вашего домена добавьте MX-запись, указывающую на хост вашей админки. Например:

Хост: @ (или hindibindi.ru)
Тип: MX
Значение: mailing.hindibindi.ru.
Приоритет: 10

Б. Перенаправление порта 25 на сервере

Встроенный почтовый сервер принимает входящие письма по умолчанию на порту 2525 (чтобы запускаться без root-прав под PM2).

Поскольку другие почтовые службы (Gmail, Yandex и др.) отправляют почту строго на стандартный порт 25, настройте перенаправление трафика на вашем сервере с помощью команды:

sudo iptables -t nat -A PREROUTING -p tcp --dport 25 -j REDIRECT --to-ports 2525

Для сохранения правила после перезагрузки установите пакет сохранения правил: sudo apt install iptables-persistent.

3. Почему отправителям возвращается ошибка E550 (Recipient address not local or inactive)?

Это сделано в целях безопасности и защиты от спама.

Наш почтовый сервер принимает письма только на те адреса, которые вы явно добавили в админ-панели в разделе «Активные адреса». Если ящик для входящих не был создан, почтовый сервер выдаст ошибку 550 Recipient address not local or inactive отправителю.

Перед тестом приема почты обязательно добавьте нужный префикс (например, noreply или support) на нужном домене в панели «Создать почтовый ящик».

4. Какие сетевые порты должны быть открыты для работы?

Для правильного функционирования всех модулей на сервере должны быть открыты следующие порты:

80/tcp и 443/tcp — для веб-интерфейса админки, API и автоматического выпуска SSL-сертификатов Certbot (Let's Encrypt).
25/tcp — стандартный порт для входящей почты от внешних серверов (перенаправляется правилом iptables на порт 2525).
587/tcp — порт отправки писем через проекты с использованием STARTTLS.
465/tcp — порт отправки писем, используйте его только если ваш SMTP-сервер поддерживает implicit TLS.

5. Что делать, если письма уходят в спам?

Качество доставки зависит от правильного совпадения доменных и сетевых параметров:

Убедитесь, что для IP-адреса вашего сервера прописана правильная PTR-запись (rDNS) в панели вашего VPS-провайдера (например, она должна возвращать mailing.hindibindi.ru).
Проверьте, что в DNS добавлены корректные записи SPF, DKIM и DMARC.
Для комплексной проверки отправьте тестовое письмо из админки на сервис mail-tester.com и изучите детальный отчет.
Используйте встроенную утилиту диагностики: во вкладке «Инструкции» указана команда:
```
./target/release/rust-custom-smtp dns-check --domain hindibindi.ru --ip SERVER_IPV4
```

Отправлено писем

Доставлено (SUCCESS)

Ошибки (FAILED)

График прогрева по дням

Распределение по доменам

Ключи авторизации API

Генерируйте ключи для транзакционной отправки писем через REST API

Ключ API нужен внешнему сайту или CRM для отправки писем через /api/send. Один ключ привязан к одному SMTP-проекту, поэтому разные домены лучше держать разными проектами и ключами.

Название ключа	Проект	Токен (Bearer)	Дата создания

Запуск рассылок и прогрева

Запускайте и анализируйте процесс доставки писем по базам

ID	Кампания	Статус	Размер базы	Успешно	Ошибки	Дата старта

Обнаруженные файлы (Auto-Watcher)

Сервер автоматически сканирует папку imports/ каждые 5 секунд. Закидывайте файлы через FTP/FileZilla!

Папка imports/ сканируется watcher-ом. Один и тот же файл можно импортировать повторно: будет создана новая база или новый шаблон с выбранным именем.

Имя файла	Тип	Обнаружен	Статус	Действия

Входящие письма и Временная почта

Принимайте входящую почту на свои домены, заводите ящики техподдержки или генерируйте временные disposable-адреса для тестов.

Создать почтовый ящик

Активные адреса

Email	Тип

Входящие сообщения

Отправитель	Тема	Получено