@bernierllc/email-subscription

Email subscription management service with list management, unsubscribe handling, preference centers, suppression list support, and provider synchronization. Works independently of the underlying email provider.

Installation

npm install @bernierllc/email-subscription

Usage

import {
  SubscriptionListManager,
  UnsubscribeManager,
  SuppressionManager,
  PreferenceCenterManager,
  InMemorySubscriptionStore,
} from '@bernierllc/email-subscription';

const store = new InMemorySubscriptionStore();
const listManager = new SubscriptionListManager(store);

// Create a mailing list
const list = await listManager.createList({
  name: 'Weekly Newsletter',
  description: 'Our weekly product updates',
});

// Add subscribers
await listManager.addSubscriber(list.id, {
  email: '[email protected]',
  name: 'Jane Doe',
});

// Manage unsubscribes
const unsubscribeManager = new UnsubscribeManager(store);
await unsubscribeManager.unsubscribe('[email protected]', list.id);

// Manage suppression lists
const suppressionManager = new SuppressionManager(store);
await suppressionManager.addSuppression({
  email: '[email protected]',
  reason: 'hard_bounce',
});

// Preference center
const preferenceManager = new PreferenceCenterManager(store);
const preferences = await preferenceManager.getPreferences('[email protected]');

Exports

• SubscriptionListManager -- manage subscriber lists (create, add/remove subscribers, bulk operations)
• UnsubscribeManager -- handle opt-out requests and one-click unsubscribe
• SuppressionManager -- maintain suppression lists (bounces, complaints)
• PreferenceCenterManager -- subscriber preference centers and URL generation
• ProviderSyncManager -- synchronize subscription data with provider-level systems
• InMemorySubscriptionStore -- in-memory store for development and testing
• SubscriptionError -- custom error class with error codes
• Types: SubscriberList, Subscriber, Suppression, SubscriptionPreference, ProviderSyncAdapter, and more

Provider Capability Support

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

Capability Levels by Provider

| Provider | Capability Level | Notes | |----------|-----------------|-------| | SendGrid | enhanced | Platform subscription management enhanced with SendGrid Contacts API for list sync | | Mailgun | enhanced | Platform subscription management enhanced with Mailgun mailing list sync | | Postmark | platform | Fully platform-managed; Postmark has no native list management | | SES | platform | Fully platform-managed; SES has no native list management | | SMTP | platform | Fully platform-managed; SMTP has no native capabilities |

How It Works

• Enhanced (SendGrid, Mailgun): This package provides the full subscription management layer (lists, preferences, unsubscribe handling, suppression). Additionally, the ProviderSyncManager synchronizes subscriber data with the provider's native contact/list APIs. Unsubscribes and suppressions flow both directions -- provider-side events (e.g., a bounce processed by SendGrid) are pulled into the platform, and platform-side unsubscribes are pushed to the provider.

• Platform-level (Postmark, SES, SMTP): This package handles all subscription management entirely at the platform level. There is no provider-side list to synchronize with. The platform maintains its own subscriber store, preference center, and suppression lists.

Degradation Behavior

There is no degradation in the traditional sense. This package always provides full subscription management functionality regardless of provider. The only difference is whether provider sync is available:

• With provider sync (SendGrid, Mailgun): Two-way synchronization keeps platform and provider lists in alignment
• Without provider sync (Postmark, SES, SMTP): The platform is the single source of truth; no sync is needed or attempted
• Strategy: platform-managed for providers without native list management

Override Options

The subscription management capability is marked overridable: true at the platform level, allowing you to replace or extend the built-in subscription store with a custom implementation:

import { SubscriptionStore } from '@bernierllc/email-subscription';

class PostgresSubscriptionStore implements SubscriptionStore {
  // Custom implementation backed by PostgreSQL
}

const store = new PostgresSubscriptionStore();
const listManager = new SubscriptionListManager(store);

Provider Independence

This package is designed to work identically across all providers. You can switch email providers without losing subscription data, preference settings, or suppression history. The ProviderSyncManager is an optional enhancement -- the core subscription system functions without it.

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.