Skip to content

Next.js

Guide for applications built with Next.js (Node.js 18+, App Router). Mailexam connects as SMTP via Nodemailer and a Route Handler at POST /api/mail/test.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • Node.js 18+ and npm.

Copy from the welcome email (or dashboard) for your project:

  • YOUR_LOGIN — SMTP login (for example, xxxxx);
  • YOUR_PASSWORD — SMTP password (a unique pair with the login);
  • host — YOUR_LOGIN.mailexam.io (matches the login).

1. Dependencies

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

Minimal package.json dependencies:

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

Enable standalone output in next.config.js if you deploy with Docker:

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

module.exports = nextConfig;

2. Environment variables

.env or .env.local in the project root (do not commit passwords to git):

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

SMTP host: YOUR_LOGIN.mailexam.io.

Next.js loads these variables automatically in Route Handlers (server-side).

Sender address

MAIL_FROM can be any test address — the message goes to Mailexam, not to a real recipient.

Alternative ports

MAILEXAM_PORT=587

In transport: secure: false.

MAILEXAM_PORT=2525

MAILEXAM_PORT=465

In transport: secure: true.

3. Nodemailer transport

// 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.io`,
    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 test from 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 });
  }
}

Start and verify:

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":"Test","text":"Hello"}'

The message will appear in the Mailexam dashboard → your project → inbox.

5. Local development and CI

Environment Recommendation
local .env.local with Mailexam credentials
CI secrets MAILEXAM_LOGIN, MAILEXAM_PASSWORD in GitLab CI/CD Variables

Example for .gitlab-ci.yml:

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

After an integration test, verify delivery via the Mailexam API.

6. Common issues

Connection timeout / authentication failed

  • Host must be {login}.mailexam.io, user the same login from the email.
  • Login and password are a pair from the email for one project.

Route returns 404

  • Path is /api/mail/test (App Router), not /mail/test.

Port 587 and TLS

  • For 587: secure: false (STARTTLS). For 465: secure: true.

Message not in the dashboard

  • View the inbox of the same Mailexam project.
  • Check the JSON error body from the route handler.

See also