Newsletter content...
',\n },\n listId, // Subscriber list ID\n 'alice@example.com', // Recipient for token generation\n true, // Enable one-click unsubscribe (RFC 8058)\n);\n```\n\n> See [`examples/subscription-management.ts`](examples/subscription-management.ts) for the full lifecycle.\n\n---\n\n### Suppression\n\nCheck if an email address is suppressed before sending. Emails become suppressed when a subscriber unsubscribes or when bounces/complaints are processed.\n\n```typescript\n// Check global suppression\nconst isSuppressed = await manager.isSuppressed('alice@example.com');\n\n// Check list-specific suppression\nconst isListSuppressed = await manager.isSuppressed('alice@example.com', listId);\n\nif (isSuppressed) {\n console.log('Skipping send - email is suppressed');\n}\n```\n\n---\n\n### Custom Subscription Store\n\nBy default, the manager uses an in-memory subscription store. For production, replace it with a database-backed implementation:\n\n```typescript\nimport { SubscriptionStore } from '@bernierllc/email-manager';\n\nclass DatabaseSubscriptionStore implements SubscriptionStore {\n // Implement all SubscriptionStore methods using your database\n // (createList, getList, addSubscriber, etc.)\n}\n\nconst store = new DatabaseSubscriptionStore();\nmanager.setSubscriptionStore(store);\n```\n\n---\n\n### Custom Headers\n\nAdd custom email headers for threading, read receipts, and other purposes by including them in the `metadata.headers` field.\n\n#### Email Threading\n\n```typescript\nconst result = await manager.sendEmail({\n to: 'colleague@example.com',\n subject: 'Re: Project Discussion',\n html: 'I agree with the proposed approach.
',\n metadata: {\n headers: {\n 'In-Reply-To': 'Your digest...
',\n metadata: { headers },\n});\n```\n\n#### MDN (Read Receipt) Request\n\n```typescript\nconst result = await manager.sendEmail({\n to: 'recipient@example.com',\n subject: 'Contract for Review',\n html: 'Please confirm receipt of the attached contract.
',\n metadata: {\n headers: {\n 'Disposition-Notification-To': 'sender@example.com',\n },\n },\n});\n```\n\n> See [`examples/attachments-and-headers.ts`](examples/attachments-and-headers.ts) for complete examples.\n\n---\n\n### Attachments\n\nSend emails with file attachments, inline images, or both.\n\n#### File Attachment\n\n```typescript\nconst result = await manager.sendEmail({\n to: 'recipient@example.com',\n subject: 'Report Attached',\n html: 'Please find the report attached.
',\n attachments: [\n {\n filename: 'report.pdf',\n content: fs.readFileSync('/path/to/report.pdf'),\n contentType: 'application/pdf',\n },\n ],\n});\n```\n\n#### String Content Attachment\n\n```typescript\nconst csvData = 'Name,Email\\nAlice,alice@example.com\\nBob,bob@example.com\\n';\n\nconst result = await manager.sendEmail({\n to: 'manager@example.com',\n subject: 'User Export',\n html: 'User export attached.
',\n attachments: [\n {\n filename: 'users.csv',\n content: csvData, // String content is also supported\n contentType: 'text/csv',\n },\n ],\n});\n```\n\n#### Inline / Embedded Image\n\nReference inline images using a Content-ID (CID):\n\n```typescript\nconst result = await manager.sendEmail({\n to: 'customer@example.com',\n subject: 'Order Confirmation',\n html: `\nOrder Confirmed!
\n `,\n attachments: [\n {\n filename: 'logo.png',\n content: fs.readFileSync('/path/to/logo.png'),\n contentType: 'image/png',\n contentDisposition: 'inline',\n cid: 'company-logo', // Matches src=\"cid:company-logo\" in HTML\n },\n ],\n});\n```\n\n#### Multiple Attachments\n\n```typescript\nconst result = await manager.sendEmail({\n to: 'team@example.com',\n subject: 'Brand Kit Assets',\n html: 'Attached are the brand assets.
',\n attachments: [\n {\n filename: 'guidelines.pdf',\n content: fs.readFileSync('/path/to/guidelines.pdf'),\n contentType: 'application/pdf',\n },\n {\n filename: 'logo.png',\n content: fs.readFileSync('/path/to/logo.png'),\n contentType: 'image/png',\n },\n {\n filename: 'palette.json',\n content: JSON.stringify({ primary: '#0066CC' }, null, 2),\n contentType: 'application/json',\n },\n ],\n});\n```\n\n> See [`examples/attachments-and-headers.ts`](examples/attachments-and-headers.ts) for complete examples.\n\n---\n\n## Capability Matrix & Smart Routing\n\nThe email manager includes a full capability matrix that maps every feature to every provider, enabling smart routing decisions and graceful degradation.\n\n### Capability Matrix\n\nEach feature is classified per provider with one of four source types:\n\n| Source | Meaning |\n|--------|---------|\n| `provider` | Natively supported by the email provider's API |\n| `platform` | Implemented by the platform (polyfilled locally) |\n| `enhanced` | Built on top of provider primitives with added value |\n| `unsupported` | Not available for this provider |\n\n#### Provider Feature Support\n\n| Feature | SendGrid | Mailgun | Postmark | SES | SMTP |\n|---------|----------|---------|----------|-----|------|\n| sendEmail | provider | provider | provider | provider | provider |\n| batchSend | provider | provider | provider | provider | platform |\n| providerTemplates | provider | provider | provider | provider | unsupported |\n| localTemplates | platform | platform | platform | platform | platform |\n| calendarInvites | platform | platform | platform | platform | platform |\n| calendarEventMgmt | platform | platform | platform | platform | platform |\n| webhooksReceive | provider | provider | provider | provider | unsupported |\n| webhookNormalization | enhanced | enhanced | enhanced | enhanced | unsupported |\n| deliveryTracking | provider | provider | provider | provider | unsupported |\n| inboundEmailParsing | enhanced | enhanced | enhanced | enhanced | unsupported |\n| subscriptionMgmt | enhanced | enhanced | platform | platform | platform |\n| suppressionLists | provider | provider | provider | provider | platform |\n| unsubscribeUrlGeneration | platform | platform | platform | platform | platform |\n| scheduledSend | provider | provider | platform | platform | platform |\n| openClickTracking | provider | provider | provider* | unsupported | unsupported |\n| emailContentParsing | platform | platform | platform | platform | platform |\n| emailHeaderMgmt | platform | platform | platform | platform | platform |\n| attachments | provider | provider | provider | provider | provider |\n| advancedAttachmentProcessing | platform | platform | platform | platform | platform |\n| dkimSpf | provider | provider | provider | provider | unsupported |\n| linkBranding | provider | provider | unsupported | unsupported | unsupported |\n| retryResilience | platform | platform | platform | platform | platform |\n| multiProviderFailover | platform | platform | platform | platform | platform |\n\n*Postmark supports open tracking only; click tracking is not available.\n\nNotable provider-specific limitations:\n- **SendGrid** `scheduledSend`: 72-hour maximum scheduling window\n- **Mailgun** `scheduledSend`: 3-day maximum scheduling window\n- **SES** `webhooksReceive` / `deliveryTracking`: Requires SNS topic configuration\n\n### Routing Configuration\n\nCapability-aware routing is opt-in. Enable it by adding a `routing` section to your config:\n\n```typescript\nimport { EmailManager, EmailManagerConfig } from '@bernierllc/email-manager';\n\nconst config: EmailManagerConfig = {\n providers: [\n { id: 'sg', name: 'SendGrid', type: 'sendgrid', config: { apiKey: '...' }, isActive: true, priority: 1 },\n { id: 'mg', name: 'Mailgun', type: 'mailgun', config: { apiKey: '...', domain: '...' }, isActive: true, priority: 2 },\n ],\n routing: {\n strategy: 'primary-failover',\n featureOverrides: {\n // Always use platform implementation for local templates\n localTemplates: { behavior: 'platform-always' },\n // Throw an error if no native provider supports the feature\n openClickTracking: { behavior: 'error' },\n },\n },\n degradation: {\n logLevel: 'warn',\n includeDocLinks: true,\n docsBaseUrl: 'https://docs.example.com/email',\n },\n};\n\nconst manager = new EmailManager(config);\n```\n\n#### Feature Override Behaviors\n\n| Behavior | Description |\n|----------|-------------|\n| `native-first` | (Default) Prefer providers with native or enhanced support; fall back to platform if none found |\n| `platform-always` | Always use the platform implementation, even if the provider supports it natively |\n| `error` | Throw `FeatureUnsupportedError` if no provider has native or enhanced support |\n\n### Degradation Behavior\n\nWhen a feature is routed to a provider via platform polyfill (not native), the system records degradation information:\n\n- **`platform` source features** (e.g., SMTP `batchSend`): Emails are sent sequentially rather than in a true batch. The `SendResult.routing` field indicates `degraded: true` with a `degradationReason`.\n- **`unsupported` features** (e.g., SMTP `webhooksReceive`): The router skips the provider entirely and tries the next in priority order. If no provider supports the feature, a `FeatureUnsupportedError` is thrown.\n- **Degradation logging**: Controlled by `degradation.logLevel` (`'silent'` | `'info'` | `'warn'` | `'error'`). When `includeDocLinks` is `true`, log messages include links to degradation documentation.\n\n### Redis Resolver Setup\n\nBy default, the capability matrix is resolved from an in-memory snapshot. For shared or dynamic capability data across multiple instances, use the Redis-backed resolver:\n\n```bash\n# Set the environment variable to enable Redis resolver auto-detection\nexport EMAIL_MANAGER_REDIS_URL=\"redis://localhost:6379\"\n```\n\nThe factory (`createCapabilityResolver`) automatically detects the environment variable and creates a `SafeCapabilityResolver` that wraps a Redis resolver with an in-memory fallback. If `ioredis` is not installed or Redis is unavailable, it falls back to the in-memory resolver silently.\n\n#### Redis Resolver Options\n\n```typescript\nimport { createCapabilityResolver } from '@bernierllc/email-manager';\n\nconst resolver = await createCapabilityResolver({\n namespace: 'myapp:capabilities', // Redis key namespace (default: 'email-manager:capabilities')\n ttl: 3600, // Cache TTL in seconds (default: varies by implementation)\n});\n```\n\nYou can also provide your own resolver implementation:\n\n```typescript\nconst config: EmailManagerConfig = {\n providers: [/* ... */],\n routing: {\n strategy: 'primary-failover',\n capabilityResolver: myCustomResolver, // Must implement CapabilityResolver interface\n },\n};\n```\n\n### RoutingMetadata in Responses\n\nWhen routing is active, `SendResult` includes a `routing` field:\n\n```typescript\nconst result = await manager.sendEmail(emailData);\n\nif (result.routing) {\n console.log('Provider used:', result.routing.provider);\n console.log('Feature:', result.routing.feature);\n console.log('Source:', result.routing.source); // 'provider' | 'platform' | 'enhanced' | 'unsupported'\n console.log('Degraded:', result.routing.degraded); // true if platform polyfill was used\n console.log('Reason:', result.routing.degradationReason);\n console.log('Tried:', result.routing.attemptedProviders); // providers checked before selecting\n}\n```\n\nThe `RoutingMetadata` interface:\n\n```typescript\ninterface RoutingMetadata {\n provider: string;\n feature: string;\n source: 'provider' | 'platform' | 'enhanced' | 'unsupported';\n degraded: boolean;\n degradationReason?: string;\n attemptedProviders?: string[];\n}\n```\n\n### Migration Guide from v0.4.x\n\nThe capability matrix and routing system is fully backward compatible. Existing code continues to work without changes:\n\n- **No routing config**: When `routing` is omitted from the config, the manager uses the same provider selection logic as before (priority-based failover).\n- **No degradation config**: When `degradation` is omitted, degradation events are not logged.\n- **Opt-in**: To enable capability-aware routing, add a `routing` section to your config. The `RoutingMetadata` field on `SendResult` only appears when routing is active.\n- **No new required dependencies**: The Redis resolver is optional and only activated when `EMAIL_MANAGER_REDIS_URL` is set and `ioredis` is installed.\n\n---\n\n## Re-exported Types\n\nFor convenience, the email-manager re-exports types and utilities from its sub-packages so consumers do not need direct dependencies:\n\n| Package | Re-exported Items |\n|---------|-------------------|\n| `@bernierllc/email-calendar` | `CalendarEvent`, `CalendarAttendee`, `CalendarMethod`, `createCalendarInvite`, `createCalendarCancel`, `toCalendarAttachment` |\n| `@bernierllc/email-batch-sender` | `BatchSenderOptions`, `BatchResult`, `BatchEmailInput`, `BatchProgress`, `BatchSender`, `createBatchSender` |\n| `@bernierllc/email-subscription` | `SubscriberList`, `Subscriber`, `SubscriptionStore`, `AddSubscriberInput`, `CreateListOptions`, `BulkAddResult`, `UnsubscribeManager`, `SuppressionManager`, `InMemorySubscriptionStore` |\n| `@bernierllc/email-headers` | `EmailHeaders`, `ThreadingHeaders`, `ListUnsubscribeHeaders`, `createListUnsubscribeHeaders` |\n| `@bernierllc/email-attachments` | `AttachmentInput`, `AttachmentLimits`, `AttachmentValidationResult` |\n\n## License\n\nCopyright (c) 2025 Bernier LLC. All rights reserved.\n\n## See Also\n\n- [@bernierllc/email-sender](../email-sender) - Core email sending functionality\n- [@bernierllc/template-engine](../template-engine) - Template rendering engine\n- [@bernierllc/magic-link](../magic-link) - Secure token generation","readmeFilename":"README.md"}