@bernierllc/email-batch-sender

Batch email sending with concurrency control, rate limiting, retry strategies, and failure handling. Provides a unified batch API across all email providers, using native provider batch endpoints where available and falling back to sequential sending otherwise.

Installation

npm install @bernierllc/email-batch-sender

Usage

import { createBatchSender } from '@bernierllc/email-batch-sender';

const sender = createBatchSender(emailSenderInstance, {
  concurrency: 5,
  rateLimit: { tokensPerInterval: 10, interval: 1000 },
  retry: { maxRetries: 3, backoffMs: 1000 },
});

const result = await sender.sendBatch([
  { to: '[email protected]', subject: 'Hello', html: '<p>Hi Alice</p>' },
  { to: '[email protected]', subject: 'Hello', html: '<p>Hi Bob</p>' },
]);

console.log(`Sent: ${result.succeeded} / ${result.total}`);

Exports

• BatchSender -- main class for batch operations
• createBatchSender() -- factory function
• TokenBucketRateLimiter -- rate limiter used internally
• BatchSenderError -- custom error class with error codes
• Types: BatchSenderOptions, RateLimitOptions, BatchRetryOptions, BatchResult, BatchEmailResult, BatchProgress, BatchEmailInput

Provider Capability Support

This section documents how batch sending behaves across email providers, based on the canonical CAPABILITY_MATRIX in @bernierllc/email-manager.

Capability Levels by Provider

| Provider | Capability Level | Notes | |----------|-----------------|-------| | SendGrid | provider | Native batch API via personalizations; the provider handles batching server-side | | Mailgun | provider | Native batch send via recipient variables | | Postmark | provider | Native batch API endpoint (/email/batch) | | SES | provider | Native SendBulkEmail API | | SMTP | platform | No native batch support; this package sends emails sequentially over the SMTP connection |

How It Works

• Provider-level (SendGrid, Mailgun, Postmark, SES): The email manager delegates to the provider's native batch endpoint. This package orchestrates the calls, handles rate limiting, and manages retries. The provider may process the batch as a single API call (SendGrid personalizations, Postmark batch endpoint) or as optimized bulk operations (SES SendBulkEmail).

• Platform-level (SMTP): Since SMTP has no native batch support, this package sends emails sequentially over the SMTP connection. Concurrency, rate limiting, and retry logic are all handled at the platform level by this package.

Degradation Behavior

When used with a provider that lacks native batch support (currently only SMTP):

• Strategy: sequential-batch
• Behavior: Emails are sent one at a time over the SMTP connection, respecting the configured concurrency limit and rate limiter
• Performance: Slower than native batch APIs; throughput depends on SMTP server response times and the configured concurrency/rate-limit settings
• Reliability: Full retry support with configurable backoff; individual message failures do not block the rest of the batch

Override Options

The batch send capability is marked overridable: true for all providers with native support, meaning you can force platform-level sequential sending even when a native batch API is available. This can be useful for debugging or when provider batch endpoints have temporary issues.

// Force sequential sending regardless of provider
const sender = createBatchSender(emailSenderInstance, {
  forceSequential: true,
  concurrency: 3,
});

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This package is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.