better-mail

v1.0.2

Published

3 months ago

A world-class Node.js email sending library with support for multiple providers and template engines

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: '[email protected]'
  },
  templatesPath: './templates'
});

// Send an email
const result = await send({
  to: '[email protected]',
  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: '[email protected]',
    pass: 'your-app-password',
    from: '[email protected]'
  }
});

Resend Configuration

createMailer({
  provider: 'resend',
  resend: {
    apiKey: 're_123...',
    from: '[email protected]'
  }
});

SendGrid Configuration

createMailer({
  provider: 'sendgrid',
  sendgrid: {
    apiKey: 'SG.123...',
    from: '[email protected]'
  }
});

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: ['[email protected]', '[email protected]'],
  cc: '[email protected]',
  bcc: '[email protected]',
  template: 'newsletter',
  variables: { name: 'Subscribers' }
});

Attachments

await send({
  to: '[email protected]',
  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: [email protected]
💬 Discord: Join our community
📖 Documentation: docs.bettermail.dev
🐛 Issues: GitHub Issues