mail-opener

Preview the emails your Node.js app sends, right in your browser, during development. mail-opener is a zero-config Nodemailer transport that opens email previews directly in your browser without requiring an SMTP server, Docker container, or extra background process.

Status: early development. Preview is on when NODE_ENV is development. auto uses file mode, and mode: 'server' opens a local inbox. In production, mail goes to production.transport when you provide one. The package is not published yet.

Why

Previewing development email in Node.js usually means running MailHog, MailDev, Docker, or another SMTP server in a separate process. mail-opener is a Nodemailer transport instead: it runs inside your app, saves each email locally, and opens it in your browser. No SMTP server, no Docker, no extra terminal.

Your email-sending code stays the same in development and production. In development, emails are previewed; in production, mail-opener stays out of the way and your real transport delivers them.

Quick start

With NODE_ENV=development, this installs the package, sends one message, and opens it in your browser. No SMTP server and no extra process.

npm install mail-opener nodemailer

import nodemailer from 'nodemailer';
import { createMailOpenerTransport } from 'mail-opener';

const transporter = nodemailer.createTransport(createMailOpenerTransport());

await transporter.sendMail({
  to: '[email protected]',
  subject: 'Welcome',
  html: '<h1>Hello</h1>',
});

The same sendMail() call is what you keep in application code. Configure the transport once.

production.transport is the low-level Nodemailer transport, the .transporter on the object createTransport() returns. In development, auto saves a file preview. In production, that SMTP transport delivers the message.

import nodemailer from 'nodemailer';
import { createMailOpenerTransport } from 'mail-opener';

const smtp = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: 587,
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
});

export const transporter = nodemailer.createTransport(
  createMailOpenerTransport({
    development: { mode: 'auto' },
    production: { transport: smtp.transporter },
  }),
);

Copy-paste files for each framework live in examples/. None of those frameworks are dependencies of this package.

Node.js

Use the quick start above from any server script. examples/node.ts is the same setup with a production SMTP transport.

Express

Create the transporter once next to the app, then call it from a route. examples/express.ts:

import express from 'express';
import nodemailer from 'nodemailer';
import { createMailOpenerTransport } from 'mail-opener';

const smtp = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: 587,
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
});

const transporter = nodemailer.createTransport(
  createMailOpenerTransport({
    development: { mode: 'auto' },
    production: { transport: smtp.transporter },
  }),
);

const app = express();
app.use(express.json());

app.post('/welcome', async (request, response) => {
  await transporter.sendMail({
    to: request.body.to,
    subject: 'Welcome',
    html: '<h1>Hello</h1>',
  });
  response.sendStatus(202);
});

NestJS

Do not choose the transport inside each mail method. One module owns it, and every service calls sendMail. examples/nestjs.ts:

import { Injectable, Module } from '@nestjs/common';
import nodemailer from 'nodemailer';
import { createMailOpenerTransport } from 'mail-opener';

const smtp = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: 587,
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
});

const transporter = nodemailer.createTransport(
  createMailOpenerTransport({
    development: { mode: 'auto' },
    production: { transport: smtp.transporter },
  }),
);

@Injectable()
export class MailService {
  async sendWelcome(to: string): Promise<void> {
    await transporter.sendMail({
      to,
      subject: 'Welcome',
      html: '<h1>Hello</h1>',
    });
  }
}

@Module({
  providers: [MailService],
  exports: [MailService],
})
export class MailModule {}

This is the branch to avoid copying into every service. The transport above already switches for you:

const transport = process.env.NODE_ENV === 'development' ? createMailOpenerTransport() : smtp.transporter;

Next.js

Use it from server code such as app/api/welcome/route.ts. examples/nextjs.ts.

mail-opener is server-side only. Do not import it from a Client Component, and do not let it end up in browser JavaScript. A file that starts with 'use client' must not import this package. The server-only package can make a bad import fail the build. That package belongs to the Next.js app, not to mail-opener.

// lib/mail.ts
import 'server-only';
import nodemailer from 'nodemailer';
import { createMailOpenerTransport } from 'mail-opener';

const smtp = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: 587,
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
});

export const transporter = nodemailer.createTransport(
  createMailOpenerTransport({
    development: { mode: 'auto' },
    production: { transport: smtp.transporter },
  }),
);

// app/api/welcome/route.ts
import { transporter } from '../../../lib/mail';

export async function POST(): Promise<Response> {
  await transporter.sendMail({
    to: '[email protected]',
    subject: 'Welcome',
    html: '<h1>Hello</h1>',
  });
  return Response.json({ ok: true });
}

CLI

The commands are optional. Sending mail does not use them.

npx mail-opener path
npx mail-opener list
npx mail-opener clear

path prints the preview directory. list prints saved emails. clear deletes them. --directory overrides MAIL_OPENER_DIRECTORY.

Development

The published package supports Node.js 18 and later. Working on the package itself requires Node.js 24, pinned in .nvmrc:

nvm use
npm install

Scripts:

• npm run build: build ESM, CommonJS, and type declarations into dist/
• npm run dev: rebuild on every change
• npm test: run the test suite once
• npm run test:watch: run tests in watch mode
• npm run typecheck: type-check with tsc
• npm run lint: lint with ESLint
• npm run format: format with Prettier (npm run format:check only reports)

License

MIT