Test Node.js emails locally with Nodemailer

Point Nodemailer at a local SMTP server on your Mac and catch every email your Node.js app sends in development. Works with Express, NestJS, Next.js and more.

Whether you use Express, NestJS, Next.js API routes or a plain script, most Node.js apps send email through Nodemailer. In development you want those emails caught, not delivered. Mailbox runs a local SMTP server on your Mac: point Nodemailer at it and every message appears instantly, rendered, with headers and attachments.

1. Start a server in Mailbox

Open Mailbox. On first launch it creates a server on port 2525 — make sure it’s started. If you add another server instead, Mailbox picks a free port for it; use that port in the steps below.

2. Create the transport

import nodemailer from "nodemailer";

export const transporter = nodemailer.createTransport({
  host: "127.0.0.1",
  port: 2525,
  secure: false,
});

secure: false means plain SMTP, which is what Mailbox speaks. Nodemailer only upgrades to TLS when the server offers it, so no extra options are needed. Leave out the auth object — Mailbox doesn’t use SMTP authentication. The examples use 127.0.0.1 because Mailbox listens on IPv4.

A common pattern is to read these values from the environment, so production keeps its real provider:

const transporter = nodemailer.createTransport({
  host: process.env.SMTP_HOST ?? "127.0.0.1",
  port: Number(process.env.SMTP_PORT ?? 2525),
  secure: false,
});

3. Send a test email

Save this as send-test.mjs and run node send-test.mjs:

import nodemailer from "nodemailer";

const transporter = nodemailer.createTransport({ host: "127.0.0.1", port: 2525, secure: false });

const info = await transporter.sendMail({
  from: '"My App" <app@example.com>',
  to: "test@example.com",
  subject: "Hello from Node.js",
  text: "It works!",
  html: "<h1>It works!</h1>",
});

console.log("Sent", info.messageId);

The email appears in Mailbox right away.

Using SendGrid, Postmark or Resend SDKs?

If your app talks to an email API instead of SMTP, Mailbox Pro can stand in for that too: it exposes local endpoints that accept the same requests as SendGrid, Postmark, Resend, Mailgun, Brevo and Mailtrap, so you only change the base URL. See the API section for details.

Running Node in Docker

Inside a container, 127.0.0.1 is the container itself. Use host.docker.internal as the host instead.

If the container still can’t connect, turn on Allow Network Access in Mailbox (Settings → General) and restart the server, so it accepts connections from outside the loopback interface.

Troubleshooting

  • ECONNREFUSED 127.0.0.1:2525 — the Mailbox server isn’t running, or the port doesn’t match.
  • TLS or certificate errors — make sure secure is false and that no requireTLS option is set.

What to check next

Use Mailbox’s HTML compatibility check to see which CSS in your templates email clients like Outlook won’t support, and the mobile preview to check responsive layouts. Testing several services? With Mailbox Pro, give each one its own server and port.

More guides