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." <[email protected]>',
      to: ["[email protected]", "[email protected]"],
      cc: ["[email protected]"],
      bcc: ["[email protected]"],
      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

1. Features
2. API Reference
   • createTransporter(options)
   • sendEmail(mailOptions, transporter)
3. Configuration Options
4. Usage Examples
5. Error Handling
6. Testing
7. Contributing
8. Change Log
9. License

✅ 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 protected]>") | | 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: "[email protected]",
    to: ["[email protected]"],
    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: "[email protected]",
    to: "[email protected]",
    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.

🧪 Testing

Tests are written with Jest. To run:

npm test

Test Coverage

npm run test:coverage

🤝 Contributing

We welcome contributions! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes (git commit -m 'feat: add new feature')
4. Push to your branch (git push origin feat/my-feature)
5. Open a Pull Request

See CONTRIBUTING.md for details.

📝 Change Log

See CHANGELOG.md for version history and release notes.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.
© 2025 NXT Webmasters. All rights reserved.