BullMQ + Mailexam

Минимальный пример BullMQ на Express, который отправляет тестовое письмо через SMTP Mailexam с помощью Nodemailer в фоновом worker.

Основан на руководстве Mailexam для BullMQ.

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

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

Из приветственного письма или личного кабинета Mailexam:

Быстрый старт (на хосте)

1. Установите зависимости:

npm install

2. Скопируйте пример файла окружения и заполните учётные данные:

cp .env.example .env

3. Отредактируйте .env:

REDIS_URL=redis://localhost:6379/0
MAILEXAM_LOGIN=ВАШ_ЛОГИН
MAILEXAM_PASSWORD=ВАШ_ПАРОЛЬ
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

4. Запустите Redis (если ещё не запущен локально):

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

5. Запустите worker и HTTP-сервер (два терминала):

npm run worker

npm start

Сервер слушает http://127.0.0.1:3000 по умолчанию.

6. Поставьте тестовое письмо в очередь:

curl -X POST http://127.0.0.1:3000/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Тест","text":"Привет"}'

Ответ: {"status":"ok","queued":true,"jobId":"..."}. После выполнения worker письмо появится в личном кабинете Mailexam → ваш проект → входящие.

Постановка в очередь без HTTP

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

mailQueue.add('send-test', {
  to: 'user@example.test',
  subject: 'BullMQ + Mailexam',
  text: 'Mailexam test from BullMQ',
});

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

Для порта 587 transport использует STARTTLS (secure: false). Для порта 465 — SMTPS (secure: true).

Структура проекта

.
├── package.json
├── mail.js              # Nodemailer transport и sendTest()
├── queue.js             # очередь BullMQ и подключение Redis
├── worker.js            # worker BullMQ (отправка почты)
├── server.js            # POST /mail/test (постановка в очередь)
├── .env.example
├── Dockerfile           # только для локальной отладки
└── docker-compose.yml   # redis + worker + app

Docker (отладка)

Docker предназначен для локальной отладки. Для повседневной разработки запускайте Redis, worker и приложение на хосте (см. выше).

cp .env.example .env
# отредактируйте .env с учётными данными Mailexam

docker compose up --build

Затем вызовите тот же endpoint на проброшенном порту:

curl -X POST http://127.0.0.1:3000/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Тест","text":"Привет"}'

Compose запускает Redis, worker BullMQ и HTTP-приложение на порту 3000.

CI

Задайте эти секреты в окружении CI:

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

После отправки письма в тесте проверьте доставку через API Mailexam.

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

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

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

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

• Хост должен быть {логин}.mailexam.ru, где {логин} совпадает с MAILEXAM_LOGIN.
• Логин и пароль должны быть из одного проекта Mailexam.

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

• Откройте входящие того же проекта Mailexam.
• Подождите, пока worker обработает задачу.

См. также

• Руководство Mailexam для BullMQ (wiki)
• Пример на Express — синхронный Nodemailer на том же SMTP-стеке
• Пример на Celery — фоновая почта в Python
• Пример на Sidekiq — фоновая почта в Ruby
• Документация BullMQ
• Документация API Mailexam

Лицензия

Apache 2.0