Перейти к содержанию

BullMQ

Инструкция для фоновой отправки почты через BullMQ на Node.js 18+ (в примере — Express). Письма уходят на SMTP Mailexam® из worker через Nodemailer — удобно для уведомлений и CI без блокировки HTTP-запроса.

Web-слой ставит задачу в очередь; BullMQ отправляет письмо асинхронно (аналог Celery в Python или Sidekiq в Ruby).

Что понадобится

  • Аккаунт Mailexam® и проект с SMTP-учётными данными.
  • Брокер сообщений — Redis (обязателен для BullMQ).
  • Node.js 18+ и npm.

Скопируйте из приветственного письма (или личного кабинета) для вашего проекта:

  • ВАШ_ЛОГИН — SMTP-логин (например, xxxxx);
  • ВАШ_ПАРОЛЬ — SMTP-пароль (уникальная пара к логину);
  • хост — ВАШ_ЛОГИН.mailexam.ru (совпадает с логином).

1. Зависимости

npm init -y
npm install bullmq ioredis express nodemailer dotenv

Минимальные зависимости в package.json:

{
  "dependencies": {
    "bullmq": "^5.34.0",
    "dotenv": "^16.0.0",
    "express": "^4.21.0",
    "ioredis": "^5.4.0",
    "nodemailer": "^6.9.0"
  },
  "scripts": {
    "start": "node server.js",
    "worker": "node worker.js"
  }
}

Запуск Redis локально (Docker):

docker run -d --name redis -p 6379:6379 redis:7-alpine

2. Переменные окружения

Файл .env в корне проекта:

REDIS_URL=redis://localhost:6379/0

MAILEXAM_LOGIN=ВАШ_ЛОГИН
MAILEXAM_PASSWORD=ВАШ_ПАРОЛЬ
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

SMTP-хост: ВАШ_ЛОГИН.mailexam.ru.

3. Nodemailer transport

Как в Express — файл mail.js в корне проекта:

// mail.js
const nodemailer = require('nodemailer');

function createTransport() {
  const login = process.env.MAILEXAM_LOGIN;
  const port = Number(process.env.MAILEXAM_PORT || 587);

  return nodemailer.createTransport({
    host: `${login}.mailexam.ru`,
    port,
    secure: port === 465,
    auth: {
      user: login,
      pass: process.env.MAILEXAM_PASSWORD,
    },
  });
}

async function sendTest({ to, subject, text }) {
  const transport = createTransport();

  await transport.sendMail({
    from: process.env.MAIL_FROM || 'noreply@example.test',
    to: to || 'user@example.test',
    subject: subject || 'BullMQ + Mailexam',
    text: text || 'Mailexam test from BullMQ',
  });
}

module.exports = { sendTest };

4. Очередь BullMQ и worker

queue.js:

require('dotenv').config();

const { Queue } = require('bullmq');
const IORedis = require('ioredis');

const connection = new IORedis(process.env.REDIS_URL || 'redis://localhost:6379/0', {
  maxRetriesPerRequest: null,
});

const mailQueue = new Queue('mail', { connection });

module.exports = { mailQueue, connection };

worker.js:

require('dotenv').config();

const { Worker } = require('bullmq');
const IORedis = require('ioredis');
const { sendTest } = require('./mail');

const connection = new IORedis(process.env.REDIS_URL || 'redis://localhost:6379/0', {
  maxRetriesPerRequest: null,
});

new Worker(
  'mail',
  async (job) => {
    const { to, subject, text } = job.data;
    await sendTest({ to, subject, text });
    return { status: 'ok', to: to || 'user@example.test' };
  },
  { connection },
);

5. HTTP endpoint

// server.js
require('dotenv').config();

const express = require('express');
const { mailQueue } = require('./queue');

const app = express();
app.use(express.json());

app.post('/mail/test', async (req, res, next) => {
  try {
    const { to, subject, text, body } = req.body ?? {};

    const job = await mailQueue.add('send-test', {
      to,
      subject,
      text: text ?? body,
    });

    res.json({ status: 'ok', queued: true, jobId: job.id });
  } catch (err) {
    next(err);
  }
});

const host = process.env.HTTP_HOST || '127.0.0.1';
const port = Number(process.env.HTTP_PORT || 3000);

app.listen(port, host);

Запустите Redis, worker и сервер:

npm run worker
npm start

curl -X POST http://127.0.0.1:3000/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Test","text":"Hello"}'

После обработки задачи worker письмо появится в личном кабинете Mailexam® → ваш проект → входящие.

6. Локальная разработка и CI

Окружение Рекомендация
local Redis + процесс worker + HTTP-сервер
CI Сервис Redis, REDIS_URL и секреты Mailexam в переменных pipeline

Пример для .gitlab-ci.yml:

variables:
  REDIS_URL: redis://redis:6379/0
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

После интеграционного теста проверьте доставку через REST API Mailexam®.

7. Типичные проблемы

Задача в очереди, но письмо не отправлено

  • Убедитесь, что worker запущен (npm run worker).
  • Проверьте REDIS_URL и доступность Redis.
  • Изучите логи worker на предмет ошибок SMTP.

Таймаут соединения / ошибка аутентификации

  • Хост должен быть {логин}.mailexam.ru, user — тот же логин из письма.

Письмо не в кабинете

  • Откройте входящие того же проекта Mailexam®.
  • Дождитесь обработки задачи worker.

См. также