6.5 KiB
6.5 KiB
@suaveplan/suppression - Email suppression list management: in-memory store, bulk import/export (CSV/JSON), domain-level suppression, and OTel instrumentation
Summary
Email suppression list management for Suaveplan. Stores and checks email addresses that should not receive outgoing mail — unsubscribes, hard/soft bounces, complaints, manual suppressions, and invalid addresses. Supports domain-level blocking, bulk CSV/JSON import and export, OTel instrumentation, and full serialisation round-trips.
Documentation tree
- csv-exporter —
exportToCsvconverts an array ofSuppressionEntryobjects into a properly-formatted CSV string suitable for downloa… - json-exporter —
exportToJsonandimportFromJsonprovide full-store persistence forSuppressionStoreinstances. They wrap the stor… - importer — (no submodules)
- csv-importer — (no submodules)
- store — (no submodules)
- suppression-store — (no submodules)
- errors — (no submodules)
- suppression-error — (no submodules)
- utils — (no submodules)
- email-utils — (no submodules)
Packages
| Module | Description |
|---|---|
src/core/store/suppression-store.ts |
In-memory suppression store with CRUD, domain blocking, stats, and serialisation |
src/core/importer/csv-importer.ts |
Bulk import from CSV with header-driven column mapping |
src/core/exporter/csv-exporter.ts |
Export entries to RFC 4180-compliant CSV |
src/core/exporter/json-exporter.ts |
Full-store JSON serialisation and deserialisation |
src/utils/email-utils.ts |
Email normalisation, domain extraction, and validation helpers |
src/errors/suppression-error.ts |
Typed error class with stable code registry |
Quick Start
import { createSuppressionStore } from "@suaveplan/suppression/store";
import { importFromCsv } from "@suaveplan/suppression/importer";
import { exportToCsv, exportToJson } from "@suaveplan/suppression/exporter";
// Create a store
const store = createSuppressionStore({ domainSuppressionEnabled: true });
// Add individual entries
store.add("user@example.com", "unsubscribe", "newsletter-june");
store.addDomain("spam.example", "bounce-hard");
// Check before sending
if (!store.isSuppressed(recipient)) {
await sendEmail(recipient);
}
// Bulk import from ESP export
const entries = importFromCsv(csvString);
store.fromJSON({ entries, domains: [] });
// Persist
const json = exportToJson(store);
await db.set("suppression_snapshot", json);
Installation
bun add @suaveplan/suppression
Suppression Reasons
| Reason | Description |
|---|---|
unsubscribe |
User explicitly opted out |
bounce-hard |
Permanent delivery failure |
bounce-soft |
Temporary delivery failure |
complaint |
Spam complaint recorded |
manual |
Manually added by operator |
invalid |
Structurally invalid address |
License
MIT