> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thepurplebox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Nodemailer

> Learn how to send transactional emails using thePurplebox with Nodemailer

[Nodemailer](https://nodemailer.com/) 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

<CodeGroup>
  ```sh npm theme={null}
  npm i nodemailer
  ```

  ```sh yarn theme={null}
  yarn add nodemailer
  ```

  ```sh pnpm theme={null}
  pnpm add nodemailer
  ```

  ```sh bun theme={null}
  bun add nodemailer
  ```
</CodeGroup>

### Optional: Install Nodemailer TypeScript types

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

<CodeGroup>
  ```sh npm theme={null}
  npm i -D @types/nodemailer
  ```

  ```sh yarn theme={null}
  yarn add -D @types/nodemailer
  ```

  ```sh pnpm theme={null}
  pnpm add -D @types/nodemailer
  ```

  ```sh bun theme={null}
  bun add -D @types/nodemailer
  ```
</CodeGroup>

## Set up environment variables

Store your SMTP password securely in a `.env` file:

```sh .env theme={null}
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`:

```js theme={null}
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`:

```js theme={null}
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:

```js theme={null}
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:

```js theme={null}
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);
}
```