NestJS¶

Guide for applications built with NestJS (Node.js 18+). Mailexam connects as SMTP via Nodemailer and the @nestjs-modules/mailer module.

What you need¶

A Mailexam account and a project with SMTP credentials.
A Nest application (CLI: nest new).

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 install @nestjs-modules/mailer nodemailer
npm install -D @types/nodemailer

Optional for .env:

npm install @nestjs/config

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 (STARTTLS on 587).

MAILEXAM_PORT=2525

MAILEXAM_PORT=465

In transport set secure: true.

3. Mailer module¶

app.module.ts:

import { Module } from '@nestjs/common';
import { MailerModule } from '@nestjs-modules/mailer';
import { ConfigModule } from '@nestjs/config';
import { MailController } from './mail.controller';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    MailerModule.forRootAsync({
      useFactory: () => {
        const login = process.env.MAILEXAM_LOGIN!;
        const port = Number(process.env.MAILEXAM_PORT ?? 587);

        return {
          transport: {
            host: `${login}.mailexam.io`,
            port,
            secure: port === 465,
            auth: {
              user: login,
              pass: process.env.MAILEXAM_PASSWORD,
            },
          },
          defaults: {
            from: process.env.MAIL_FROM ?? 'noreply@example.test',
          },
        };
      },
    }),
  ],
  controllers: [MailController],
})
export class AppModule {}

Without @nestjs/config remove ConfigModule and make sure variables are set in the process environment.

4. Test route¶

// mail.controller.ts
import { Body, Controller, Post } from '@nestjs/common';
import { MailerService } from '@nestjs-modules/mailer';

class SendMailDto {
  to?: string;
  subject?: string;
  text?: string;
}

@Controller('mail')
export class MailController {
  constructor(private readonly mailer: MailerService) {}

  @Post('test')
  async test(@Body() body: SendMailDto) {
    await this.mailer.sendMail({
      to: body.to ?? 'user@example.test',
      subject: body.subject ?? 'Nest + Mailexam',
      text: body.text ?? 'Mailexam test from NestJS',
    });

    return { status: 'ok' };
  }
}

Start and verify:

npm run start:dev

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` + `ConfigModule.forRoot()`
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 MailerService or use transport: { jsonTransport: true } in the test module.

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

Use secure: false for 587 (STARTTLS). For 465 — secure: true.

Variables undefined

Add ConfigModule.forRoot() or export .env in CI.

Message not in the dashboard

View the inbox of the same Mailexam project.
Check Nest logs on sendMail (SMTP errors appear in the console).