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 — exportToCsv converts an array of SuppressionEntry objects into a properly-formatted CSV string suitable for downloa…
json-exporter — exportToJson and importFromJson provide full-store persistence for SuppressionStore instances. 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)

- [csv-importer](./src/core/importer/csv-importer.md) — _(no submodules)_- [store](./src/core/store/suppression-store.md) — _(no submodules)_- [suppression-store](./src/core/store/suppression-store.md) — _(no submodules)_- [errors](./src/errors/suppression-error.md) — _(no submodules)_- [suppression-error](./src/errors/suppression-error.md) — _(no submodules)_- [utils](./src/utils/email-utils.md) — _(no submodules)_- [email-utils](./src/utils/email-utils.md) — _(no submodules)_- [csv-importer](./src/core/importer/csv-importer.md) — _(no submodules)_- [store](./src/core/store/suppression-store.md) — _(no submodules)_- [suppression-store](./src/core/store/suppression-store.md) — _(no submodules)_- [errors](./src/errors/suppression-error.md) — _(no submodules)_- [suppression-error](./src/errors/suppression-error.md) — _(no submodules)_- [utils](./src/utils/email-utils.md) — _(no submodules)_- [email-utils](./src/utils/email-utils.md) — _(no submodules)_- [csv-importer](./src/core/importer/csv-importer.md) — _(no submodules)_- [store](./src/core/store/suppression-store.md) — _(no submodules)_- [suppression-store](./src/core/store/suppression-store.md) — _(no submodules)_- [errors](./src/errors/suppression-error.md) — _(no submodules)_- [suppression-error](./src/errors/suppression-error.md) — _(no submodules)_- [utils](./src/utils/email-utils.md) — _(no submodules)_- [email-utils](./src/utils/email-utils.md) — _(no submodules)_- [csv-importer](./src/core/importer/csv-importer.md) — _(no submodules)_- [store](./src/core/store/suppression-store.md) — _(no submodules)_ - [suppression-store](./src/core/store/suppression-store.md) — _(no submodules)_- [errors](./src/errors/suppression-error.md) — _(no submodules)_ - [suppression-error](./src/errors/suppression-error.md) — _(no submodules)_- [utils](./src/utils/email-utils.md) — _(no submodules)_ - [email-utils](./src/utils/email-utils.md) — _(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