Skip to content

Midway.js

Guide for applications built with Midway.js 3 on Koa (Node.js 18+). Mailexam connects as SMTP via Nodemailer in a @Provide() service.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • A Midway 3 project (CLI: npm init midway@latest -- --type=koa-v3).

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 nodemailer dotenv
npm install -D @types/nodemailer

Midway Koa starter already includes @midwayjs/koa, @midwayjs/core, and @midwayjs/bootstrap.

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

Load .env before bootstrap (for example, in bootstrap.js):

require('dotenv').config();

const { Bootstrap } = require('@midwayjs/bootstrap');
Bootstrap.run();

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

MAILEXAM_PORT=2525

MAILEXAM_PORT=465

In transport set secure: true.

3. Mail service

src/service/mail.service.ts:

import { Provide } from '@midwayjs/core';
import * as nodemailer from 'nodemailer';
import type { Transporter } from 'nodemailer';

@Provide()
export class MailService {
  private createTransport(): Transporter {
    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 sendTest(to: string, subject: string, text: string): Promise<void> {
    const from = process.env.MAIL_FROM || 'noreply@example.test';

    await this.createTransport().sendMail({ from, to, subject, text });
  }
}

4. Test route

src/controller/mail.controller.ts:

import { Body, Controller, Inject, Post } from '@midwayjs/core';
import { MailService } from '../service/mail.service';

interface SendMailBody {
  to?: string;
  subject?: string;
  text?: string;
  body?: string;
}

@Controller('/mail')
export class MailController {
  @Inject()
  mailService: MailService;

  @Post('/test')
  async test(@Body() body: SendMailBody) {
    await this.mailService.sendTest(
      body.to ?? 'user@example.test',
      body.subject ?? 'Midway + Mailexam',
      body.text ?? body.body ?? 'Mailexam test from Midway.js'
    );

    return { status: 'ok' };
  }
}

Default HTTP port in Midway Koa is 7001 (koa.port in src/config/config.default.ts).

Start and verify:

npm run build
npm start

curl -X POST http://127.0.0.1:7001/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 + dotenv in bootstrap.js
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, 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

  • Load .env in bootstrap.js before Bootstrap.run(), or export variables in CI.

Message not in the dashboard

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

See also