Sperren

Der Sperrspiegel: Abmeldung, Hard Bounce und Spam-Beschwerde entstehen bei Postmark und werden dort je Nachricht durchgesetzt. Hier holt das Kundensystem die Änderungen ab, prüft Adressen und hebt Sperren nach neuem Double-Opt-in auf. Die Einwilligung selbst liegt im CRM des Kunden — „darf E-Mails empfangen“ ist die Ableitung aus beidem.

Verfügbar

GET

/v1/suppressions

Liefert alle Sperränderungen des Kunden seit since, chronologisch: gesetzte Sperren (active=true) und aufgehobene (active=false). Gedacht für einen Cron im Kundensystem, der sein Sperrfeld nachzieht. Adressen stehen im Klartext, weil das CRM sie seinem Kontakt zuordnen muss. Scope reporting.

Query-Parameter

Name	Typ	Pflicht	Beschreibung
since	string (ISO 8601)	erforderlich	Änderungen ab diesem Zeitpunkt (inklusive). Beim nächsten Aufruf changed_at des letzten Eintrags übergeben. `z. B. 2026-09-03T06:00:00Z`
stream	enum	optional	newsletter (Standard) oder transactional. Sperren gelten je Stream. `z. B. newsletter`
limit	integer	optional	Einträge pro Seite, max. 500. `z. B. 500`
after	string	optional	Cursor aus paging.after der vorigen Seite. `z. B. MjAyNi0…`

Request · Next.js

const res = await fetch(`https://api.newsletterkit.ventureon.io/v1/suppressions?since=2026-09-03T06%3A00%3A00Z&stream=newsletter&limit=500&after=MjAyNi0%E2%80%A6`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.NEWSLETTERKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": [
    { "email": "max@example.com",  "stream": "newsletter", "active": true,  "reason": "unsubscribe", "reactivatable": true, "changed_at": "2026-09-03T07:12:41Z" },
    { "email": "lena@example.com", "stream": "newsletter", "active": false, "reason": "hard_bounce", "reactivatable": true, "changed_at": "2026-09-03T07:40:03Z" }
  ],
  "paging": { "after": null, "has_next": false },
  "request_id": "…"
}

reason: unsubscribe | hard_bounce | spam_complaint. reactivatable ist bei spam_complaint immer false. Ein Eintrag mit active=false ist eine aufgehobene Sperre — auch die muss ins CRM, sonst bleibt der Kontakt dort gesperrt. Der Spiegel ist so aktuell wie der letzte Postmark-Webhook, in der Regel Sekunden.

POST

/v1/suppressions/lookup

Prüft bis zu 500 Adressen auf eine aktive Sperre — für den Einzelfall („warum bekommt Max nichts?“), nicht als Ersatz für den Abgleich. POST statt GET, damit Adressen nicht in URLs und Server-Logs landen. Scope reporting.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
emails	string[]	erforderlich	Zu prüfende Adressen, max. 500. `z. B. ["max@example.com"]`
stream	enum	optional	newsletter (Standard) oder transactional. `z. B. newsletter`

Request · Next.js

const res = await fetch(`https://api.newsletterkit.ventureon.io/v1/suppressions/lookup`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEWSLETTERKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      emails: ["max@example.com"],
      stream: "newsletter",
    }),
});
const data = await res.json();

Response 200

{
  "data": [
    { "email": "max@example.com",  "suppressed": true,  "reason": "unsubscribe", "reactivatable": true, "since": "2026-09-03T07:12:41Z" },
    { "email": "lena@example.com", "suppressed": false }
  ],
  "request_id": "…"
}

Antwortet aus dem Spiegel, nicht live von Postmark.

POST

/v1/suppressions/reactivate

Hebt die Sperre einer Adresse bei Postmark auf. Nur nach einem neuen, bestätigten Double-Opt-in aufrufen — nie, weil jemand im CRM einen Haken gesetzt hat. Bei Spam-Beschwerde verweigert Postmark das Aufheben; die Antwort ist dann 409 conflict mit details.reason = spam_complaint. Scope full.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
email	string (E-Mail)	erforderlich	Adresse, deren Sperre aufgehoben werden soll. `z. B. max@example.com`
stream	enum	optional	newsletter (Standard) oder transactional. `z. B. newsletter`

Request · Next.js

const res = await fetch(`https://api.newsletterkit.ventureon.io/v1/suppressions/reactivate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEWSLETTERKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      email: "max@example.com",
      stream: "newsletter",
    }),
});
const data = await res.json();

Response 200

{
  "data": { "email": "max@example.com", "stream": "newsletter", "reactivated": true },
  "request_id": "…"
}

Gefahrlos wiederholbar: Eine bei Postmark nicht gesperrte Adresse liefert reactivated: true ohne weiteren Effekt. Die Aufhebung erscheint anschließend als Eintrag mit active=false in GET /v1/suppressions.