Nodemailer is a popular Node.js library for sending emails.
In this guide, you’ll learn how to configure it with thePurplebox SMTP service to send transactional emails reliably and securely.

Prerequisites

Before getting started, make sure your project has:

Nodemailer installed
A thePurplebox SMTP password (API key) stored in your .env file
A verified sending domain (recommended for best deliverability)

Install Nodemailer

npm i nodemailer

yarn add nodemailer

pnpm add nodemailer

bun add nodemailer

Optional: Install Nodemailer TypeScript types

If your project uses TypeScript, install the types as well:

npm i -D @types/nodemailer

yarn add -D @types/nodemailer

pnpm add -D @types/nodemailer

bun add -D @types/nodemailer

Set up environment variables

Store your SMTP password securely in a .env file:

.env

SMTP_PASSWORD=your-secret-api-key

Note: The SMTP username is always: thepurplebox

Sending Transactional Emails

Once Nodemailer and your environment variables are set up, you can create a transporter. This object defines the SMTP connection settings and determines whether you use STARTTLS or SSL.

Using STARTTLS (Port 587)

Set secure to false and use port 587:

import { createTransport } from "nodemailer";

const transporter = createTransport({
  host: "smtp.thepurplebox.io",
  port: 587,
  secure: false, // STARTTLS
  auth: {
    user: "thepurplebox",
    pass: process.env.SMTP_PASSWORD
  }
});

Using SSL (Port 465)

Set secure to true and use port 465:

import { createTransport } from "nodemailer";

const transporter = createTransport({
  host: "smtp.thepurplebox.io",
  port: 465,
  secure: true, // SSL
  auth: {
    user: "thepurplebox",
    pass: process.env.SMTP_PASSWORD
  }
});

Sending an Email

Now that the transporter is configured, you can send your first email with thePurplebox:

const info = await transporter.sendMail({
  from: "hello@example.com",
  to: "user@example.com",
  subject: "Welcome to thePurplebox!",
  html: "<p>Your email is being delivered successfully 🎉</p>"
});

console.log("Email sent:", info.messageId);

Or use a try/catch for better error handling:

try {
  const info = await transporter.sendMail({
    from: "hello@example.com",
    to: "user@example.com",
    subject: "Welcome to thePurplebox!",
    html: "<p>Your email is being delivered successfully 🎉</p>"
  });

  console.log("Email sent:", info.messageId);
} catch (err) {
  console.error("Failed to send email:", err);
}

Get Started

Guides

Tools

Configuration

Using Nodemailer

Prerequisites

Install Nodemailer

Optional: Install Nodemailer TypeScript types

Set up environment variables

Sending Transactional Emails

Using STARTTLS (Port 587)

Using SSL (Port 465)

Sending an Email

​Prerequisites

​Install Nodemailer

​Optional: Install Nodemailer TypeScript types

​Set up environment variables

​Sending Transactional Emails

​Using STARTTLS (Port 587)

​Using SSL (Port 465)

​Sending an Email

Prerequisites

Install Nodemailer

Optional: Install Nodemailer TypeScript types

Set up environment variables

Sending Transactional Emails

Using STARTTLS (Port 587)

Using SSL (Port 465)

Sending an Email