Hi Alice
' },\n { to: 'bob@example.com', subject: 'Hello', html: 'Hi Bob
' },\n]);\n\nconsole.log(`Sent: ${result.succeeded} / ${result.total}`);\n```\n\n## Exports\n\n- `BatchSender` -- main class for batch operations\n- `createBatchSender()` -- factory function\n- `TokenBucketRateLimiter` -- rate limiter used internally\n- `BatchSenderError` -- custom error class with error codes\n- Types: `BatchSenderOptions`, `RateLimitOptions`, `BatchRetryOptions`, `BatchResult`, `BatchEmailResult`, `BatchProgress`, `BatchEmailInput`\n\n## Provider Capability Support\n\nThis section documents how batch sending behaves across email providers, based on the canonical `CAPABILITY_MATRIX` in `@bernierllc/email-manager`.\n\n### Capability Levels by Provider\n\n| Provider | Capability Level | Notes |\n|----------|-----------------|-------|\n| SendGrid | **provider** | Native batch API via personalizations; the provider handles batching server-side |\n| Mailgun | **provider** | Native batch send via recipient variables |\n| Postmark | **provider** | Native batch API endpoint (`/email/batch`) |\n| SES | **provider** | Native `SendBulkEmail` API |\n| SMTP | **platform** | No native batch support; this package sends emails sequentially over the SMTP connection |\n\n### How It Works\n\n- **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`).\n\n- **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.\n\n### Degradation Behavior\n\nWhen used with a provider that lacks native batch support (currently only SMTP):\n\n- **Strategy**: `sequential-batch`\n- **Behavior**: Emails are sent one at a time over the SMTP connection, respecting the configured concurrency limit and rate limiter\n- **Performance**: Slower than native batch APIs; throughput depends on SMTP server response times and the configured concurrency/rate-limit settings\n- **Reliability**: Full retry support with configurable backoff; individual message failures do not block the rest of the batch\n\n### Override Options\n\nThe 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.\n\n```typescript\n// Force sequential sending regardless of provider\nconst sender = createBatchSender(emailSenderInstance, {\n forceSequential: true,\n concurrency: 3,\n});\n```\n\n## License\n\nCopyright (c) 2025 Bernier LLC. All rights reserved.\n\nThis 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.\n","readmeFilename":"README.md"}