Skip to content

Node.js

Guide for applications on Node.js 18+ without a web framework. Mailexam connects as SMTP via Nodemailer. The HTTP endpoint below is built on the built-in http module.

Frameworks

If you use Express, Fastify, Hapi, or NestJS, see the dedicated guides: Express, Fastify, Hapi, NestJS.

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

npm init -y
npm install nodemailer dotenv

package.json:

{
  "type": "commonjs",
  "scripts": {
    "start": "node server.js",
    "send": "node send-test.js"
  },
  "dependencies": {
    "dotenv": "^16.0.0",
    "nodemailer": "^6.9.0"
  }
}

2. Environment variables

.env file 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.

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
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.io`,
    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 || 'Node.js + Mailexam',
    text: text || 'Mailexam test from Node.js',
  });
}

module.exports = { sendTest };

4. Sending from a script

send-test.js — without an HTTP server:

require('dotenv').config();

const { sendTest } = require('./mail');

sendTest({
  to: 'user@example.test',
  subject: 'Test',
  text: 'Hello from Node.js',
})
  .then(() => {
    console.log('Sent');
  })
  .catch((err) => {
    console.error(err);
    process.exit(1);
  });

npm run send

5. HTTP server with http

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

const http = require('http');
const { sendTest } = require('./mail');

function readJson(req) {
  return new Promise((resolve, reject) => {
    let data = '';

    req.on('data', (chunk) => {
      data += chunk;
    });

    req.on('end', () => {
      try {
        resolve(data ? JSON.parse(data) : {});
      } catch (err) {
        reject(err);
      }
    });

    req.on('error', reject);
  });
}

function json(res, statusCode, payload) {
  res.writeHead(statusCode, { 'Content-Type': 'application/json; charset=utf-8' });
  res.end(JSON.stringify(payload));
}

const server = http.createServer(async (req, res) => {
  if (req.method === 'POST' && req.url === '/mail/test') {
    try {
      const body = await readJson(req);
      await sendTest(body);
      json(res, 200, { status: 'ok' });
    } catch (err) {
      console.error(err);
      json(res, 500, { error: err.message });
    }
    return;
  }

  res.writeHead(404);
  res.end();
});

const port = 3000;
server.listen(port, '127.0.0.1', () => {
  console.log(`Server running on http://127.0.0.1:${port}`);
});

Start and verify:

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"}'

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

6. Local development and CI

Environment Recommendation
local .env + require('dotenv').config()
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.

7. Common issues

Connection timeout / authentication failed

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

Port 587 and TLS

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

Variables not read

  • Call require('dotenv').config() before require('./mail') or export variables in the shell.

Message not in the dashboard

  • View the inbox of the same Mailexam project.
  • SMTP errors are printed to console.error on a 500 response.

See also