Configuring Nodemailer with Gmail and SMTP Services

Nodemailer needs a transporter — an object that knows how to connect to an email server and deliver messages. You create it once with your SMTP credentials and reuse it across every email you send. In this lesson you will install Nodemailer, configure a Gmail transporter using an App Password, set up an Ethereal Email transporter for development testing, and build the sendEmail utility function that every email feature in the MERN Blog will call.

Installation #

cd server
npm install nodemailer

Environment Variables #

# server/.env

# ── Gmail (use App Password, not your real password) ──────────────────────────
EMAIL_SERVICE=gmail
EMAIL_USER=your_gmail@gmail.com
EMAIL_PASS=xxxx xxxx xxxx xxxx    # 16-char App Password from Google Account settings
EMAIL_FROM="MERN Blog" <noreply@mernblog.com>

# ── Alternative: SMTP service (SendGrid, Resend, Mailgun) ────────────────────
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.xxxxxxxxxxxxxxxx

# ── App URLs (for links in emails) ───────────────────────────────────────────
CLIENT_URL=http://localhost:5173
SERVER_URL=http://localhost:5000

# ── To generate a Gmail App Password: ────────────────────────────────────────
# Google Account → Security → 2-Step Verification → App passwords
# Select app: Mail, device: Other → type "MERN Blog" → Generate

The Email Utility Module #

// server/src/utils/sendEmail.js
const nodemailer = require('nodemailer');

// ── Create transporter once — reused for all emails ───────────────────────────
let transporter;

const createTransporter = async () => {
  // Development: use Ethereal Email (fake SMTP — captures without delivering)
  if (process.env.NODE_ENV === 'development') {
    const testAccount = await nodemailer.createTestAccount();
    transporter = nodemailer.createTransport({
      host:   'smtp.ethereal.email',
      port:    587,
      secure:  false,
      auth: {
        user: testAccount.user,
        pass: testAccount.pass,
      },
    });
    console.log('Ethereal test account created:', testAccount.user);
    return;
  }

  // Production: Gmail with App Password
  transporter = nodemailer.createTransport({
    service: 'gmail',
    auth: {
      user: process.env.EMAIL_USER,
      pass: process.env.EMAIL_PASS, // App Password — NOT your real password
    },
  });
};

// Initialise once on module load
createTransporter().catch(console.error);

// ── The sendEmail utility — called by all email features ─────────────────────
const sendEmail = async ({ to, subject, text, html }) => {
  if (!transporter) {
    throw new Error('Email transporter not initialised');
  }

  const info = await transporter.sendMail({
    from:    process.env.EMAIL_FROM || '"MERN Blog" <noreply@mernblog.com>',
    to,
    subject,
    text,    // plain text fallback
    html,    // HTML version
  });

  // In development, log the Ethereal URL to view the captured email
  if (process.env.NODE_ENV === 'development') {
    console.log('Email preview URL:', nodemailer.getTestMessageUrl(info));
  }

  return info;
};

module.exports = sendEmail;

Using sendEmail in Controllers #

// Usage example — sending a simple email from a controller
const sendEmail = require('../utils/sendEmail');

const register = asyncHandler(async (req, res) => {
  const { name, email, password } = req.body;
  const user = await User.create({ name, email, password });

  const token = signAccessToken(user._id, user.role);
  res.status(201).json({ success: true, token, data: user });

  // Fire and forget — send welcome email after responding
  sendEmail({
    to:      user.email,
    subject: 'Welcome to MERN Blog!',
    text:    `Hi ${user.name}, welcome to MERN Blog!`,
    html:    `<p>Hi <strong>${user.name}</strong>, welcome to MERN Blog!</p>`,
  }).catch(err => console.error('Welcome email failed:', err.message));
});

Testing with Ethereal in Development #

Flow in development:
  1. POST /api/auth/register → user created → sendEmail() called
  2. Nodemailer connects to smtp.ethereal.email
  3. Email is "delivered" to Ethereal (captured — NOT sent to real inbox)
  4. Console logs: "Email preview URL: https://ethereal.email/message/xxxx"
  5. Open the URL in browser — see the formatted email exactly as it would appear
  6. No real email delivered — safe to test with any email address

Flow in production (Gmail):
  1. Same sendEmail() call
  2. Nodemailer connects to Gmail SMTP
  3. Email delivered to recipient's real inbox
  4. No preview URL logged

SMTP Configuration for Popular Services #

// ── Resend (recommended for production) ───────────────────────────────────────
transporter = nodemailer.createTransport({
  host: 'smtp.resend.com',
  port:  465,
  secure: true,
  auth: { user: 'resend', pass: process.env.RESEND_API_KEY },
});

// ── SendGrid ──────────────────────────────────────────────────────────────────
transporter = nodemailer.createTransport({
  host: 'smtp.sendgrid.net',
  port:  587,
  auth: { user: 'apikey', pass: process.env.SENDGRID_API_KEY },
});

// ── Mailgun ───────────────────────────────────────────────────────────────────
transporter = nodemailer.createTransport({
  host: 'smtp.mailgun.org',
  port:  587,
  auth: { user: process.env.MAILGUN_USER, pass: process.env.MAILGUN_PASS },
});

Common Mistakes #

Mistake 1 — Creating a new transporter on every sendEmail call #

❌ Wrong — transporter recreated every time:

const sendEmail = async ({ to, subject, ... }) => {
  const transporter = nodemailer.createTransport({ ... }); // new connection every email!
  await transporter.sendMail({ ... });
};

✅ Correct — create once at module level and reuse:

// Created once — module-level variable
const transporter = nodemailer.createTransport({ ... });
const sendEmail = async (options) => transporter.sendMail(options); // ✓

Mistake 2 — Using your real Gmail password #

❌ Wrong — real password in .env:

EMAIL_PASS=myRealGmailPassword123
# If .env is ever committed or leaked — full account access for attacker

✅ Correct — use a Gmail App Password (16 characters, generated for this app only).

Mistake 3 — Not providing a plain text fallback #

❌ Wrong — only HTML content:

transporter.sendMail({ to, subject, html: '<p>Welcome!</p>' });
// Some email clients or spam filters prefer or require plain text

✅ Correct — always include both:

transporter.sendMail({ to, subject, text: 'Welcome!', html: '<p>Welcome!</p>' }); // ✓

Quick Reference #