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

Next.js

Инструкция для приложений на Next.js (Node.js 18+, App Router). Mailexam® подключается как SMTP через Nodemailer и Route Handler POST /api/mail/test.

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

  • Аккаунт Mailexam® и проект с SMTP-учетными данными.
  • Node.js 18+ и npm.

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

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

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

npx create-next-app@latest my-app
cd my-app
npm install nodemailer dotenv

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

{
  "dependencies": {
    "dotenv": "^16.0.0",
    "next": "^15.0.0",
    "nodemailer": "^6.9.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

Включите standalone output в next.config.js, если деплой через Docker:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
};

module.exports = nextConfig;

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

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

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

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

Next.js автоматически подгружает эти переменные в Route Handlers (server-side).

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

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

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

MAILEXAM_PORT=587

В транспорте: secure: false.

MAILEXAM_PORT=2525

MAILEXAM_PORT=465

В транспорте: secure: true.

3. Транспорт Nodemailer

// mail.js
import 'dotenv/config';

import nodemailer from '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,
    },
  });
}

export 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 || 'Next.js + Mailexam',
    text: text || 'Тест Mailexam из Next.js',
  });
}

4. Route Handler

// app/api/mail/test/route.js
import { sendTest } from '../../../../mail.js';

export async function POST(request) {
  try {
    const body = await request.json();
    const { to, subject, text, body: messageBody } = body ?? {};

    await sendTest({
      to,
      subject,
      text: text ?? messageBody,
    });

    return Response.json({ status: 'ok' });
  } catch (error) {
    return Response.json({ error: error.message }, { status: 500 });
  }
}

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

npm run dev

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

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

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

Среда Рекомендация
local .env.local с учетными данными Mailexam®
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. Типичные проблемы

Connection timeout / authentication failed

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

Route возвращает 404

  • Путь должен быть /api/mail/test (App Router), а не /mail/test.

Порт 587 и TLS

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

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

  • Смотрите входящие того же проекта Mailexam®.
  • Проверьте JSON-ошибку в ответе route handler.

См. также