SendinBlue + Node.js: отправка писем шаг за шагом

SendinBlue упрощает отправку писем из Node.js: зарегистрируйтесь, сгенерируйте API-ключ, установите SDK sib-api-v3-sdk и вызовите метод sendTransacEmail. В статье шаг за шагом показано, как добавить рассылку приветственного письма для эндпоинта /waitlist, а также даны рекомендации по масштабированию, безопасности и тестированию.

Важно: храните ваш API-ключ в защищённом месте (переменная окружения) и не публикуйте его в репозитории.

Открытый ноутбук с логотипом Node.js на экране и иконкой, символизирующей электронную почту

В современном мире цифрового маркетинга электронная почта остаётся ключевым каналом связи для бизнеса. Настройка почтовой системы может показаться сложной, особенно если вы только начинаете. SendinBlue — это SaaS-платформа, которая упрощает отправку email и SMS: она предоставляет API и SDK, которые легко интегрировать с Node.js.

Что такое SendinBlue?

SendinBlue — это платформа (SaaS) для email-маркетинга и рассылок, подходящая для малого, среднего и крупного бизнеса. Она помогает выстраивать отношения с клиентами через email и SMS, а также предоставляет наборы API и SDK для автоматизации отправки сообщений.

Кратко: SendinBlue — это сервис для отправки транзакционных и маркетинговых писем, шаблонов, вебхуков и аналитики.

Как получить API-учётные данные SendinBlue

Для работы с API SendinBlue потребуется аккаунт. Процесс регистрации простой: создайте аккаунт на странице регистрации SendinBlue, заполните данные и завершите онбординг. После входа в панель управления получите API-ключ:

Откройте дашборд SendinBlue и кликните по названию организации в правом верхнем углу.
Выберите пункт SMTP & API в выпадающем меню.

Пункт SMTP & API в выпадающем меню панели управления SendinBlue

Перейдите на вкладку API Keys и нажмите кнопку «Generate a new API key».

Кнопка генерации API-ключа в SendinBlue

В появившемся окне задайте имя ключу, скопируйте сгенерированную строку и сохраните её в безопасном месте.

API-ключ — это ваша учётная запись для аутентификации запросов. Никогда не публикуйте его в открытых репозиториях.

Как построить систему отправки писем в Node.js

Node.js не имеет встроенного почтового пакета наподобие некоторых других языков, поэтому обычно используют внешние библиотеки: nodemailer, сторонние SDK или официальный SDK SendinBlue.

Для примера рассмотрим простое приложение на Node/Express с эндпоинтом /waitlist, куда добавляются пользователи, и им отправляется приветственное письмо.

Исходный пример сервера (без разделения на модули):

        `// server.js  
const express = require('express');  
  
// create server  
const server = express();  
const port = 3333;  
  
server.listen(port, () => {  
    console.log(`server listening on port ${port}`);  
})  
  
// create waitlist endpoint  
server.use('/waitlist', async (req, res) => {  
    try {  
        const user = req.body;  
  
        console.log(`${user.fullname} joined the waitlist`);  
        res.status(200).json({ message: 'Joined Waitlist successfully' })  
    } catch (error) {  
        console.error(error)  
        res.status(500).json({ message: 'An error occurred' })  
    }  
})  
`

Прежде чем отправлять почту, установите SDK SendinBlue:

npm: npm install sib-api-v3-sdk
yarn: yarn add sib-api-v3-sdk

На больших проектах выделите логику отправки писем в отдельный модуль. В демонстрации мы добавим код прямо в server.js.

Импортируйте пакет и настройте клиента SendinBlue:

        `const SibApi = require('sib-api-v3-sdk');  
  
// instantiate new SendinBlue API client  
const SibClient = SibApi.ApiClient.instance;  
  
// Authentication  
SibClient.authentications['api-key'].apiKey = process.env.SIB_API_KEY  
 || 'YOUR_API_KEY_HERE';  
`

Далее создайте конфигурацию и функцию отправки приветственного письма:

        `const transactionEmailApi = new SibApiSDK.TransactionalEmailsApi();  
  
let smtpMailData = new SibApiSDK.SendSmtpEmail();  
  
const sender = {  
  email: 'sendinbluemail@example.com',  // your email address  
  name: 'Example Sender',  
};  
  
const SendWaitlistEmail = async (userData) => {  
}  
`

Объект transactionEmailApi предоставляет метод sendTransacEmail. Переменная smtpMailData будет содержать объект письма: отправителя, получателей, тему и контент.

Тело функции SendWaitlistEmail выглядит так:

        `const SendWaitlistEmail = async (userData) => {  
    try {  
        smtpMailData.sender = sender;  
  
       smtpMailData.to = [{  
            email: userData.email,  
            name: userData.fullname  
        }];  
  
       smtpMailData.subject = 'You are on the waitlist!';  
  
       smtpMailData.params = {  
            'name': userData.fullname,  
            'twitter': '@makeuseof'  
        };  
  
       smtpMailData.htmlContent = "Hello {{ params.name }}, "  
                 + "welcome to makeuseof.com waitlist. We'll notify you "  
                  + "when we launch. Kindly follow us on Twitter "  
                 + "{{ params.twitter }}.";  
  
        // send email  
        await transactionEmailApi.sendTransacEmail(smtpMailData)  
            .then((data) => {   
                console.log(data)  // log the email id  
            })  
            .catch((error) => {  
                console.error(error)  
                throw new Error(error)  // handle errors  
            })  
    } catch (error) {  
        console.log('An error occured...')  
        console.error(error)  
        throw new Error(error)  // handle errors  
    }  
}  
`

Разберём ключевые свойства smtpMailData:

sender: объект с email и name. В продакшене используйте проверенный рабочий адрес.
to: массив получателей (до 50 получателей на сообщение безопасно). Большие рассылки лучше разбивать или использовать маркетинговые кампании.
subject: тема письма.
params: дополнительные параметры для шаблонов; вставляются как {{ params.name }}.
htmlContent / textContent: тело письма в HTML или текстовом формате.

Метод sendTransacEmail отправляет письмо и возвращает ID сообщения (messageId), который вы можете сохранить для логирования и отладки.

Подключите отправку письма в ваш /waitlist эндпоинт:

        `server.use('/waitlist', async (req, res) => {  
    try {  
        const user = req.body;  
  
        console.log(`${user.fullname} joined the waitlist`);  
  
        // call email sender function          
        await SendWaitlistEmail(user)  
        res.status(200).json({ message: 'Joined Waitlist successfully' })  
    } catch (error) {  
        console.error(error)  
        res.status(500).json({ message: 'An internal server error occurred' })  
    }  
})  
`

Тестирование: запустите приложение и отправьте POST-запрос в /waitlist из Postman или с фронтенда.

Пример запроса из Postman для эндпоинта waitlist

После отправки вы получите письмо, в котором будут подставлены значения из params.

Пример полученного тестового письма с подставленными параметрами

В консоли вы увидите поле messageId — полезно сохранить его в БД для идентификации и отладки.

Советы по предотвращению попадания писем в спам

Используйте подтверждённый отправитель и корректные SPF/DKIM/DMARC записи для вашего домена.
Поддерживайте хорошую репутацию IP и домена: не отправляйте нежелательные рассылки.
Персонализируйте и сегментируйте аудиторию.
Добавляйте текстовую версию письма (textContent) для почтовых агентов.
Отслеживайте отказы и жалобы, настройте обработку bounce/feedback.

Почему не вызывать отправку письма прямо в обработчике запроса

Если вызываете SendWaitlistEmail синхронно в теле HTTP-запроса, пользователь ждёт, пока письмо отправится. Это увеличит время ответа и может привести к таймаутам.

Рекомендуемые подходы:

Асинхронная очередь задач (Bull, RabbitMQ, AWS SQS): ставьте задачу на отправку письма в очередь и возвращайте ответ быстро.
Фоновая обработка: отдельный воркер читает очередь и отправляет письма.
Микросервисная архитектура: выделите сервис рассылок.

Простейшая последовательность для очереди:

Получили POST /waitlist.
Сохранили пользователя в БД.
Поставили задачу SendWaitlistEmail в очередь.
Вернули 200 OK пользователю.
Воркер обработал задачу и отправил письмо.

Mermaid-диаграмма принятия решения по отправке письма:

flowchart TD
  A[POST /waitlist] --> B{Параметры валидны?}
  B -- Нет --> C[Вернуть 400 Bad Request]
  B -- Да --> D[Сохранить пользователя]
  D --> E{Нужно ли ждать отправки письма?}
  E -- Да --> F[Вызвать SendWaitlistEmail синхронно]
  E -- Нет --> G[Поставить задачу в очередь и вернуть 202]
  F --> H[Вернуть 200 после отправки]
  G --> H

Безопасность и хранение ключей

Храните SIB_API_KEY в переменных окружения (process.env.SIB_API_KEY).
Ограничивайте доступ к ключам: использование секретного менеджера (HashiCorp Vault, AWS Secrets Manager) для продакшна.
Ротация ключей: периодически создавайте новые ключи и отзывайте старые.
Логи: не логируйте полный ключ API и конфиденциальные поля писем.

GDPR и приватность (коротко)

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

Альтернативные подходы и инструменты

Nodemailer: если нужен контролируемый SMTP-стек.
Amazon SES: для высокомасштабируемых отправок с гибкостью настройки.
Mailgun/SendGrid/Postmark: похожие по функционалу сервисы с собственными SDK.

Когда SendinBlue может не подходить:

Если нужна глубокая кастомизация SMTP-стека на уровне доставки.
Если у вас уже есть контракт с другим провайдером и миграция затратна.

Модель зрелости отправки писем — уровни

Уровень 1 (Начальный): Прямая отправка из обработчика запроса, нет очередей.
Уровень 2 (Базовый): Отправка через очередь задач, базовая обработка ошибок.
Уровень 3 (Продвинутый): Воркерная архитектура, мониторинг доставляемости, вебхуки для событий.
Уровень 4 (Оптимизированный): A/B тесты, персонализация, SLI/SLO по доставляемости и времени обработки.

Критерии приёмки

API-ключ хранится в переменной окружения и не попадает в репозиторий.
Письма отправляются, и для каждого отправления сохраняется messageId.
Время ответа на /waitlist не превышает установленного SLA (если используется очередь — ответ < 500 мс).
Наличие теста, который проверяет формирование smtpMailData и вызов transactionEmailApi.

Чек-лист для разработчика перед релизом

Переменные окружения заданы в CI/CD.
SPF/DKIM/DMARC настроены для домена отправителя.
Проверены ограничения SendinBlue (лимиты на отправку и получателей).
Настроены обработчики bounce и жалоб (webhooks).
Логи не содержат секретов.

Примеры тестов и критерии приёмки

Unit-тест: функция SendWaitlistEmail генерирует корректный smtpMailData при заданных userData.
Integration-тест (мок): отправка вызывает transactionEmailApi.sendTransacEmail с ожидаемым объектом.
E2E: POST /waitlist возвращает 200, а в воркере отправляется задача на email.

Шаблон письма — пример

Простой HTML-шаблон, который можно улучшать и вынести в шаблон SendinBlue:

Спасибо за то, что присоединились к нашей waitlist. Мы уведомим вас, когда запустимся.

Подписывайтесь: {{ params.twitter }}

Пример конфигурации окружения

SIB_API_KEY=* (в CI/CD или менеджере секретов)
NODE_ENV=production
MAIL_SENDER=sendinbluemail@example.com

Роли и ответственность (короткие чек-листы)

Разработчик: подготовить модуль отправки, покрыть тестами, не хранить ключи в коде.
DevOps: настроить секреты, CI/CD, мониторинг и алерты.
Маркетолог: подготовить шаблоны писем и сегменты аудитории.

Частые ошибки и способы их устранения

Ошибка 401 Unauthorized: проверьте API-ключ и его присвоение в клиенте.
Письма попадают в спам: проверьте SPF/DKIM/DMARC и содержание письма.
Таймауты при синхронной отправке: вынесите отправку в очередь.

Короткая галерея крайних случаев

Массовая рассылка > 50 000 писем: используйте маркетинговую часть SendinBlue и разбивайте отправку.
Высокая доля отклонений: временно приостановите рассылку и проведите проверку базы.

Короткий глоссарий

Транзакционные письма: автоматические сообщения (подтверждение, уведомления).
SMTP: протокол отправки почты.
SPF/DKIM/DMARC: DNS-записи для подтверждения подлинности отправителя.

Часто задаваемые вопросы

Нужно ли платить за SendinBlue, чтобы отправлять тестовые письма?

SendinBlue имеет бесплатный тариф с ограничением по количеству писем; для продакшна обычно выбирают платный план.

Можно ли использовать несколько API-ключей и ротацию?

Да. Рекомендуется ротация ключей и использование ограничений доступа.

Как отслеживать доставляемость и клики?

SendinBlue предоставляет аналитические отчёты и вебхуки для событий доставки, открытия и кликов.

Итог

SendinBlue предоставляет простой путь для отправки писем из Node.js с помощью официального SDK. Для продакшна важно хранить ключи безопасно, настроить SPF/DKIM/DMARC, использовать очереди для масштабирования и настраивать обработку bounce/complaints. Эта статья показала базовый пример и дала рекомендации по лучшим практикам.

Сводка ключевых шагов:

Зарегистрируйтесь и получите API-ключ.
Установите sib-api-v3-sdk.
Настройте клиента и реализуйте SendWaitlistEmail.
Выносите отправку в очередь, настройте безопасность и мониторинг.

Спасибо за внимание. Если нужно, могу подготовить готовый модуль отправки писем на TypeScript или пример настройки очереди с Bull.

Отправка писем в Node.js через SendinBlue