@oxog/mailer - Zero-Dependency SMTP Mailer for Node.js

Why Choose @oxog/mailer?

Built from the ground up with modern standards and best practices

🔒

Zero Dependencies

No external packages. Everything implemented from scratch using only Node.js built-in modules for maximum security and reliability.

📘

TypeScript First

Complete TypeScript support with strict typing. Full IntelliSense and type safety out of the box.

🚀

Modern API

Clean, intuitive API with Promise-based async/await support. No callbacks, just modern JavaScript.

⚡

High Performance

Connection pooling, rate limiting, and efficient resource management for high-throughput applications.

🔐

Security First

STARTTLS support, multiple authentication methods (PLAIN, LOGIN, CRAM-MD5, OAuth2).

🧩

Extensible

Plugin system with event-driven architecture. Customize and extend functionality as needed.

Getting Started

Send your first email in under 60 seconds

Installation

npm install @oxog/mailer

Basic Usage

import { Mailer } from '@oxog/mailer';

const mailer = new Mailer({
  host: 'smtp.gmail.com',
  port: 587,
  secure: false,
  auth: {
    user: 'your-email@gmail.com',
    pass: 'your-app-password',
  },
});

async function sendEmail() {
  const result = await mailer.send({
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Hello from @oxog/mailer!',
    text: 'This is a test email.',
    html: 'Hello!
This is a test email.
',
  });

  console.log('Email sent:', result.messageId);
}

sendEmail();

Factory Methods

Quick setup for popular email providers:

Gmail

const gmailMailer = Mailer.createGmailClient(
  'user@gmail.com',
  'app-password'
);

Outlook

const outlookMailer = Mailer.createOutlookClient(
  'user@outlook.com',
  'password'
);

OAuth2

const gmailOAuth = Mailer.createGmailOAuth2Client(
  'user@gmail.com',
  'access-token'
);

Examples

Real-world usage examples

HTML Email with Attachment

await mailer.send({
  from: 'sender@example.com',
  to: 'recipient@example.com',
  subject: 'Report Attachment',
  html: `
    <h2>Monthly Report</h2>
    <p>Please find the report attached.</p>
  `,
  attachments: [
    {
      filename: 'report.pdf',
      path: './reports/monthly.pdf',
      contentType: 'application/pdf'
    }
  ]
});

Multiple Recipients

await mailer.send({
  from: 'sender@example.com',
  to: [
    'team@example.com',
    { name: 'John Doe', address: 'john@example.com' }
  ],
  cc: 'manager@example.com',
  bcc: 'archive@example.com',
  subject: 'Team Update',
  text: 'Weekly team update...'
});

Using Plugins

const loggerPlugin = {
  name: 'logger',
  install(mailer) {
    mailer.on('beforeSend', (message) => {
      console.log('Sending:', message.subject);
    });

    mailer.on('afterSend', (result) => {
      console.log('Sent:', result.messageId);
    });
  }
};

mailer.use(loggerPlugin);

Error Handling

try {
  await mailer.send(message);
} catch (error) {
  if (error instanceof MailerError) {
    console.error('Error:', error.code, error.message);
    console.error('Solution:', error.solution);
  }
}

API Reference

Complete API documentation

MailerOptions

host: string

SMTP server hostname (required)

port?: number

SMTP server port (default: 587 for non-secure, 465 for secure)

secure?: boolean

Use SSL/TLS connection (default: false)

auth?: AuthOptions

Authentication credentials

rateLimit?: number

Rate limit in messages per second

Message

from: string | Address

Sender address (required)

to: string | Address | Array

Recipient(s) (required)

subject: string

Email subject (required)

text?: string

Plain text body

html?: string

HTML body

attachments?: Attachment[]

File attachments

Methods

send(message: Message)

Send an email message

Returns: Promise<SendResult>

verify()

Verify SMTP connection

Returns: Promise<boolean>

close()

Close the mailer connection

Returns: Promise<void>

use(plugin: Plugin)

Install a plugin

Returns: this

Comparison with Nodemailer

See how we stack up against the competition

Feature	@oxog/mailer	Nodemailer
Dependencies	0	50+
Bundle Size	~50KB	~1MB+
TypeScript	Native	Third-party types
Plugin System	Built-in	Limited
OAuth2	Built-in	Plugin required
Modern API	Promise-based	Callback + Promise