Package Exports

better-mail
better-mail/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (better-mail) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

BetterMail 📧

A world-class Node.js email sending library with support for multiple providers and template engines. Built with TypeScript for maximum type safety and developer experience.

✨ Features

🚀 Multiple Providers: SMTP, Resend, SendGrid
🎨 Template Engines: React, MJML, Handlebars
🔒 Type Safe: Full TypeScript support
🛡️ Error Handling: Comprehensive error management
📝 Logging: Built-in logging with configurable levels
⚡ Performance: Optimized for high-volume sending
🧪 Well Tested: 100% test coverage
📦 Zero Dependencies: Minimal bundle size

🚀 Quick Start

Installation

npm install better-mail
# or
yarn add better-mail
# or
pnpm add better-mail

Basic Usage

import { createMailer, send } from 'better-mail';

// Configure BetterMail
createMailer({
  provider: 'resend', // or 'smtp', 'sendgrid'
  resend: {
    apiKey: 're_123...',
    from: 'noreply@yourdomain.com'
  },
  templatesPath: './templates'
});

// Send an email
const result = await send({
  to: 'user@example.com',
  template: 'welcome',
  templateEngine: 'react',
  variables: {
    name: 'John Doe',
    company: 'Your Company'
  }
});

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

📚 Documentation

Configuration

BetterMail supports three email providers:

SMTP Configuration

createMailer({
  provider: 'smtp',
  smtp: {
    host: 'smtp.gmail.com',
    port: 587,
    user: 'your-email@gmail.com',
    pass: 'your-app-password',
    from: 'your-email@gmail.com'
  }
});

Resend Configuration

createMailer({
  provider: 'resend',
  resend: {
    apiKey: 're_123...',
    from: 'noreply@yourdomain.com'
  }
});

SendGrid Configuration

createMailer({
  provider: 'sendgrid',
  sendgrid: {
    apiKey: 'SG.123...',
    from: 'noreply@yourdomain.com'
  }
});

Template Engines

React Templates

// templates/welcome.tsx
import * as React from 'react';

export const subject = ({ name }: { name: string }) =>
  `Welcome to BetterMail, ${name}!`;

export const text = ({ name, company }: { name: string; company: string }) =>
  `Hi ${name},\n\nWelcome to ${company}! We're excited to have you on board.`;

export default function Welcome({ name, company }: { name: string; company: string }) {
  return (
    <html>
      <body>
        <h1>Welcome, {name}!</h1>
        <p>Thanks for joining {company}!</p>
      </body>
    </html>
  );
}

MJML Templates

<!-- templates/newsletter.mjml -->
<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text>Hello {{name}}!</mj-text>
        <mj-text>Welcome to {{company}}!</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

Handlebars Templates

<!-- templates/invoice.hbs -->
<h1>Invoice #{{invoiceNumber}}</h1>
<p>Dear {{customerName}},</p>
<p>Thank you for your business!</p>
<p>Amount: ${{amount}}</p>

Advanced Usage

Multiple Recipients

await send({
  to: ['user1@example.com', 'user2@example.com'],
  cc: 'manager@example.com',
  bcc: 'admin@example.com',
  template: 'newsletter',
  variables: { name: 'Subscribers' }
});

Attachments

await send({
  to: 'user@example.com',
  template: 'invoice',
  variables: { invoiceNumber: 'INV-001' },
  attachments: [
    {
      filename: 'invoice.pdf',
      path: './invoices/invoice-001.pdf'
    }
  ]
});

Error Handling

import { BetterMailError, ValidationError, ProviderError } from 'better-mail';

try {
  await send({ /* ... */ });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation failed:', error.message);
  } else if (error instanceof ProviderError) {
    console.log('Provider error:', error.message);
  } else if (error instanceof BetterMailError) {
    console.log('BetterMail error:', error.message);
  }
}

🛠️ Development

Prerequisites

Node.js 18+
npm/yarn/pnpm

Setup

git clone https://github.com/your-username/better-mail.git
cd better-mail
npm install

Scripts

npm run dev:full    # Lint + Format + Test
npm run build       # Build the package
npm run test        # Run tests
npm run lint        # Check code quality
npm run format      # Format code

Testing

npm test                    # Run all tests
npm run test:watch         # Watch mode
npm run test:coverage      # Coverage report

📊 API Reference

`createMailer(config: MailerConfig)`

Configures BetterMail with provider and template settings.

`send(options: SendOptions): Promise<EmailResult>`

Sends an email using the configured provider and template.

Types

interface MailerConfig {
  provider: 'smtp' | 'resend' | 'sendgrid';
  templates?: TemplateConfig;
  logging?: LoggingConfig;
  smtp?: SMTPConfig;
  resend?: ResendConfig;
  sendgrid?: SendGridConfig;
}

interface SendOptions {
  to: string | string[];
  template: string;
  templateEngine?: 'react' | 'mjml' | 'handlebars';
  variables: Record<string, unknown>;
  cc?: string | string[];
  bcc?: string | string[];
  attachments?: EmailAttachment[];
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Resend for their excellent email API
SendGrid for their reliable email service
React Email for their amazing React email components
MJML for their responsive email framework

📞 Support

📧 Email: support@bettermail.dev
💬 Discord: Join our community
📖 Documentation: docs.bettermail.dev
🐛 Issues: GitHub Issues

Made with ❤️ by the BetterMail team