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

Midway.js

Инструкция для приложений на Midway.js 3 и Koa (Node.js 18+). Mailexam® подключается как SMTP через Nodemailer в сервисе с @Provide().

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

  • Аккаунт Mailexam® и проект с SMTP-учётными данными.
  • Проект Midway 3 (CLI: npm init midway@latest -- --type=koa-v3).

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

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

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

npm install nodemailer dotenv
npm install -D @types/nodemailer

Стартер Midway Koa уже включает @midwayjs/koa, @midwayjs/core и @midwayjs/bootstrap.

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

Файл .env в корне проекта (не коммитьте пароли):

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

Подключите .env до bootstrap (например, в bootstrap.js):

require('dotenv').config();

const { Bootstrap } = require('@midwayjs/bootstrap');
Bootstrap.run();

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

Адрес отправителя

MAIL_FROM может быть любым тестовым адресом — письмо попадёт в Mailexam®, а не реальному получателю.

Альтернативные порты

MAILEXAM_PORT=587

В transport: secure: false (STARTTLS на 587).

MAILEXAM_PORT=2525

MAILEXAM_PORT=465

В transport задайте secure: true.

3. Сервис отправки

src/service/mail.service.ts:

import { Provide } from '@midwayjs/core';
import * as nodemailer from 'nodemailer';
import type { Transporter } from 'nodemailer';

@Provide()
export class MailService {
  private createTransport(): Transporter {
    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 sendTest(to: string, subject: string, text: string): Promise<void> {
    const from = process.env.MAIL_FROM || 'noreply@example.test';

    await this.createTransport().sendMail({ from, to, subject, text });
  }
}

4. Тестовый маршрут

src/controller/mail.controller.ts:

import { Body, Controller, Inject, Post } from '@midwayjs/core';
import { MailService } from '../service/mail.service';

interface SendMailBody {
  to?: string;
  subject?: string;
  text?: string;
  body?: string;
}

@Controller('/mail')
export class MailController {
  @Inject()
  mailService: MailService;

  @Post('/test')
  async test(@Body() body: SendMailBody) {
    await this.mailService.sendTest(
      body.to ?? 'user@example.test',
      body.subject ?? 'Midway + Mailexam',
      body.text ?? body.body ?? 'Тест Mailexam из Midway.js'
    );

    return { status: 'ok' };
  }
}

Порт HTTP по умолчанию в Midway Koa — 7001 (koa.port в src/config/config.default.ts).

Запуск и проверка:

npm run build
npm start

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

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

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

Среда Рекомендация
local .env + dotenv в bootstrap.js
CI Секреты MAILEXAM_LOGIN, MAILEXAM_PASSWORD в GitLab CI/CD Variables

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

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

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

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

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

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

Порт 587 и TLS

  • Для 587: secure: false (STARTTLS). Для 465 — secure: true.

Переменные undefined

  • Загрузите .env в bootstrap.js до Bootstrap.run() или экспортируйте переменные в CI.

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

  • Смотрите входящие того же проекта Mailexam®.
  • Проверьте логи Midway при sendMail.

См. также