
У серверов Hangar общий IP, а 25-й порт на нём может занимать только одна программа. Поэтому почтой занимается шлюз платформы. Он принимает письма для подтверждённых доменов и передаёт их вашему почтовому серверу. Исходящие письма сервисов он подписывает DKIM, считает по лимиту тарифа и доставляет с повторами. Для почтовых программ шлюз отвечает по TLS на портах 993 и 465.
Как подключить#
- Подключите домен
Кабинет → Почта → Подключить домен. Выберите режим: почтовый сервер с ящиками, только отправка из приложения или свой сервер.
- Добавьте DNS-записи
Hangar покажет 4–6 записей: подтверждение, DKIM, SPF, DMARC, MX и адрес для почтовых программ.
- Дождитесь проверки
Hangar сам проверяет записи каждые 10 минут; кнопка «Проверить DNS сейчас» запускает проверку сразу.
- Пользуйтесь
Создайте ящики, подключите почтовую программу или отправляйте письма из приложения через relay.
Режимы#
- Почтовый сервер с ящиками — Hangar разворачивает Postfix и Dovecot (docker-mailserver) с диском и ежедневным бэкапом. Первый ящик postmaster@домен создаётся сразу, его пароль показывается один раз и лежит в переменной MAIL_ADMIN_PASSWORD.
- Только отправка из приложения — письма с сайта или бота (регистрация, заказы, рассылки). Входящие письма не принимаются, MX-запись не нужна.
- Свой почтовый сервер — у вас уже есть сервис с SMTP (25), IMAP (143) и submission (587). Hangar передаёт ему входящую почту, а клиентам выдаёт TLS на 993 и 465.
DNS-записи#
Точные значения показаны в карточке домена, у каждой записи есть кнопка копирования. Пример для shop.ru:
TXT _hangar-mail.shop.ru hangar-mail-… # домен ваш (обязательно)
TXT hangar._domainkey.shop.ru v=DKIM1; k=rsa; p=… # подпись писем (обязательно для отправки)
TXT shop.ru v=spf1 ip4:<IP Hangar> ~all
TXT _dmarc.shop.ru v=DMARC1; p=quarantine; adkim=r; aspf=r
MX shop.ru 10 mx.apps.hangar.rest # входящая почта
A mail.shop.ru <IP Hangar> # почтовые программы и TLS-сертификатЕсли SPF-запись у домена уже есть, не создавайте вторую — добавьте ip4:<IP Hangar> в существующую. Без DKIM-записи отправка выключена: письма без подписи почти всегда попадают в спам.
Ящики#
Для почтового сервера Hangar ящики создаются во вкладке «Ящики» карточки домена: имя до @ и пароль (от 8 символов). Там же меняются пароли и удаляются ящики вместе с почтой. Через API: POST /v1/mail-domains/<id>/mailboxes.
Почтовые программы#
- Входящая почта — IMAP, сервер mail.домен, порт 993, SSL/TLS
- Исходящая почта — SMTP, сервер mail.домен, порт 465, SSL/TLS
- Логин — полный адрес ящика, пароль — пароль ящика
- Сертификат для mail.домен Hangar выпускает сам, как только появляется A-запись
Отправка из приложений#
Наружу 25-й порт для сервисов закрыт, письма уходят через relay внутри Hangar. Его адрес, логин и пароль уже лежат в переменных выбранного сервиса:
HANGAR_SMTP_HOST=mail-relay.hangar-mail.svc.cluster.local
HANGAR_SMTP_PORT=587 # STARTTLS, логин и пароль обязательны
HANGAR_SMTP_USER=shop.ru
HANGAR_SMTP_PASSWORD=…import nodemailer from 'nodemailer'
const mail = nodemailer.createTransport({
host: process.env.HANGAR_SMTP_HOST,
port: Number(process.env.HANGAR_SMTP_PORT),
auth: { user: process.env.HANGAR_SMTP_USER, pass: process.env.HANGAR_SMTP_PASSWORD },
tls: { rejectUnauthorized: false }, // внутренний адрес кластера
})
await mail.sendMail({ from: 'Магазин <orders@shop.ru>', to: 'client@gmail.com', subject: 'Заказ принят', text: 'Спасибо!' })Отправитель в конверте и в заголовке From — только адреса вашего домена (или его поддоменов). Date и Message-ID Hangar добавит сам, если их нет. Историю отправки за неделю показывает вкладка «Отправленные»: статус, число попыток, ответ сервера получателя.
Для почтовых сервисов#
Если вы делаете свой почтовый сервис на Hangar (клиенты подключают свои домены из вашего кабинета), регистрируйте их из бекенда токеном проекта (hgr_t_…). Токен может подключить, проверить и удалить домен в своём окружении. Без TXT-записи _hangar-mail, которую добавляет владелец домена, подключённый домен ничего не принимает и не отправляет.
curl -X POST -H "Authorization: Bearer $HANGAR_TOKEN" -H 'Content-Type: application/json' \
-d '{"domain": "org.ru", "service_id": "<backend>", "proxy_protocol": true}' \
https://api.hangar.rest/v1/projects/<project>/mail-domains
# ответ: id домена и records — записи, которые клиент добавит у регистратора
curl -X POST -H "Authorization: Bearer $HANGAR_TOKEN" https://api.hangar.rest/v1/mail-domains/<id>/check
curl -X DELETE -H "Authorization: Bearer $HANGAR_TOKEN" https://api.hangar.rest/v1/mail-domains/<id>Один логин на сервис#
У сервиса один relay-логин на все почтовые домены, которые к нему подключены. Он лежит в переменных HANGAR_SMTP_USER и HANGAR_SMTP_PASSWORD, а показать его или выпустить новый пароль можно через GET или POST /v1/services/<service>/instances/<environment>/mail-relay. Письмо подписывается DKIM того домена, что стоит в заголовке From. Отправка работает для подтверждённых доменов с DKIM-записью.
События#
- mail.domain.verified — домен подтверждён (TXT _hangar-mail найден)
- mail.domain.check_failed — ручная проверка не нашла обязательные записи, или у подтверждённого домена пропала запись; в data.missing — какие (verify, dkim, mx)
- mail.domain.blocked — отправка остановлена (много недоставленных писем), причина в data.reason
Подпишитесь на них в настройках проекта → Вебхуки. В data есть mail_domain_id и domain. Поле verified_at есть и в списке доменов: GET /v1/projects/<project>/mail-domains.
IP отправителя#
К входящим письмам шлюз добавляет заголовки X-Hangar-Client-IP (IP подключившегося сервера) и X-Hangar-Client-Helo. Их ставит только шлюз: такие же заголовки, пришедшие от отправителя, вырезаются. Формат стабильный, по нему можно делать свои SPF- и DMARC-проверки. Другой вариант — proxy_protocol: true у домена. Тогда каждое соединение к вашему серверу начинается строкой PROXY v1 с IP отправителя (Postfix: smtpd_upstream_proxy_protocol = haproxy).
Статусы отправки#
- queued — ещё не отправлялось
- deferred — сервер получателя попросил повторить позже, Hangar повторит (next_attempt_at)
- sent — доставлено всем получателям
- partial — часть получателей приняла, остальные отказали
- bounced — не доставлено никому
В results по каждому получателю: status (delivered, deferred или bounced), response — ответ его сервера, например «250 2.0.0 OK … gsmtp», host и время.
Лимиты и защита#
- Дневной лимит писем — по тарифу. При превышении relay отвечает временной ошибкой 451, и приложение может повторить отправку на следующий день.
- Недоставленные письма Hangar повторяет до 48 часов (через 1, 5, 15, 30 минут, потом раз в 1–4 часа), после этого отправитель получает уведомление о недоставке.
- Если за день возвращается больше трети писем (адреса не существуют), отправка для workspace останавливается: это похоже на рассылку по чужой базе. Приём почты продолжает работать, снять блокировку может поддержка.
- Входящие письма с IP из списков спама (Spamhaus) и письма, которые не проходят SPF, шлюз отклоняет.
API#
/v1/workspaces/<workspace>/mailВсе почтовые домены workspacePOST/v1/projects/<project>/mail-serverПочтовый сервер в один клик: {domain}POST/v1/projects/<project>/mail-domainsПодключить домен: {domain, service_id, inbound}POST/v1/mail-domains/<id>/checkПроверить DNS-записи сейчасPOST/v1/mail-domains/<id>/mailboxesСоздать ящик: {name, password}GET/v1/mail-domains/<id>/relay-passwordПароль relay (POST — выпустить новый)GET/v1/mail-domains/<id>/queueПоследние отправленные письма
