Транзакционные письма через API

Что такое транзакционные письма

Транзакционное письмо отправляется в ответ на действие конкретного человека: он зарегистрировался, забыл пароль, оплатил заказ. Его ждут, его открывают, по нему переходят. Поэтому к такой почте иные требования, чем к рассылкам: она должна дойти быстро, не попасть в спам и быть понятной по теме и отправителю.

Встроенная в хостинг функция mail() с этим справляется плохо: у письма нет подписи вашего домена, IP-адрес общего сервера может оказаться в чёрных списках, а о том, что письмо не дошло, вы не узнаете. Сервис транзакционной почты решает все три проблемы: подписывает письма, доставляет их с репутационного сервера и возвращает вам события.

Отправка одним запросом

Весь интерфейс сводится к одному вызову: POST /v1/messages с ключом в заголовке Authorization. В теле запроса — отправитель, получатель, тема и текст. В ответ приходит 201 Created с идентификатором письма и статусом queued: письмо принято в очередь.

const res = await fetch('https://slendermail.ru/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.SLENDERMAIL_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'noreply@вашдомен.ru',
    to: user.email,
    subject: 'Подтвердите адрес',
    text: 'Перейдите по ссылке, чтобы завершить регистрацию: ' + link,
  }),
});

if (res.status !== 201) throw new Error('Письмо не принято: ' + res.status);

Ключ создаётся в личном кабинете, в разделе для разработчиков. Храните его в переменной окружения, а не в репозитории. Если вам удобнее обычный SMTP, например для готовой CMS, подключитесь через SMTP-сервер для сайта: письма пойдут по тому же конвейеру.

Отправитель и подпись

Отправлять письма можно только с домена, который вы подтвердили. Это не настройка, а правило, встроенное в архитектуру: запрос с любым другим адресом в From отклоняется на входе. Так никто не сможет воспользоваться вашим аккаунтом, чтобы писать от чужого имени, а ваш домен не окажется в списке источников спама из-за чужой ошибки.

Каждое письмо подписывается DKIM-ключом вашего домена длиной 2048 бит. Приватные ключи хранятся на диске в зашифрованном виде (AES-256-GCM). Чтобы подпись и SPF проходили проверку, домену нужны три DNS-записи — какие именно и как их проверить, описано в руководстве по настройке DKIM, SPF и DMARC. Кабинет сам формирует значения и проверяет их в реальном времени.

События и вебхуки

Отправить письмо — это половина дела. Вторая половина — узнать, что с ним случилось дальше.

События отправляются на ваш адрес с подписью HMAC-SHA256: проверьте её на своей стороне, и вы будете уверены, что запрос пришёл от SlenderMail. Если ваш сервер временно недоступен, доставка события повторяется. Встроенная защита от SSRF не позволит использовать вебхук для обращений во внутреннюю сеть.

Отчёты об отказах (DSN) и жалобах (ARF) разбираются автоматически и классифицируются по RFC 3463, поэтому вы получаете не сырой текст из почтового сервера, а понятное событие.

Стоп-лист

Повторная отправка на несуществующие адреса вредит репутации домена. Чтобы этого не происходило, сервис ведёт стоп-лист и пополняет его без вашего участия:

• жёсткий отказ блокирует адрес в пределах вашего аккаунта;
• жалоба на спам блокирует адрес глобально, для всех отправителей сервиса.

Адреса из стоп-листа отсеиваются ещё до отправки, так что вы не тратите квоту и не портите статистику.

Квоты и репутация

Новый домен без истории отправки получатели встречают настороженно. Поэтому на новых аккаунтах действуют часовые и дневные квоты, которые растут постепенно — это называется прогревом. Резкий скачок объёма на свежем домене даёт ровно тот результат, которого вы хотите избежать, то есть спам.

Лимиты по числу писем в месяц зависят от тарифа, они описаны на странице тарифов.

Типичные сценарии

Подтверждение регистрации

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

Сброс пароля

Самое критичное письмо: если оно попало в спам, пользователь решит, что сервис не работает. Подпись домена и стоп-лист снижают этот риск.

Уведомления

Комментарии, статусы заказов, напоминания. Здесь важны квоты и автопауза: сбой в вашем коде не превратится в тысячи лишних писем.

Чеки и документы

Сведения об оплате должны быть доставлены надёжно. События bounced и complained подскажут, что адрес пользователя устарел или недействителен.

Частые вопросы