@nxtwebmasters/nxt-mailer NPM

NXTWEBMASTERS/NXT MAILER

A lightweight, zero-dependency Node.js module for sending transactional emails using Gmail (or any SMTP) via Nodemailer. Perfect for serverless functions, microservices, or any Node.js app needing quick email capabilities.

📦 Installation

Install via NPM:

npm install @nxtwebmasters/nxt-mailer

Install via Yarn:

yarn add @nxtwebmasters/nxt-mailer

🔧 Quick Start

Import Package

import { createTransporter, sendEmail } from "@nxtwebmasters/nxt-mailer";

Create Transporter with your SMTP credentials

(async () => {
  const transporter = createTransporter({
    host: "smtp.gmail.com",
    port: 465,
    secure: true, // true for 465, false for other ports
    auth: {
      user: process.env.EMAIL_USER,
      pass: process.env.EMAIL_PASSWORD,
    },
  });

Send Email

  await sendEmail(
    {
      from: '"Acme Inc." <no-reply@acme.com>',
      to: ["alice@example.com", "bob@example.com"],
      cc: ["manager@example.com"],
      bcc: ["audit@example.com"],
      subject: "Welcome to Acme!",
      text: "Hello there!",
      html: "<p>Hello <strong>there</strong>!</p>",
      attachments: [{ filename: "terms.pdf", path: "./docs/terms.pdf" }],
    },
    transporter
  );
  console.log("✅ Email sent successfully");
})();

📖 Table of Contents

✅ Features

Zero dependencies beyond Nodemailer
Gmail SMTP presets (but works with any SMTP)
Multi-recipient support: To, CC, BCC
Rich content: plain-text, HTML, inline images
Attachments: files, streams, buffers
Promise-based API with async/await
TypeScript type definitions included

🔌 API Reference

`createTransporter(options)`

Creates and returns a Nodemailer transporter instance.

Property	Type	Required	Default	Description
`host`	`string`	✓	—	SMTP server hostname (e.g., `"smtp.gmail.com"`)
`port`	`number`	✓	—	SMTP port (465 for SSL, 587 for TLS)
`secure`	`boolean`	✓	`false`	`true` for port 465 (SSL), `false` for others
`auth`	`object`	✓	—	Authentication object
└─ `user`	`string`	✓	—	SMTP username (e.g., your email address)
└─ `pass`	`string`	✓	—	SMTP password or app-specific password
`logger`	`boolean`	✗	`false`	Enable Nodemailer logging
`debug`	`boolean`	✗	`false`	Show SMTP traffic for debugging

interface TransportOptions {
  host: string;
  port: number;
  secure: boolean;
  auth: {
    user: string;
    pass: string;
  };
  logger?: boolean;
  debug?: boolean;
}

`sendEmail(mailOptions, transporter)`

Sends an email using the provided transporter. Returns a promise that resolves with the Nodemailer info object.

Property	Type	Required	Description
`from`	`string`	✓	Sender address (e.g., `"Name <email@domain.com>"`)
`to`	`string` \| `string[]`	✓	Primary recipient(s)
`cc`	`string` \| `string[]`	✗	CC recipient(s)
`bcc`	`string` \| `string[]`	✗	BCC recipient(s)
`subject`	`string`	✓	Email subject line
`text`	`string`	✗	Plain-text body
`html`	`string`	✗	HTML body
`attachments`	`Attachment[]`	✗	Array of attachment objects (see below)

interface MailOptions {
  from: string;
  to: string | string[];
  cc?: string | string[];
  bcc?: string | string[];
  subject: string;
  text?: string;
  html?: string;
  attachments?: Attachment[];
}

interface Attachment {
  filename?: string;
  path?: string;
  href?: string;
  content?: Buffer | string;
  contentType?: string;
  cid?: string; // inline images
}

Returns:
Promise<import("nodemailer").SentMessageInfo>

⚙️ Configuration Options

Beyond SMTP auth, you can pass any Nodemailer transporter options:

const transporter = createTransporter({
  host: process.env.SMTP_HOST,
  port: +process.env.SMTP_PORT,
  secure: process.env.SMTP_SECURE === "true",
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
  logger: true, // Turn on Nodemailer logger
  debug: true, // Show SMTP traffic
});

💡 Usage Examples

1. Sending Inline Images

await sendEmail(
  {
    from: "no-reply@acme.com",
    to: ["user@example.com"],
    subject: "Inline Images Example",
    html: '<h1>Logo</h1><img src="cid:logo@acme"/>',
    attachments: [
      { filename: "logo.png", path: "./assets/logo.png", cid: "logo@acme" },
    ],
  },
  transporter
);

2. Sending Buffers or Streams

import fs from "fs";

const pdfBuffer = fs.readFileSync("./reports/summary.pdf");

await sendEmail(
  {
    from: "reports@acme.com",
    to: "manager@acme.com",
    subject: "Monthly Report",
    text: "Please find the report attached.",
    attachments: [{ filename: "report.pdf", content: pdfBuffer }],
  },
  transporter
);

⚠️ Error Handling

sendEmail will throw if sending fails. Wrap calls in try/catch:

try {
  await sendEmail(
    {
      /* ... */
    },
    transporter
  );
  console.log("✅ Success");
} catch (err) {
  console.error("❌ Email failed:", err);
}

Common errors include authentication failures, network timeouts, or invalid addresses.