Dual Mailer

A flexible email utility that supports both Mailgun and self-hosted SMTP servers with automatic transport management, rate limiting, and retry capabilities. Perfect for applications that need to send emails through different providers.

Features

• 📧 Supports both Mailgun and self-hosted SMTP
• 🔄 Automatic transport pooling and management
• 🚀 Connection reuse and optimization
• ⏱️ Automatic cleanup of idle connections
• 🛡️ Rate limiting for authenticated SMTP connections
• 🧪 Development mode support
• ♻️ Automatic retries on failed email sends

Installation

npm install @jvp/dual-mailer

Usage

Basic SMTP Setup (e.g., for Mailhog)

import { DualMailer } from '@jvp/dual-mailer';

const mailer = new DualMailer({
  host: 'localhost',
  port: 1025,
  is_dev: true
});

Authenticated SMTP Setup

const mailer = new DualMailer({
  host: 'smtp.your-domain.com',
  port: 587,
  user: 'your-username',
  password: 'your-password',
  is_dev: process.env.NODE_ENV === 'development'
});

Mailgun Setup

const mailer = new DualMailer({
  mailgun_api_key: 'your-mailgun-key',
  mailgun_domain: 'your-domain.com',
  is_dev: process.env.NODE_ENV === 'development'
});

Sending Emails

await mailer.send_mail({
  to: '[email protected]',
  subject: 'Hello World',
  html: {
    title: 'My Email',
    body: '<h1>Hello World</h1>'
  }
});

Enabling Retries

To enable retries for email sends, you can pass a retry option when creating the DualMailer instance:

const mailer = new DualMailer(config, {
  retry: {
    max_retries: 3,
    retry_delay: 1000,
    retryable_errors: ['Temporary Error']
  }
});

The retry option accepts the following properties:

| Option | Type | Default | Description | |--------|------|---------|-------------| | max_retries | number | 3 | The maximum number of retry attempts | | retry_delay | number | 1000 | The initial delay between retries in milliseconds (the delay doubles for each subsequent retry) | | retryable_errors | string[] | [] | A list of error messages that should trigger a retry (if empty, all errors will be retried) |

By default, retries are disabled. To enable them, you need to provide the retry option when creating the DualMailer instance.

Advanced HTML Emails

await mailer.send_mail({
  to: '[email protected]',
  subject: 'Styled Email',
  from: '[email protected]', // Optional
  reply_to: '[email protected]', // Optional
  html: {
    title: 'Styled Email',
    style: `
      .header { color: blue; }
      .content { padding: 20px; }
    `,
    body: `
      <div class="header">
        <h1>Welcome!</h1>
      </div>
      <div class="content">
        <p>This is a styled email.</p>
      </div>
    `
  }
});

Rate Limiting

Dual Mailer supports rate limiting for authenticated SMTP connections. You can configure the rate limiting options when creating the DualMailer instance:

const mailer = new DualMailer(config, {
  rate_limit: {
    max_connections: 5,
    max_messages_per_connection: 200,
    rate_delta: 1000,
    rate_limit: 5
  }
});

The rate_limit option accepts the following properties:

| Option | Type | Default | Description | |--------|------|---------|-------------| | max_connections | number | 5 | The maximum number of concurrent SMTP connections | | max_messages_per_connection | number | 200 | The maximum number of messages per SMTP connection | | rate_delta | number | 1000 | The time window for rate limiting in milliseconds | | rate_limit | number | 5 | The maximum number of messages to send within the rate delta |

Rate limiting is only applied to authenticated SMTP connections. For Mailgun, rate limiting is handled by the Mailgun service.

Cleanup

Make sure to clean up when shutting down your application:

await mailer.destroy();

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | host | string | No* | SMTP host | | port | number | No* | SMTP port | | user | string | No | SMTP username for authentication | | password | string | No** | SMTP password for authentication | | mailgun_api_key | string | No*** | Mailgun API key | | mailgun_domain | string | No*** | Mailgun domain | | noreply_email | string | No | Default from address | | is_dev | boolean | No | Development mode flag |

* Required if using SMTP transport (must provide both host and port)
** Required if SMTP user is provided
*** Required if using Mailgun transport (must provide both api_key and domain)

You must provide either:

• SMTP configuration (host + port), or
• Mailgun configuration (api_key + domain)

Email Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | to | string | Yes | Recipient email address | | subject | string | Yes | Email subject | | text | string | No | Plain text version | | from | string | No | Sender address | | html | object | Yes | HTML email content | | reply_to | string | No | Reply-to address |

HTML Object Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | title | string | Yes | Email title | | style | string | No | CSS styles | | body | string | Yes | HTML content |

Logging Options

The mailer accepts an optional logger in its constructor options. You can provide your own logging implementation or disable logging entirely.

Using Custom Logger

// With Winston
import winston from 'winston';
const logger = winston.createLogger({
  transports: [new winston.transports.Console()]
});

const mailer = new DualMailer(config, {
  logger: (level, message, meta) => logger.log(level, message, meta)
});

// With Pino
import pino from 'pino';
const logger = pino();

const mailer = new DualMailer(config, {
  logger: (level, message, meta) => logger[level]({ msg: message, ...meta })
});

// With custom logging service
const mailer = new DualMailer(config, {
  logger: (level, message, meta) => {
    MyLoggingService.log({
      severity: level,
      message,
      timestamp: new Date(),
      ...meta
    });
  }
});

Disabling Logging

const mailer = new DualMailer(config, { silent: true });

The logger function receives:

• level: 'info' | 'warn' | 'error'
• message: String description of the event
• meta: Object with additional context (timestamps, email details, errors)

Development Mode

When is_dev is true:

• SSL is disabled for SMTP
• Failed emails log their content instead of throwing
• Transport cleanup is disabled

Error Handling

try {
  await mailer.send_mail({
    to: '[email protected]',
    subject: 'Test Email',
    html: {
      title: 'Test',
      body: '<h1>Hello</h1>'
    }
  });
} catch (error) {
  console.error('Failed to send email:', error);
}

Best Practices

1. Always call destroy() when shutting down your application
2. Use environment variables for sensitive configuration
3. Implement proper error handling
4. Set appropriate timeouts for your use case
5. For local development, use tools like Mailhog with simple SMTP configuration
6. Use authenticated SMTP or Mailgun for production environments
7. Configure appropriate rate limiting settings for your use case

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.