Hapi¶

Guide for applications built with Hapi (Node.js 18+). Mailexam connects as SMTP via Nodemailer — a separate mail plugin is not required.

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 @hapi/hapi nodemailer dotenv

package.json:

{
  "type": "commonjs",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "@hapi/hapi": "^21.0.0",
    "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¶

587 + STARTTLS (recommended)2525465 (SMTPS)

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 || 'Hapi + Mailexam',
    text: text || 'Mailexam test from Hapi',
  });
}

module.exports = { sendTest };

4. Hapi route¶

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

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

async function init() {
  const server = Hapi.server({
    port: 3000,
    host: '127.0.0.1',
  });

  server.route({
    method: 'POST',
    path: '/mail/test',
    options: {
      payload: {
        parse: true,
        allow: 'application/json',
      },
    },
    handler: async (request) => {
      const { to, subject, text } = request.payload || {};

      await sendTest({ to, subject, text });

      return { status: 'ok' };
    },
  });

  await server.start();
  console.log('Server running on %s', server.info.uri);
}

init().catch((err) => {
  console.error(err);
  process.exit(1);
});

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.

5. 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"

For unit tests mock sendTest or use a Nodemailer test account separately from Mailexam.

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

6. 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.

Empty payload

Make sure payload.parse: true and the Content-Type: application/json header is set.

Message not in the dashboard

View the inbox of the same Mailexam project.
SMTP errors are printed to the Node console when sendMail fails.