Forem: Pruthvisinh Rajput

I got tired of janky nodemailer mocks on every project

Pruthvisinh Rajput — Sun, 29 Mar 2026 20:09:20 +0000

Every Node.js project I've joined has the same file somewhere.

A giant jest.mock() block for nodemailer. Some manual spy setup. A comment that says "don't touch this." And at least one developer who spent three hours debugging it when transporter.sendMail silently stopped being called in tests.

I kept rebuilding the same abstraction on every project. Eventually I stopped rebuilding it and just shipped it as a library.

The fix: Mail.fake()

Mail.fake();

await Mail.to('user@example.com').send(new WelcomeEmail(user));

Mail.assertSent(WelcomeEmail, (mail) => mail.hasTo('user@example.com'));

No SMTP server. No network. No mock setup. The test fails if the wrong email goes to the wrong address. That's it.

What actually goes wrong with nodemailer mocks

Here's the pattern I kept seeing:

// Some version of this exists in nearly every Node.js codebase
jest.mock('nodemailer', () => ({
  createTransport: jest.fn().mockReturnValue({
    sendMail: jest.fn().mockResolvedValue({ messageId: 'test-id' }),
  }),
}));

It works. Until it doesn't.

Someone upgrades nodemailer and the mock stops matching the real API
A new developer adds a new email send call and the mock swallows it silently
You want to assert the email went to the right address and you're digging through sendMail.mock.calls[0][0].to
You switch from nodemailer to Resend and your entire mock layer needs to be rebuilt

Mail.fake() intercepts at the abstraction layer, not the transport layer. Your tests don't know or care what provider you're using.

A real test

import { Mail } from 'laramail';
import { WelcomeEmail } from './emails/WelcomeEmail';

describe('Registration', () => {
  beforeEach(() => Mail.fake());
  afterEach(() => Mail.restore());

  it('sends a welcome email on signup', async () => {
    await registerUser({ name: 'John', email: 'john@example.com' });

    // Did the right email class get sent?
    Mail.assertSent(WelcomeEmail);

    // Did it go to the right address?
    Mail.assertSent(WelcomeEmail, (mail) =>
      mail.hasTo('john@example.com')
    );

    // Did it have the right subject?
    Mail.assertSent(WelcomeEmail, (mail) =>
      mail.subjectContains('Welcome')
    );

    // Was it sent exactly once? Was nothing else sent?
    Mail.assertSentCount(WelcomeEmail, 1);
    Mail.assertNotSent(PasswordResetEmail);
  });
});

Assertions that read like plain English. No mock.calls[0][0].

The Mailable class

The WelcomeEmail above is a Mailable — a self-contained, testable email object. This is the pattern from Laravel (and AdonisJS) that I missed most in Node.js.

import { Mailable } from 'laramail';

class WelcomeEmail extends Mailable {
  constructor(private user: { name: string; email: string }) {
    super();
  }

  build() {
    return this
      .subject(`Welcome, ${this.user.name}!`)
      .html(`
        <h1>Hello ${this.user.name}!</h1>
        <p>Thanks for joining. Your account is ready.</p>
      `);
  }
}

await Mail.to(user.email).send(new WelcomeEmail(user));

Your email logic lives in one place. Easy to test, easy to reuse, easy to find.

Setup

import { Mail } from 'laramail';

Mail.configure({
  default: process.env.MAIL_DRIVER,
  from: { address: 'noreply@example.com', name: 'My App' },
  mailers: {
    smtp: {
      driver: 'smtp',
      host: process.env.SMTP_HOST,
      port: 587,
      auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
    },
    resend: {
      driver: 'resend',
      apiKey: process.env.RESEND_API_KEY,
    },
    sendgrid: {
      driver: 'sendgrid',
      apiKey: process.env.SENDGRID_API_KEY,
    },
  },
});

Switch providers by changing MAIL_DRIVER in your .env. No code changes anywhere else. That's a bonus side effect — the testing story is the reason I built this.

One more DX feature: staging redirect

In staging you never want to accidentally email real users. One line:

if (process.env.NODE_ENV === 'staging') {
  Mail.alwaysTo('dev@example.com');
}

Every email your staging environment sends goes to dev@example.com. CC and BCC cleared automatically. Works with Mail.fake() too — fake mode bypasses it so your test assertions still see the original recipients.

What's included

Mail.fake() + Mail.assertSent() — zero-setup email testing
Mailable classes — self-contained, reusable, testable email objects
6 providers — SMTP, SendGrid, AWS SES, Mailgun, Resend, Postmark
Provider failover — auto-chain if a provider fails
Rate limiting — sliding window, configurable per-mailer
Queue support — Bull / BullMQ
Template engines — Handlebars, EJS, Pug
Markdown emails — built-in components
Log transport — console output in dev, zero SMTP config
Staging redirect — Mail.alwaysTo()
CLI tools — laramail preview, laramail send-test, and more
774 tests, TypeScript-first

The one-line pitch: AdonisJS mailer, but framework-agnostic. Works with Express, Fastify, NestJS, or any Node.js app.

Get started

npm install laramail

GitHub — star it if this solves a problem you've hit
Documentation — full API reference including testing docs
npm

If you've been living with a fragile nodemailer mock on every project — I built this for you.

I Got Tired of Rewriting My Email Code Every Time I Switched Providers

Pruthvisinh Rajput — Sat, 28 Mar 2026 18:17:29 +0000

I've hit this pain three times across three different Node.js projects.

You're using SMTP in dev, SendGrid in production, and one day you decide to try Resend because you've heard great things. So you go into your code, swap out the nodemailer transport, install a different package, rewrite the config shape, hunt down every place you referenced transporter.sendMail(), update environment variables, and test everything again from scratch.

It takes half a day. It shouldn't.

Laravel solved this years ago. You configure your providers, your application code never knows which one is active, and you switch by changing MAIL_MAILER=resend in .env. That's it.

I wanted that in Node.js. It didn't exist. So I built it.

Introducing laramail

npm install laramail

laramail is a Laravel-style mail system for Node.js and TypeScript. Same API across every provider. Switch providers with one config change. Test email sending without mocks.

The Core Problem: Provider Lock-in

Here's what sending email with nodemailer + Resend looks like:

// Resend has its own SDK — can't use nodemailer at all
import { Resend } from 'resend';
const resend = new Resend(process.env.RESEND_API_KEY);
await resend.emails.send({
  from: 'noreply@example.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Hello!</h1>',
});

Now switch to SendGrid:

// Completely different package, completely different API
import sgMail from '@sendgrid/mail';
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
await sgMail.send({
  to: 'user@example.com',
  from: 'noreply@example.com',
  subject: 'Welcome!',
  html: '<h1>Hello!</h1>',
});

Every provider has a different package, a different API shape, a different config format. Switching requires code changes everywhere you send email.

The laramail Way

Configure your providers once:

import { Mail } from 'laramail';

Mail.configure({
  default: process.env.MAIL_DRIVER, // 'smtp' | 'sendgrid' | 'resend' | 'ses' | 'mailgun' | 'postmark'
  from: { address: 'noreply@example.com', name: 'My App' },
  mailers: {
    smtp: {
      driver: 'smtp',
      host: process.env.SMTP_HOST,
      port: 587,
      auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
    },
    resend: {
      driver: 'resend',
      apiKey: process.env.RESEND_API_KEY,
    },
    sendgrid: {
      driver: 'sendgrid',
      apiKey: process.env.SENDGRID_API_KEY,
    },
  },
});

Send email — the same code, always:

await Mail.to('user@example.com').send(new WelcomeEmail(user));

Switch from Resend to SendGrid:

# Before
MAIL_DRIVER=resend

# After
MAIL_DRIVER=sendgrid

No code changes. Zero.

Mailable Classes

Self-contained, reusable, testable email objects — just like Laravel:

import { Mailable } from 'laramail';

class WelcomeEmail extends Mailable {
  constructor(private user: { name: string; email: string }) {
    super();
  }

  build() {
    return this
      .subject(`Welcome, ${this.user.name}!`)
      .html(`<h1>Hello ${this.user.name}!</h1><p>Your account is ready.</p>`);
  }
}

await Mail.to(user.email).send(new WelcomeEmail(user));

Testing with Mail.fake()

This is the part I'm most proud of.

Testing email in Node.js is usually painful — you either hit a real server or write verbose mocks. Mail.fake() intercepts outgoing email and gives you readable assertions:

describe('Registration', () => {
  beforeEach(() => Mail.fake());
  afterEach(() => Mail.restore());

  it('sends a welcome email on signup', async () => {
    await registerUser({ name: 'John', email: 'john@example.com' });

    Mail.assertSent(WelcomeEmail);
    Mail.assertSent(WelcomeEmail, (mail) => mail.hasTo('john@example.com'));
    Mail.assertSent(WelcomeEmail, (mail) => mail.subjectContains('Welcome'));
    Mail.assertSentCount(WelcomeEmail, 1);
  });
});

No mocks. No SMTP server. Just Mail.fake() and assertions that read like plain English.

Provider Failover

Mail.configure({
  default: 'resend',
  failover: ['resend', 'sendgrid'], // try resend first, fall back to sendgrid
  mailers: {
    resend:   { driver: 'resend',   apiKey: process.env.RESEND_API_KEY },
    sendgrid: { driver: 'sendgrid', apiKey: process.env.SENDGRID_API_KEY },
  },
});

If Resend fails, laramail automatically retries with SendGrid.

Staging Redirect

Never accidentally email real users from staging again:

if (process.env.NODE_ENV === 'staging') {
  Mail.alwaysTo('dev@example.com');
}

Every email goes to dev@example.com. Regardless of what Mail.to() says.

What's Included

6 providers: SMTP, SendGrid, AWS SES, Mailgun, Resend, Postmark
3 template engines: Handlebars, EJS, Pug
Markdown emails with built-in components
Queue support via BullMQ
Rate limiting (sliding window, per-mailer)
Email events (sending/sent/failed hooks)
Email preview via CLI (laramail preview)
Custom providers via Mail.extend()
TypeScript-first — fully typed, no @types/ needed
620+ tests

Get Started

npm install laramail

GitHub: https://github.com/impruthvi/laramail — star it if this solves your problem
Docs: https://laramail.impruthvi.me
npm: https://npmjs.com/package/laramail

If you've been copy-pasting provider-specific email code across projects — I built this for you. If something's broken or missing, open an issue. I read every one.