На этой странице
Видео: почта на своём домене0:48
Раздел «Почта»
Раздел «Почта»: «Подключить домен» — ящики на домене или только отправка писем из приложений.

У серверов Hangar общий IP, а 25-й порт на нём может занимать только одна программа. Поэтому почтой занимается шлюз платформы. Он принимает письма для подтверждённых доменов и передаёт их вашему почтовому серверу. Исходящие письма сервисов он подписывает DKIM, считает по лимиту тарифа и доставляет с повторами. Для почтовых программ шлюз отвечает по TLS на портах 993 и 465.

Как подключить#

  1. Подключите домен

    Кабинет → Почта → Подключить домен. Выберите режим: почтовый сервер с ящиками, только отправка из приложения или свой сервер.

  2. Добавьте DNS-записи

    Hangar покажет 4–6 записей: подтверждение, DKIM, SPF, DMARC, MX и адрес для почтовых программ.

  3. Дождитесь проверки

    Hangar сам проверяет записи каждые 10 минут; кнопка «Проверить DNS сейчас» запускает проверку сразу.

  4. Пользуйтесь

    Создайте ящики, подключите почтовую программу или отправляйте письма из приложения через relay.

Режимы#

  • Почтовый сервер с ящиками — Hangar разворачивает Postfix и Dovecot (docker-mailserver) с диском и ежедневным бэкапом. Первый ящик postmaster@домен создаётся сразу, его пароль показывается один раз и лежит в переменной MAIL_ADMIN_PASSWORD.
  • Только отправка из приложения — письма с сайта или бота (регистрация, заказы, рассылки). Входящие письма не принимаются, MX-запись не нужна.
  • Свой почтовый сервер — у вас уже есть сервис с SMTP (25), IMAP (143) и submission (587). Hangar передаёт ему входящую почту, а клиентам выдаёт TLS на 993 и 465.

DNS-записи#

Точные значения показаны в карточке домена, у каждой записи есть кнопка копирования. Пример для shop.ru:

dns
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. Его адрес, логин и пароль уже лежат в переменных выбранного сервиса:

env
HANGAR_SMTP_HOST=mail-relay.hangar-mail.svc.cluster.local
HANGAR_SMTP_PORT=587        # STARTTLS, логин и пароль обязательны
HANGAR_SMTP_USER=shop.ru
HANGAR_SMTP_PASSWORD=…
node.js
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#

Свои домены для сайтов и приложений.

Сеть и домены