Suppression list

Each organisation keeps a list of addresses that must not receive mail: opt-outs, deceased recipients, complaints. An entry holds back all mail, or only the advertising categories in its categories. Entries are normalised and matched on the delivery point (postal code, house number and addition), so spelling and spacing differences still match.

The list is applied twice: when an item is created (it becomes SUPPRESSED, never printed or billed) and again at the run cutoff, so an entry added after creation still takes effect. An item's category is its own advertisingCategory when given at creation, otherwise the one of its Postflow or Postbatch; an item without a category is held back only by entries for all mail.

await client.suppressions.add({
  body: [
    { addressLine1: 'Dam 1', postalCode: '1012 JS', city: 'Amsterdam', reason: 'opt_out' },
    { addressLine1: 'Dam 2', postalCode: '1012 JS', city: 'Amsterdam', categories: ['newsletter'] },
  ],
  idempotencyKey: 'optout-2026-10-11',
});
const page = await client.suppressions.list({
  query: { filter: { search: { contains: '1012' } } },
});
await client.suppressions.remove(entry.id);

Bulk lists come in through a CSV upload: create an upload session of kind csv, upload the file, complete the session and call suppressions.importCsv with the upload id. Columns are mapped to the recipient fields by their header names (Dutch and English synonyms are recognised) or through an explicit mapping; rows that cannot be identified are reported by line. Imports are capped at 50,000 rows.

Reasons and advertising categories are lists of the organisation: GET /v1/suppression-reasons starts with opt_out, deceased, complaint and other; GET /v1/advertising-categories returns the PostBuddy categories followed by the organisation's own. Both take POST to add an entry (the key is derived from the label), PATCH /{key} to rename, reorder or archive it and DELETE /{key}, which is refused with still_referenced while the entry is in use. Adding an address that is already listed widens its categories; PATCH /v1/suppressions/{id} changes the reason, the categories or the note. A CSV import reads an optional categories column (keys or labels separated by commas, semicolons or bars).