# NewsletterKit API

> Interne Middleware zwischen Kundenplattformen und Postmark. Verschickt wird
> immer ein Template — im Dashboard gebaut oder aus dem Builder des Portals
> gespeichert. Transaktional einzeln und synchron, Newsletter als Versandjob.
> Jede Mail hat eine ID; Auswertung und Sperren liegen bei NewsletterKit, das
> Portal fragt ab. Die Einwilligung liegt im CRM des Kunden. Der API-Key
> bestimmt den Kunden; der Postmark-Server-Token verlässt nie den Server.

Base URL: https://api.newsletterkit.ventureon.io/v1
Docs: https://docs.newsletterkit.ventureon.io
Auth: Authorization: Bearer <API-Key> (Scopes: full | reporting)
Version: v1

## Standard-Header
- Authorization (immer): Bearer <API-Key>. Bestimmt Kunde + Plan. Niemals clientseitig im Browser verwenden.
- Content-Type (bei JSON-Body): application/json — für alle POST/PUT-Requests mit JSON-Body.
- Idempotency-Key (empfohlen (POST/PUT)): Eindeutige UUID pro Erstellung/Versand. Wiederholte Requests mit gleichem Key erzeugen keine Dubletten (kein doppelter Versand).
- NewsletterKit-Version (optional): Pinnt die API-Version (z. B. v1). Ohne Header gilt die Account-Default-Version.
- X-Request-Id (optional): Eigene Korrelations-ID; wird in Logs & Support-Anfragen zurückgegeben.

## Fehlercodes
- 400 bad_request: Request-Format ungültig (JSON-Syntax, fehlende Felder).
- 401 unauthorized: API-Key fehlt, ungültig oder widerrufen.
- 403 forbidden: Key-Scope deckt diese Operation nicht (z. B. reporting-only bei schreibenden Calls).
- 404 not_found: Ressource existiert nicht oder gehört nicht zum Kunden (falsche ID).
- 409 conflict: Idempotenz-Konflikt oder Statuskollision.
- 422 validation_error: Felder vorhanden, aber inhaltlich ungültig (siehe details[]).
- 429 rate_limited: Zu viele Requests → Retry-After beachten.
- 429 quota_exceeded: Monatslimit oder Höchstzahl je Job erreicht — eine Sicherung des Kunden, im Admin anhebbar.
- 5xx internal_error: Fehler bei uns oder bei Postmark. Mit Backoff erneut versuchen.

## Integrationspfad — die fünf Abläufe

### Transaktionale Mail
Ein fertiges Template des Kunden, ein Empfänger, sofort. Die Antwort trägt unsere Mail-ID — sie gehört an die Bestellung oder den Nutzer, damit das Portal später den Status nachfragen kann.
1. GET /v1/templates — Template der Art transaktional wählen, params lesen (name, label, type, required, example).
2. POST /v1/templates/{id}/send mit to und params; Idempotency-Key gegen doppelten Versand bei Retries.
3. Bei Bedarf GET /v1/messages/{id}: zugestellt oder gebounct, mit Grund.

```ts
// Server Action / Route Handler
import { newsletterkit } from "@/lib/newsletterkit";

const { data } = await newsletterkit<{ data: { message_id: string; status: string } }>(
  "/templates/00000000-0000-4000-8000-0000000000f3/send",
  {
    method: "POST",
    headers: { "Idempotency-Key": crypto.randomUUID() },
    body: JSON.stringify({
      to: "mira@example.com",
      params: {
        titel: "Dein Zugang zum Dashboard",
        name: "Mira",
        text: "Du bist als Redaktion eingetragen.",
        link: "https://kunde.de/einladung?token=…",
        screenshot: "https://kunde.de/bilder/dashboard.jpg",
      },
    }),
  },
);
// data.status: accepted | suppressed | invalid — data.message_id am Nutzer speichern
await db.user.update({ where: { id: userId }, data: { inviteMailId: data.message_id } });
```

### Newsletter aus fertigem Template
Das Portal zeigt die Newsletter-Templates des Kunden, der Nutzer füllt die Parameter (eine KI kann sie aus Bezeichnung und Beispiel vorausfüllen), wählt Empfänger aus dem CRM und schickt ab. Verschickt wird als Job.
1. GET /v1/templates — Art newsletter, params lesen.
2. POST /v1/render/preview zum Prüfen — oder GET /v1/templates/{id} und die Blöcke mit den Werten rendern lassen.
3. POST /v1/send-jobs mit template_id, params, optional scheduled_at.
4. POST /v1/send-jobs/{id}/recipients — Kontakte aus dem CRM, gefiltert nach Einwilligung UND keiner Sperre, in Blöcken bis 5.000, je Empfänger data für {{platzhalter}}.
5. POST /v1/send-jobs/{id}/start, danach GET /v1/send-jobs/{id} alle paar Sekunden, bis status completed ist.

```ts
import { newsletterkit } from "@/lib/newsletterkit";

// 1) Job anlegen
const job = await newsletterkit<{ data: { id: string } }>("/send-jobs", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ template_id: templateId, params: { titel: "Sommerprogramm" } }),
});

// 2) Empfänger aus dem CRM: Einwilligung UND keine Sperre — nie nur eins davon
const contacts = await db.contact.findMany({
  where: { marketingConsent: true, emailSuppressed: false },
  select: { id: true, email: true, firstName: true },
});
for (let i = 0; i < contacts.length; i += 5000) {
  const chunk = contacts.slice(i, i + 5000);
  const res = await newsletterkit<{ data: { recipients: { email: string; message_id: string }[] } }>(
    `/send-jobs/${job.data.id}/recipients`,
    {
      method: "POST",
      headers: { "Idempotency-Key": `${job.data.id}:${i}` },
      body: JSON.stringify({
        recipients: chunk.map((c) => ({ email: c.email, data: { vorname: c.firstName } })),
      }),
    },
  );
  // Mail-IDs an die Kontakte schreiben — der Schlüssel für Status und Auswertung
  for (const r of res.data.recipients) await db.newsletterMail.create({ data: { contactEmail: r.email, messageId: r.message_id, jobId: job.data.id } });
}

// 3) Starten und abwarten
await newsletterkit(`/send-jobs/${job.data.id}/start`, { method: "POST" });
```

### Newsletter aus dem Builder
Der Nutzer stapelt Blöcke im Canvas des Portals und füllt sie mit Inhalt. Das Portal rendert nie selbst: Jede Vorschau und jede Kachel kommt fertig aus NewsletterKit, mit den Design-Regeln des Kunden dieses Moments. Am Ende wird der Stapel als eigenes Template gespeichert und wie ein fertiges verschickt.
1. GET /v1/blocks — Blöcke mit Parameter-Schema und tile_url; Kacheln über GET /v1/blocks/{id}/tile in iframes mit srcdoc.
2. Bei jeder Änderung (entprellt, ~300 ms): POST /v1/render/preview mit dem Stapel — HTML in ein iframe.
3. Bilder: POST /v1/assets → PUT an upload.url → POST /v1/assets/{id}/complete; die url in Bild-Parameter setzen.
4. POST /v1/templates speichert den Stapel als Template (Art newsletter; kein Footer im Stapel, der kommt aus dem Rahmen des Kunden).
5. Weiter wie beim fertigen Template: Job anlegen, Empfänger anhängen, starten.

```ts
import { newsletterkit } from "@/lib/newsletterkit";

// Live-Vorschau: der Stapel des Builders, unverändert, an die API
export async function preview(blocks: { block_id: string; values: Record<string, unknown> }[]) {
  const { data } = await newsletterkit<{ data: { html: string | null; errors: string[] } }>(
    "/render/preview",
    { method: "POST", body: JSON.stringify({ blocks }) },
  );
  return data.html; // <iframe srcDoc={html} sandbox="" />
}

// Bild hochladen: drei Aufrufe hinter einer Funktion
export async function uploadAsset(file: File) {
  const created = await newsletterkit<{ data: { id: string; upload: { url: string; headers: Record<string, string> } } }>(
    "/assets",
    { method: "POST", body: JSON.stringify({ filename: file.name, content_type: file.type }) },
  );
  await fetch(created.data.upload.url, { method: "PUT", headers: created.data.upload.headers, body: file });
  const done = await newsletterkit<{ data: { url: string; width: number; height: number } }>(
    `/assets/${created.data.id}/complete`,
    { method: "POST" },
  );
  return done.data; // { url, width, height } — url in bild.url setzen
}

// Speichern als Template
const template = await newsletterkit<{ data: { id: string } }>("/templates", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    name: "Sommer-Newsletter",
    subject: "Hallo {{vorname}}, das Sommerprogramm ist da",
    blocks, // derselbe Stapel wie in der Vorschau
    status: "active",
  }),
});
```

### Sperren ins CRM
Die Einwilligung liegt im CRM, die Sperre bei Postmark. NewsletterKit spiegelt die Sperren; das CRM holt sie ab und leitet daraus ab, wer eine Mail bekommen darf. Ein Cron alle paar Minuten reicht — beim Versand sperrt Postmark ohnehin zuletzt.
1. Cron: GET /v1/suppressions?since=<letzter Stand>, Seiten über paging.after; je Eintrag das Sperrfeld des Kontakts setzen (active=true) oder aufheben (active=false).
2. Einzelfall: POST /v1/suppressions/lookup mit bis zu 500 Adressen.
3. Nach neuem Double-Opt-in: POST /v1/suppressions/reactivate — 409 bei Spam-Beschwerde, die bleibt.

```ts
// app/api/cron/suppressions/route.ts — alle 5 Minuten (Vercel Cron)
import { newsletterkit } from "@/lib/newsletterkit";

type Suppression = { email: string; active: boolean; reason?: string; changed_at: string };

export async function GET() {
  let since = (await kv.get<string>("nk:suppressions_since")) ?? "1970-01-01T00:00:00Z";
  let after: string | null = null;
  do {
    const page = await newsletterkit<{ data: Suppression[]; paging: { after: string | null; has_next: boolean } }>(
      `/suppressions?since=${since}${after ? `&after=${after}` : ""}`,
    );
    for (const s of page.data) {
      // Nur das Sperrfeld — die Einwilligung fasst der Abgleich nie an.
      await db.contact.updateMany({
        where: { email: s.email },
        data: { emailSuppressed: s.active, emailSuppressedReason: s.active ? s.reason : null },
      });
      since = s.changed_at;
    }
    after = page.paging.has_next ? page.paging.after : null;
  } while (after);
  await kv.set("nk:suppressions_since", since);
  return Response.json({ ok: true });
}
```

### Auswertungsseite
Die Auswertung liegt bei NewsletterKit, das Portal rendert nur: drei Aufrufe, fertige Zahlen. Öffnungen und Klicks laufen noch Tage nach dem Versand ein.
1. GET /v1/send-jobs/{id} — Zähler je Ergebnis, stats (Summen) und timeline (je Stunde).
2. GET /v1/send-jobs/{id}/messages?status=bounced — wer nicht erreicht wurde, über Mail-IDs.
3. GET /v1/send-jobs/{id}/links — Klicks je Link.

```ts
import { newsletterkit } from "@/lib/newsletterkit";

export async function newsletterReport(jobId: string) {
  const [job, bounced, links] = await Promise.all([
    newsletterkit<{ data: { status: string; recipients: Record<string, number>; stats: Record<string, number>; timeline: unknown[] } }>(`/send-jobs/${jobId}`),
    newsletterkit<{ data: { message_id: string; bounce_type: string | null }[] }>(`/send-jobs/${jobId}/messages?status=bounced`),
    newsletterkit<{ data: { url: string; clicks: number; unique_clicks: number }[] }>(`/send-jobs/${jobId}/links`),
  ]);
  return { job: job.data, bounced: bounced.data, links: links.data };
}
```

## Einwilligung & Sperren
Regeln für die Einbindung in ein Kundensystem (CRM, Newsletter-Builder):
- Die Einwilligung liegt im Kundensystem. Die Werbeeinwilligung ist ein dokumentierter Akt: Double-Opt-in mit Zeitpunkt, Text und Herkunft. NewsletterKit und Postmark kennen sie nicht und fragen nie danach. Das Feld gehört dem Kundensystem, und nur das Kundensystem schreibt es.
- Die Sperre liegt bei Postmark. Abmeldung, Hard Bounce und Spam-Beschwerde entstehen bei Postmark und werden dort durchgesetzt: Ein gesperrter Empfänger wird je Nachricht abgewiesen, egal was das Kundensystem über ihn glaubt. NewsletterKit spiegelt Sperren und gibt sie weiter; übersteuern kann sie niemand.
- „Darf E-Mails empfangen“ ist eine Ableitung, kein Feld. Einwilligung vorhanden UND keine aktive Sperre. Im CRM sind das zwei getrennte Felder: marketing_consent schreibt nur das Kundensystem, email_suppressed schreibt nur der Abgleich mit NewsletterKit. Wer beide zu einem Boolean verschmilzt, verliert die Wiederkehr: Ein Abgemeldeter, der sich neu einträgt, hätte wieder Einwilligung, bliebe aber bei Postmark gesperrt.
- Abgleich durch Abholen. Das Kundensystem ruft regelmäßig GET /v1/suppressions?since=<letzter Stand> und schreibt die Antwort in sein Sperrfeld — gesetzte wie aufgehobene Sperren. Ein Cron alle paar Minuten reicht: Beim Versand sperrt Postmark ohnehin zuletzt, ein verspäteter Abgleich kostet höchstens eine abgewiesene Nachricht.
- Wiederkehr nur nach neuem Double-Opt-in. Wer sich abgemeldet hat und später neu einträgt, bleibt bei Postmark gesperrt, bis das Kundensystem POST /v1/suppressions/reactivate ruft. Das geschieht nach der Bestätigung, nie beim Setzen eines Hakens. Nach einer Spam-Beschwerde gibt es keine Reaktivierung; die Adresse bleibt dauerhaft gesperrt.
- Der Abmeldelink kommt von Postmark. Newsletter enthalten den Abmeldelink über den Footer des Kunden; die Adresse dahinter setzt Postmark je Empfänger ein, und die Abmeldung führt auf Postmarks Abmeldeseite. Der Aufrufer übergibt keinen unsubscribe_url. Eine Abmeldung gilt für alle Newsletter dieses Kunden — Listen und Segmente kennt Postmark nicht.
- Transaktionale Mails bleiben erreichbar. Sperren gelten je Stream. Ein abgemeldeter Empfänger bekommt weiterhin transaktionale Mails wie Double-Opt-in, Bestellbestätigung oder Passwort-Reset; gesperrt sind nur Newsletter.
- Listen und Segmente gehören dem Kundensystem. NewsletterKit kennt keine Listen. Welche Kontakte einen Newsletter bekommen, entscheidet das Kundensystem beim Zusammenstellen der Empfänger — gefiltert nach Einwilligung und Sperre. Adressen reisen nur mit dem Versandjob und werden nach dessen Abschluss gelöscht; es bleibt der Hash und die Mail-ID.

## Endpoints

### System
Verbindung & Health. Der einfachste Endpunkt — prüft API-Key und Erreichbarkeit.

#### GET /v1/health
Prüft, dass der API-Key gültig und die API erreichbar ist. Erfordert mindestens den Scope reporting. Ideal für Status-Monitoring und um die Anbindung beim Onboarding zu verifizieren.

Response:
```json
{
  "data": { "status": "ok", "api_version": "v1" },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Blöcke
Liefert die für den Kunden freigeschalteten MJML-Blöcke samt Parameter-Schema. Welche Blöcke ein Template verwenden darf, kommt aus dieser Liste — referenziert wird ein Block immer über seine unveränderliche id (UUID), nicht über den slug. Blöcke selbst werden ausschließlich im Admin gepflegt.

#### GET /v1/blocks
Listet die für den Kunden freigeschalteten, aktiven Blöcke. Jeder Eintrag enthält die stabile id (UUID — der unveränderliche Referenzschlüssel), den slug (menschenlesbares Label) und das Parameter-Schema (name, type, required, fallback, hide_if_missing, example). Diese Liste sagt einem Client, welche Blöcke er in einem Template verwenden darf und welche Werte jeder Block erwartet. tags sind die vom Admin gepflegten Kategorien des Blocks — für Logik zählt der slug, label ist nur die Anzeige. series nennt die Familie, aus der ein Block stammt (höchstens eine, sonst null): Blöcke derselben Serie sind zusammen entworfen und passen optisch zueinander — rein zum Gruppieren, ein Template darf Serien mischen. Ein Template referenziert einen Block über seine id, nicht über den slug — Slugs und Namen können sich ändern, die id bleibt stabil und schützt gespeicherte Templates vor Brüchen. Read-only, Scope reporting genügt.

Response:
```json
{
  "data": [
    {
      "id": "b1a2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
      "slug": "hero-text",
      "name": "Hero-Text",
      "tags": [{ "slug": "content", "label": "Inhalt" }],
      "series": { "slug": "journal", "label": "Journal" },
      "description": "Große Überschrift mit Fließtext.",
      "version": 1,
      "params": [
        { "name": "headline", "label": "Überschrift", "type": "string", "required": true,  "fallback": null, "hide_if_missing": false, "example": "Willkommen zum Sommer-Update" },
        { "name": "body",     "label": "Fließtext",   "type": "text",   "required": true,  "fallback": null, "hide_if_missing": false, "example": "Hier kommen die wichtigsten Neuigkeiten." }
      ]
    }
  ],
  "request_id": "…"
}
```

Hinweis: tile_url zeigt auf die fertig gerenderte Kachel des Blocks (GET /v1/blocks/{id}/tile). Ein Template referenziert Blöcke über die unveränderliche id (UUID), nicht über den slug — so brechen gespeicherte Kompositionen nicht, wenn ein Admin Slug oder Name eines Blocks umbenennt. Welche Blöcke freigeschaltet sind, steuert ein Admin pro Kunde (customer_blocks). MJML-Templates unterstützen bedingte Abschnitte: {{#param}}…{{/param}} rendert nur, wenn param einen nicht-leeren Wert hat (optionale Elemente wie ein Logo oder ein AGB-Link verschwinden, wenn nicht gesetzt) — zusätzlich zum einfachen {{param}}. Die Detail-Doku je Block (alle Parameter + Beispielwerte) liefert die Seite „Block-Parameter“.

#### GET /v1/blocks/{id}/tile
Die Kachel für die Blockauswahl im Builder: der Block mit seinen Beispielwerten, gerendert im Design und mit den Marken-Werten des Kunden — fertiges HTML für ein iframe mit srcdoc. Gecacht; ändert sich, sobald Block oder Design-Regeln sich ändern. Ändert der Admin eine Farbe, zeigt die nächste Kachel sie ohne Zutun des Portals. Scope reporting.

Path-Parameter:
- id (string (UUID), erforderlich): Die block_id aus GET /v1/blocks. (z. B. 0d384008-1a29-4fbb-bfa8-a2509e426396)

Request:
```
GET /v1/blocks/0d384008-…/tile
```

Response:
```json
{
  "data": { "block_id": "0d384008-…", "slug": "beyond-hero", "html": "<!doctype html>…" },
  "request_id": "…"
}
```

Hinweis: html ist null, wenn ein Pflichtwert des Blocks kein Beispiel hat — dann gibt es kein Bild, sondern eine Lücke.

### Design-Regeln
Liefert das vollständige, aufgelöste Design-Token-Set des Kunden (Flächen-/Text-/Akzent-/Status-Farben, Typografie, Abstände, Komponenten). Diese Tokens werden beim Render in jedes MJML-Dokument injiziert und erzwingen ein konsistentes Erscheinungsbild über alle Newsletter hinweg. Das vollständige Regelwerk (welches Token wofür) steht unter /docs/design-rules.

#### GET /v1/design-rules
Gibt das vollständige, AUFGELÖSTE Token-Set des Kunden zurück: jeder {{token}} mit seinem konkreten Render-Wert (Größen wie Abstände/Breite bereits in px). Hat der Kunde noch keine eigenen Regeln hinterlegt, liefert die API vollständige Default-Tokens. Read-only, Scope reporting genügt — diese Tokens kann der Client nicht überschreiben, er kann sie nur lesen (z. B. für eine originalgetreue Editor-Vorschau).

Response:
```json
{
  "data": {
    "color_background": "#f4f4f5",
    "color_container": "#ffffff",
    "color_text": "#202020",
    "color_heading": "#111111",
    "color_primary": "#e11d48",
    "color_on_primary": "#ffffff",
    "color_link": "#2563eb",
    "color_footer_bg": "#1a1a1a",
    "color_footer_text": "#e4e4e7",
    "font_heading": "Georgia, serif",
    "font_body": "Helvetica, Arial, sans-serif",
    "font_size_base": "16px",
    "font_size_h1": "28px",
    "space_section": "16px",
    "container_width": "600",
    "button_radius": "6px"
  },
  "request_id": "…"
}
```

Hinweis: Design-Tokens werden serverseitig am Render injiziert — sie sind verbindlich und können über die API nicht verändert werden (Pflege im Admin-Dashboard). Das vollständige Regelwerk steht unter /docs/design-rules.

### Rendering
Rendert einen Block-Stapel serverseitig zu MJML + kompiliertem, responsivem HTML — die Live-Vorschau des Builders im Kundenportal, zustandslos und ohne etwas zu versenden. MJML-Templates unterstützen bedingte Abschnitte {{#param}}…{{/param}}, die nur bei nicht-leerem Wert rendern (optionale Elemente wie Logo oder AGB-Link verschwinden sonst).

#### POST /v1/render/preview
Rendert den übergebenen Stapel (blocks) mit seinen values serverseitig zu MJML und kompiliertem, responsivem HTML. Der MJML-Compiler läuft serverseitig (stub: false), das Ergebnis ist also fertiges, in jedem Mail-Client darstellbares HTML. Die Design-Regeln des Kunden werden dabei über das Code-Grundgerüst angewendet; Marken-Werte (Logo, Impressum) kommen aus den Kunden-Parametern. Bedingte MJML-Abschnitte {{#param}}…{{/param}} werden ausgewertet: Parameter ohne Wert werden aus dem gerenderten HTML weggelassen. Versendet nichts und legt nichts an — reine Vorschau für den Editor. Scope full.

Body-Parameter:
- blocks (object[], erforderlich): Der Stapel als Block-Refs ({ block_id, values }) — genau der Stand, den der Builder gerade hält. block_id ist die unveränderliche UUID des Blocks (aus GET /v1/blocks, Feld id), NICHT der slug. (z. B. [{"block_id":"b1a2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d","values":{"headline":"Hi"}}])
- values (object, optional): Globale Werte, die zusätzlich/überschreibend in die Block-Refs einfließen (z. B. eine Vorschau mit Beispieldaten). (z. B. {"headline":"Vorschau-Titel"})

Request:
```
POST /v1/render/preview
{
  "blocks": [
    { "block_id": "b1a2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d", "values": { "headline": "Vorschau-Titel" } }
  ]
}
```

Response:
```json
{
  "data": {
    "mjml": "<mjml>…</mjml>",
    "html": "<!doctype html>…</html>",
    "errors": [],
    "stub": false
  },
  "request_id": "…"
}
```

Hinweis: Der MJML-Compiler läuft serverseitig — html ist fertiges, responsives HTML und stub ist immer false. errors listet etwaige MJML-Compiler-Warnungen/-Fehler (leeres Array bei sauberem Render). Bedingte Abschnitte {{#param}}…{{/param}} werden ausgewertet (Parameter ohne Wert werden weggelassen). Vorschau ist PII-frei und nicht abrechnungsrelevant — es wird keine E-Mail erzeugt.

### Templates
Verschickt wird immer ein Template. Es gehört dem Kunden — im Dashboard gebaut (origin admin, mit Parameter-Vertrag) oder aus dem Builder des Kundenportals gespeichert (origin customer, feste Werte, {{platzhalter}} je Empfänger). Struktur und Blöcke liegen serverseitig fest, das Aussehen kommt aus den Design-Regeln des Kunden, der Footer aus seinem Rahmen.

#### GET /v1/templates
Alle Templates des Kunden mit Art, Status, Herkunft und Parameter-Vertrag (name, label, type, required, fallback, example). Ein Portal, das ein fertiges Template anbietet, holt hier die Felder, die der Nutzer füllen soll — eine KI kann sie aus Bezeichnung und Beispiel vorausfüllen. Scope reporting.

Request:
```
GET /v1/templates
```

Response:
```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-0000000000f3",
      "name": "Einladung (Beyond)",
      "subject": "{{titel}}",
      "kind": "transaktional",
      "status": "active",
      "origin": "admin",
      "from": null,
      "reply_to": null,
      "params": [
        { "name": "titel", "label": "Überschrift", "type": "string", "required": true, "fallback": null, "example": "Dein Zugang zum Dashboard" },
        { "name": "link",  "label": "Einladungslink", "type": "url", "required": true, "fallback": null, "example": "https://example.com/einladung?token=BEISPIEL" }
      ],
      "created_at": "2026-09-02T11:00:00Z",
      "updated_at": "2026-09-03T09:12:00Z"
    }
  ],
  "request_id": "…"
}
```

#### POST /v1/templates
Speichert den Stapel des Builders als eigenes Newsletter-Template (origin customer). Blöcke über block_id aus GET /v1/blocks, values wie bei der Vorschau — feste Werte, {{platzhalter}} darin werden je Empfänger beim Versandjob gefüllt. Kein Footer im Stapel: Der kommt aus dem Rahmen des Kunden. Werte müssen Parameter des Blocks sein. status active nur, wenn beim Kunden ein Newsletter-Footer hinterlegt ist. Scope full, idempotent.

Body-Parameter:
- name (string, erforderlich): Anzeigename im Portal und Dashboard. (z. B. Sommer-Newsletter)
- subject (string, erforderlich): Betreff; {{platzhalter}} erlaubt. (z. B. Hallo {{vorname}}, das Sommerprogramm ist da)
- blocks (object[], erforderlich): [{ block_id, values }] in Reihenfolge. block_id aus GET /v1/blocks; values nur für Parameter des Blocks, zusammengesetzte als Objekt ({ url, alt }). (z. B. [{"block_id":"…","values":{"titel":"Hallo {{vorname}}"}}])
- status (enum, optional): draft (Standard) oder active. (z. B. draft)

Request:
```
POST /v1/templates
Idempotency-Key: 3b0f…
{
  "name": "Sommer-Newsletter",
  "subject": "Hallo {{vorname}}, das Sommerprogramm ist da",
  "blocks": [
    { "block_id": "0d384008-…", "values": { "titel": "Hallo {{vorname}}", "button_text": "Programm ansehen", "button_url": "https://kunde.de/programm" } },
    { "block_id": "637c2bbc-…", "values": { "bild": { "url": "https://…/mail-assets/…/08144388….jpg", "alt": "Bühne bei Nacht" } } }
  ],
  "status": "draft"
}
```

Response:
```json
{
  "data": {
    "id": "b33be79b-…",
    "name": "Sommer-Newsletter",
    "kind": "newsletter",
    "status": "draft",
    "origin": "customer",
    "params": [],
    "blocks": [ { "block_id": "0d384008-…", "block_slug": "beyond-hero", "values": { "titel": "Hallo {{vorname}}", "…": "…" } } ],
    "created_at": "2026-09-03T17:00:00Z"
  },
  "request_id": "…"
}
```

Hinweis: 422 bei Footer im Stapel, unbekannten Werten oder einem Abmeldelink im Stapel; 403, wenn ein Block nicht freigeschaltet ist; 409 beim Aktivieren ohne Newsletter-Footer.

#### GET /v1/templates/{id}
Wie die Liste, zusätzlich der Stapel (blocks mit values). Scope reporting.

Path-Parameter:
- id (string (UUID), erforderlich): Die Template-ID. (z. B. b33be79b-90b1-44ca-bfae-5901cdc6713c)

Request:
```
GET /v1/templates/b33be79b-…
```

Response:
```json
{
  "data": { "id": "b33be79b-…", "name": "Sommer-Newsletter", "kind": "newsletter", "status": "active", "origin": "customer", "params": [], "blocks": [ "…" ] },
  "request_id": "…"
}
```

#### PUT /v1/templates/{id}
Ändert Name, Betreff, Stapel oder Status eines aus dem Portal gespeicherten Templates — alle Felder optional. Templates aus dem Dashboard (origin admin) sind über die API nur lesbar (403). Scope full.

Path-Parameter:
- id (string (UUID), erforderlich): Die Template-ID. (z. B. b33be79b-90b1-44ca-bfae-5901cdc6713c)

Body-Parameter:
- name (string, optional): Neuer Name. (z. B. Sommer-Newsletter v2)
- subject (string, optional): Neuer Betreff. (z. B. Das Sommerprogramm ist da)
- blocks (object[], optional): Der ganze Stapel neu, wie beim Anlegen. (z. B. [{"block_id":"…","values":{}}])
- status (enum, optional): draft oder active. (z. B. active)

Request:
```
PUT /v1/templates/b33be79b-…
{ "status": "active" }
```

Response:
```json
{
  "data": { "id": "b33be79b-…", "status": "active", "…": "…" },
  "request_id": "…"
}
```

#### DELETE /v1/templates/{id}
Löscht ein aus dem Portal gespeichertes Template. Laufende Versandjobs behalten ihre gerenderte Mail. Dashboard-Templates: 403. Scope full.

Path-Parameter:
- id (string (UUID), erforderlich): Die Template-ID. (z. B. b33be79b-90b1-44ca-bfae-5901cdc6713c)

Request:
```
DELETE /v1/templates/b33be79b-…
```

Response:
```json
{ "data": { "deleted": true }, "request_id": "…" }
```

#### POST /v1/templates/{id}/send
Versendet die transaktionale Mail des Templates {id} — es muss dem aufrufenden Kunden gehören und die Art transaktional haben; Newsletter gehen als Versandjob raus. Der Client übergibt einen einzelnen Empfänger und die Werte der Template-Parameter. Unbekannte Parameter werden abgelehnt; Pflicht-Parameter sind erzwungen. Pflicht-Parameter dürfen auch aus den Marken-Parametern des Kunden (Logo, Impressum …) gedeckt werden. Scope full, idempotent.

Path-Parameter:
- id (string (UUID), erforderlich): ID des Templates (im Kunden-Detail unter Templates kopierbar). (z. B. 00000000-0000-4000-8000-0000000000f3)

Body-Parameter:
- to (string (E-Mail), erforderlich): Empfängeradresse. Gespeichert wird nur ihr Hash. (z. B. mira@example.com)
- params (object, optional): Werte der Template-Parameter (der komplette Personalisierungs-Vertrag des Templates). {{platzhalter}} in festen Texten werden aus denselben Werten gefüllt. (z. B. {"titel":"Dein Zugang zum Dashboard","name":"Mira","link":"https://kunde.de/einladung?token=…"})
- from (object, optional): Absender-Ausnahme { email, name }. Standard ist die No-Reply-Adresse des Kunden; der Teil vor dem @ ist frei, die Domain muss beim Kunden hinterlegt sein. (z. B. {"email":"lena.berger@kunde.de","name":"Lena Berger"})
- reply_to (string (E-Mail), optional): Antwort-Adresse; leer = wie Absender. (z. B. support@kunde.de)

Request:
```
POST /v1/templates/00000000-0000-4000-8000-0000000000f3/send
Idempotency-Key: 6f1c…
{
  "to": "mira@example.com",
  "params": {
    "titel": "Dein Zugang zum Dashboard",
    "name": "Mira",
    "text": "Du bist als Redaktion eingetragen.",
    "link": "https://kunde.de/einladung?token=…",
    "screenshot": "https://kunde.de/bilder/dashboard.jpg"
  }
}
```

Response:
```json
{
  "data": {
    "message_id": "b7e3…",
    "status": "accepted",
    "mode": "live",
    "template_id": "00000000-0000-4000-8000-0000000000f3"
  },
  "request_id": "…"
}
```

Hinweis: Synchron: Die Antwort kommt, wenn Postmark geantwortet hat. status accepted = angenommen und gezählt; suppressed = Empfänger bei Postmark gesperrt; invalid = Adresse ungültig. Idempotent über Idempotency-Key (kein doppelter Versand bei Retries; gleicher Key mit anderem Body → 409; antwortet Postmark nicht, bleibt der Key belegt und die Wiederholung bekommt dieselbe 500-Antwort samt message_id statt einer zweiten Mail). Nur aktive Templates des eigenen Kunden (sonst 409/404); Newsletter-Templates → 422; Monatslimit erreicht → 429 quota_exceeded; Versand nicht freigeschaltet → 403. Im Sandbox-Modus nimmt Postmark an, stellt nichts zu und zählt nichts.

### Verbrauch
Zeigt die versendeten Mengen: laufender Monat, Hochrechnung, Vormonate. Keine Beträge — abgerechnet wird nach Staffel in Stripe.

#### GET /v1/usage
Gibt die Mengen dieses Kunden zurück: laufender Monat (getrennt nach newsletter/transactional), eine lineare Hochrechnung auf den ganzen Monat und die drei Vormonate. Scope reporting — auch bei gesperrtem Zugang erreichbar.

Response:
```json
{
  "data": {
    "current_month": {
      "period_month": "2026-09-01",
      "emails_sent": 12480,
      "emails_newsletter": 9330,
      "emails_transactional": 3150,
      "projected_emails": 41600,
      "days_elapsed": 9,
      "days_in_month": 30
    },
    "previous_months": [
      { "period_month": "2026-08-01", "emails_sent": 38200, "emails_newsletter": 29100, "emails_transactional": 9100 }
    ]
  },
  "request_id": "…"
}
```

Hinweis: Preise stehen bewusst nicht darin: Was der Verbrauch kostet, rechnet Stripe und stellt es gemeinsam mit den anderen Produkten auf einer Rechnung dar. Eine zweite Stelle mit Beträgen würde irgendwann abweichen.

### Bilder
Bilder für Newsletter: Das Portal lädt sie über NewsletterKit hoch und bekommt eine öffentliche, unveränderliche https-Adresse zurück — optimiert für Mail-Clients (höchstens 1360 px breit, JPEG oder PNG, unter 400 KB, ohne Metadaten). Zwei Schritte, weil ein Aufruf höchstens 4,5 MB annimmt: anmelden, Datei an die signierte Adresse schicken, abschließen.

#### POST /v1/assets
Legt ein Bild an und liefert eine signierte Upload-Adresse (zwei Stunden gültig). Die Datei geht per PUT mit ihrem Content-Type direkt an upload.url — ohne API-Key. Danach POST /v1/assets/{id}/complete. Erlaubt: PNG, JPEG, WebP, GIF, AVIF, SVG, bis 25 MB. Scope full.

Body-Parameter:
- filename (string, erforderlich): Dateiname, nur zur Anzeige. (z. B. buehne.jpg)
- content_type (string, erforderlich): MIME-Typ der Datei. (z. B. image/jpeg)

Request:
```
POST /v1/assets
{ "filename": "buehne.jpg", "content_type": "image/jpeg" }

// dann, ohne API-Key:
PUT <upload.url>
Content-Type: image/jpeg
<Dateiinhalt>
```

Response:
```json
{
  "data": {
    "id": "b7f0b1a6-…",
    "status": "pending",
    "filename": "buehne.jpg",
    "url": null,
    "upload": { "url": "https://…/storage/v1/object/upload/sign/asset-uploads/…?token=…", "method": "PUT", "headers": { "Content-Type": "image/jpeg" } }
  },
  "request_id": "…"
}
```

#### POST /v1/assets/{id}/complete
Optimiert die hochgeladene Datei (Breite, Format, Qualität, Metadaten weg) und legt sie unter einer Adresse mit Inhalts-Hash ab, die sich nie ändert — Mail-Clients dürfen ewig cachen. Gefahrlos wiederholbar. Scope full.

Path-Parameter:
- id (string (UUID), erforderlich): Die id aus POST /v1/assets. (z. B. b7f0b1a6-95ad-4080-b5ab-f8721ce47aed)

Request:
```
POST /v1/assets/b7f0b1a6-…/complete
```

Response:
```json
{
  "data": {
    "id": "b7f0b1a6-…",
    "status": "ready",
    "filename": "buehne.jpg",
    "content_type": "image/jpeg",
    "url": "https://…/storage/v1/object/public/mail-assets/<kunde>/d576d44f….jpg",
    "width": 1360,
    "height": 1020,
    "bytes": 27177,
    "created_at": "2026-09-03T17:10:00Z"
  },
  "request_id": "…"
}
```

Hinweis: 422, wenn noch keine Datei hochgeladen ist oder sie kein lesbares Bild ist (HEIC wird abgelehnt). Die url gehört in Bild-Parameter wie bild.url.

#### GET /v1/assets
Die fertigen Bilder, neueste zuerst (limit bis 200). Scope reporting.

Query-Parameter:
- limit (integer, optional): max. 200, Standard 50. (z. B. 50)

Request:
```
GET /v1/assets
```

Response:
```json
{ "data": [ { "id": "b7f0b1a6-…", "status": "ready", "url": "https://…", "width": 1360, "height": 1020, "bytes": 27177 } ], "request_id": "…" }
```

#### GET /v1/assets/{id}
Ein Bild mit Adresse und Maßen. Scope reporting.

Path-Parameter:
- id (string (UUID), erforderlich): Die Bild-ID. (z. B. b7f0b1a6-95ad-4080-b5ab-f8721ce47aed)

Request:
```
GET /v1/assets/b7f0b1a6-…
```

Response:
```json
{ "data": { "id": "b7f0b1a6-…", "status": "ready", "url": "https://…", "width": 1360, "height": 1020, "bytes": 27177 }, "request_id": "…" }
```

#### DELETE /v1/assets/{id}
Löscht das Bild. Die Datei verschwindet erst, wenn kein anderes Bild des Kunden denselben Inhalt hat — zwei Uploads desselben Fotos teilen sich die Adresse. Verschickte Mails verweisen weiter auf die Adresse; löschen heißt, dass sie dort ins Leere zeigen. Scope full.

Path-Parameter:
- id (string (UUID), erforderlich): Die Bild-ID. (z. B. b7f0b1a6-95ad-4080-b5ab-f8721ce47aed)

Request:
```
DELETE /v1/assets/b7f0b1a6-…
```

Response:
```json
{ "data": { "deleted": true }, "request_id": "…" }
```

### Versandjobs
Ein Newsletter geht an viele Empfänger und wird als Versandjob verschickt: anlegen (Template, Parameter, Absender, optionaler Startzeitpunkt), Empfänger in Blöcken anhängen, starten, abfragen. Ein Worker rendert einmal, schickt Batches an Postmark und hält je Empfänger das Ergebnis fest. Die Empfängerliste baut das Kundensystem aus seinem CRM — gefiltert nach Einwilligung und Sperre.

#### POST /v1/send-jobs
Legt einen Job als Entwurf an. Das Template muss dem Kunden gehören, aktiv und ein Newsletter sein; params sind die Werte seiner Template-Parameter (nur bekannte). Absender: Standard ist die Newsletter-Adresse des Kunden oder die Ausnahme des Templates; from.email darf den Teil vor dem @ ändern. scheduled_at plant den Start. Scope full, idempotent.

Body-Parameter:
- template_id (string (UUID), erforderlich): Ein Newsletter-Template des Kunden. (z. B. 00000000-0000-4000-8000-0000000000f4)
- params (object, optional): Werte der Template-Parameter. {{platzhalter}} in festen Texten werden aus params und den Daten des Empfängers gefüllt — der Empfänger gewinnt. (z. B. {"titel":"Sommerprogramm"})
- from (object, optional): Absender-Ausnahme { email, name } auf einer Domain des Kunden. (z. B. {"email":"lena.berger@kunde.de","name":"Lena Berger"})
- reply_to (string (E-Mail), optional): Antwort-Adresse; leer = wie Absender. (z. B. redaktion@kunde.de)
- scheduled_at (string (ISO 8601), optional): Startzeitpunkt; leer = sofort beim Start. (z. B. 2026-09-05T08:00:00Z)

Request:
```
POST /v1/send-jobs
Idempotency-Key: 7c2e…
{
  "template_id": "00000000-0000-4000-8000-0000000000f4",
  "params": { "titel": "Sommerprogramm" },
  "scheduled_at": "2026-09-05T08:00:00Z"
}
```

Response:
```json
{
  "data": {
    "id": "f90c0326-4a19-4b9f-bf81-37145e6371ab",
    "status": "draft",
    "mode": "live",
    "template_id": "00000000-0000-4000-8000-0000000000f4",
    "params": { "titel": "Sommerprogramm" },
    "from": { "email": "news@kunde.de", "name": "Kunde" },
    "reply_to": null,
    "scheduled_at": "2026-09-05T08:00:00Z",
    "recipients": { "total": 0, "accepted": 0, "suppressed": 0, "invalid": 0, "failed": 0, "pending": 0 },
    "batches": null,
    "created_at": "2026-09-03T16:00:00Z"
  },
  "request_id": "…"
}
```

Hinweis: Status: draft → scheduled | running → completed | cancelled | paused | failed. Ein Job im Sandbox-Modus des Kunden wird von Postmark angenommen, aber nicht zugestellt und nicht gezählt.

#### POST /v1/send-jobs/{id}/recipients
Hängt Empfänger an einen Job im Entwurf an — bis 5.000 je Aufruf, größere Listen in mehreren Aufrufen. Jeder Empfänger bekommt sofort seine Mail-ID; das Portal schreibt sie an seinen Kontakt. Eine Adresse ist je Job nur einmal drin (Dubletten werden gemeldet, nicht doppelt angelegt). data sind Werte für {{platzhalter}} dieses Empfängers, z. B. vorname. Mit einem Idempotency-Key je Block erzeugt ein Retry keine Dubletten. Scope full.

Path-Parameter:
- id (string (UUID), erforderlich): Die Job-ID. (z. B. f90c0326-4a19-4b9f-bf81-37145e6371ab)

Body-Parameter:
- recipients (object[], erforderlich): [{ email, data? }], 1–5.000 Einträge; data ist ein flaches Objekt aus Strings. (z. B. [{"email":"mira@example.com","data":{"vorname":"Mira"}}])

Request:
```
POST /v1/send-jobs/f90c0326-…/recipients
Idempotency-Key: 9a1d…
{
  "recipients": [
    { "email": "mira@example.com", "data": { "vorname": "Mira" } },
    { "email": "max@example.com",  "data": { "vorname": "Max" } }
  ]
}
```

Response:
```json
{
  "data": {
    "added": 2,
    "duplicates": 0,
    "total": 2,
    "recipients": [
      { "email": "mira@example.com", "message_id": "33267271-…" },
      { "email": "max@example.com",  "message_id": "42ba5d6b-…" }
    ]
  },
  "request_id": "…"
}
```

Hinweis: 429 quota_exceeded, wenn die Höchstzahl je Job des Kunden überschritten würde. 409, wenn der Job nicht mehr im Entwurf ist.

#### POST /v1/send-jobs/{id}/start
Startet den Job — sofort oder zum Zeitpunkt in scheduled_at (Body oder beim Anlegen gesetzt). Prüft Freischaltung, Newsletter-Footer, Pflicht-Parameter und im Live-Modus das Monatslimit. Danach übernimmt der Worker: einmal rendern, Batches an Postmark. Scope full.

Path-Parameter:
- id (string (UUID), erforderlich): Die Job-ID. (z. B. f90c0326-4a19-4b9f-bf81-37145e6371ab)

Body-Parameter:
- scheduled_at (string (ISO 8601), optional): Startzeitpunkt; überschreibt den beim Anlegen gesetzten. (z. B. 2026-09-05T08:00:00Z)

Request:
```
POST /v1/send-jobs/f90c0326-…/start
```

Response:
```json
{
  "data": { "id": "f90c0326-…", "status": "running", "recipients": { "total": 12000, "accepted": 0, "pending": 12000, "suppressed": 0, "invalid": 0, "failed": 0 } },
  "request_id": "…"
}
```

Hinweis: 403, wenn der Versand nicht freigeschaltet ist; 422 ohne Empfänger oder bei fehlenden Pflicht-Parametern; 429 quota_exceeded am Monatslimit.

#### POST /v1/send-jobs/{id}/cancel
Bricht einen Job ab — im Entwurf, geplant, laufend oder pausiert. Was Postmark schon angenommen hat, ist raus; alles Übrige geht nicht mehr raus. Scope full.

Path-Parameter:
- id (string (UUID), erforderlich): Die Job-ID. (z. B. f90c0326-4a19-4b9f-bf81-37145e6371ab)

Request:
```
POST /v1/send-jobs/f90c0326-…/cancel
```

Response:
```json
{
  "data": { "id": "f90c0326-…", "status": "cancelled", "cancelled_at": "2026-09-03T16:20:00Z" },
  "request_id": "…"
}
```

#### GET /v1/send-jobs/{id}
Der Job mit Zählern je Ergebnis (angenommen, gesperrt, ungültig, fehlgeschlagen, offen), den Summen aus den Postmark-Ereignissen (stats) und denselben Zahlen je Stunde (timeline). Während des Versands alle paar Sekunden abfragen, bis der Status completed ist; danach ist es die Auswertungsseite. Scope reporting.

Path-Parameter:
- id (string (UUID), erforderlich): Die Job-ID. (z. B. f90c0326-4a19-4b9f-bf81-37145e6371ab)

Request:
```
GET /v1/send-jobs/f90c0326-…
```

Response:
```json
{
  "data": {
    "id": "f90c0326-…",
    "status": "completed",
    "mode": "live",
    "recipients": { "total": 12000, "accepted": 11812, "suppressed": 188, "invalid": 0, "failed": 0, "pending": 0 },
    "batches": 68,
    "stats": { "accepted": 11812, "suppressed": 188, "delivered": 11640, "bounced": 92, "opened": 6120, "opened_unique": 4870, "clicked": 1420, "clicked_unique": 1180, "complained": 6, "unsubscribed": 41 },
    "timeline": [ { "bucket": "2026-09-05T08:00:00Z", "accepted": 11812, "delivered": 9800, "opened": 1200, "…": "…" } ]
  },
  "request_id": "…"
}
```

Hinweis: Öffnungen und Klicks kommen aus Postmarks Ereignissen und laufen noch Tage nach dem Versand ein. Ein pausierter Job nennt in paused_reason, was ein Admin klären muss.

#### GET /v1/send-jobs/{id}/messages
Die Mails eines Jobs mit ihrem Zustand, über Mail-IDs — etwa alle gebouncten (status=bounced). Die Adresse steht nur dabei, solange der Job läuft; nach dem Abschluss kennt sie nur noch das Portal. Cursor über after. Scope reporting.

Path-Parameter:
- id (string (UUID), erforderlich): Die Job-ID. (z. B. f90c0326-4a19-4b9f-bf81-37145e6371ab)

Query-Parameter:
- status (enum, optional): pending | accepted | suppressed | invalid | failed | unknown | cancelled | delivered | bounced | complained (z. B. bounced)
- limit (integer, optional): Einträge pro Seite, max. 500. (z. B. 500)
- after (string, optional): Cursor aus paging.after. (z. B. MjAyNi0…)

Request:
```
GET /v1/send-jobs/f90c0326-…/messages?status=bounced
```

Response:
```json
{
  "data": [
    { "message_id": "00024021-…", "status": "bounced", "email": null, "bounce_type": "HardBounce", "bounced_at": "2026-09-05T08:04:12Z", "delivered_at": null, "first_opened_at": null, "first_clicked_at": null, "complained_at": null, "error": null }
  ],
  "paging": { "after": null, "has_next": false },
  "request_id": "…"
}
```

#### GET /v1/send-jobs/{id}/links
Klicks je Link eines Jobs, meistgeklickt zuerst. Scope reporting.

Path-Parameter:
- id (string (UUID), erforderlich): Die Job-ID. (z. B. f90c0326-4a19-4b9f-bf81-37145e6371ab)

Request:
```
GET /v1/send-jobs/f90c0326-…/links
```

Response:
```json
{
  "data": [
    { "url": "https://kunde.de/programm", "clicks": 1420, "unique_clicks": 1180 }
  ],
  "request_id": "…"
}
```

#### GET /v1/send-jobs
Die letzten Jobs, neueste zuerst; optional nach status gefiltert. Scope reporting.

Query-Parameter:
- status (enum, optional): draft | scheduled | running | paused | completed | cancelled | failed (z. B. running)
- limit (integer, optional): max. 100, Standard 25. (z. B. 25)

Request:
```
GET /v1/send-jobs?status=running
```

Response:
```json
{
  "data": [ { "id": "f90c0326-…", "status": "running", "recipients": { "total": 12000, "accepted": 8673, "pending": 3327, "suppressed": 0, "invalid": 0, "failed": 0 } } ],
  "request_id": "…"
}
```

### Mails
Der Status einer einzelnen Mail. Jede Mail bekommt beim Versand eine ID von uns; das Portal schreibt sie an seine Bestellung oder seinen Kontakt und fragt hier nach — zugestellt, geöffnet, gebounct mit Grund, gesperrt. Die Adresse steht nirgends in der Antwort.

#### GET /v1/messages/{id}
Liefert den zuletzt bekannten Zustand einer Mail und ihren Verlauf aus den Postmark-Ereignissen: pending → accepted → delivered, oder bounced / complained; suppressed, invalid, failed, unknown, wenn Postmark nicht angenommen hat. Nur eigene Mails — eine fremde ID existiert für diesen Kunden nicht (404). Scope reporting.

Path-Parameter:
- id (string (UUID), erforderlich): Die message_id aus der Antwort des Versands. (z. B. 128e7694-9f93-41e3-88f8-d0c3083d6d63)

Request:
```
GET /v1/messages/128e7694-9f93-41e3-88f8-d0c3083d6d63
```

Response:
```json
{
  "data": {
    "id": "128e7694-…",
    "kind": "transactional",
    "mode": "live",
    "status": "delivered",
    "template_id": "00000000-0000-4000-8000-0000000000f3",
    "send_job_id": null,
    "subject": "Dein Zugang zum Dashboard",
    "bounce_type": null,
    "error": null,
    "created_at": "2026-09-03T15:20:11Z",
    "delivered_at": "2026-09-03T15:20:14Z",
    "first_opened_at": null,
    "first_clicked_at": null,
    "bounced_at": null,
    "complained_at": null,
    "events": [
      { "type": "delivery", "at": "2026-09-03T15:20:14Z", "details": { "details": "smtp;250 2.0.0 OK" } }
    ]
  },
  "request_id": "…"
}
```

Hinweis: Verlauf 90 Tage, Zustand dauerhaft. Öffnungen und Klicks gibt es nur bei Newslettern — transaktionale Mails messen nichts. Die Zuordnung läuft über unsere Mail-ID, die als Postmark-Metadatum mitreist.

### 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.

#### 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:
- 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:
```
GET /v1/suppressions?since=2026-09-03T06:00:00Z&stream=newsletter
```

Response:
```json
{
  "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": "…"
}
```

Hinweis: 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:
- 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:
```
POST /v1/suppressions/lookup
{ "emails": ["max@example.com", "lena@example.com"] }
```

Response:
```json
{
  "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": "…"
}
```

Hinweis: 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:
- 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:
```
POST /v1/suppressions/reactivate
{ "email": "max@example.com" }
```

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

Hinweis: 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.

### Webhooks (geplant)
Zustellung von Ereignissen ans Kundenportal — geplant. Heute holt das Portal Job-Status (GET /v1/send-jobs/{id}), Mail-Status (GET /v1/messages/{id}) und Sperren (GET /v1/suppressions) ab; das reicht für Builder, Versand und Auswertung. Die Zustellung kommt später als Zusatz auf dieselben Daten: job.completed, message.bounced, suppression.changed. Die Registrierung einer URL ist schon möglich, die Zustellung noch nicht.

#### POST /v1/webhooks [geplant]
Registriert eine HTTPS-URL, an die später Ereignisse gepusht werden (job.completed, message.bounced, suppression.changed). Bis die Zustellung gebaut ist, holt das Portal Job-, Mail- und Sperrstatus ab. Die Antwort enthält EINMALIG ein signing_secret — damit jede Zustellung über den Header X-NewsletterKit-Signature verifiziert werden kann. Scope full.

Body-Parameter:
- url (string (URL), erforderlich): HTTPS-Endpunkt der Kundenplattform (http wird abgelehnt). (z. B. https://kunde.de/hooks/newsletterkit)
- events (string[], optional): Abonnierte Ereignisse: job.completed | message.bounced | suppression.changed. Default: ["job.completed"]. (z. B. ["job.completed","message.bounced"])

Request:
```
POST /v1/webhooks
{
  "url": "https://kunde.de/hooks/newsletterkit",
  "events": ["job.completed", "message.bounced"]
}
```

Response:
```json
{
  "data": {
    "id": "wh_5d33…",
    "url": "https://kunde.de/hooks/newsletterkit",
    "events": ["job.completed", "message.bounced"],
    "active": true,
    "signing_secret": "whsec_… (nur hier einmalig)"
  },
  "request_id": "…"
}
```

Hinweis: signing_secret wird nur in dieser Antwort zurückgegeben und ist danach nicht mehr abrufbar — sicher speichern. Zustellungen tragen die Header X-NewsletterKit-Event, X-NewsletterKit-Delivery (Dedup) und X-NewsletterKit-Signature: t=<unix>,v1=<hmac>. Verifikation: HMAC-SHA256 über "<t>.<roher Body>" mit dem signing_secret bilden und mit v1 vergleichen.

#### POST /api/postmark/webhook
Eingehender Endpunkt für Postmark-Events (Delivery, Open, Click, Bounce, SpamComplaint). Dieser Endpunkt ist KEIN API-Key-Endpunkt — er wird ausschließlich von Postmark aufgerufen und über eine Signatur/ein geheimes Token verifiziert. Aus den Events werden die aggregierten email_stats fortgeschrieben (PII-frei); Bounces/Complaints landen als gehashte Adresse im Suppression-Netz.

Body-Parameter:
- RecordType (string, erforderlich): Postmark-Event-Typ: Delivery | Open | Click | Bounce | SpamComplaint. (z. B. Delivery)
- MessageID (string, optional): Postmark-Message-ID zur Zuordnung zum Versand. (z. B. pm_abc123)
- Metadata (object, optional): Beim Versand mitgegebene Metadaten (message_id, customer_id, send_job_id) für die Zuordnung. (z. B. {"composition_id":"c0a8…"})

Request:
```
POST /api/postmark/webhook
{
  "RecordType": "Delivery",
  "MessageID": "pm_abc123",
  "Metadata": { "message_id": "128e7694-…", "customer_id": "1d17f761-…", "send_job_id": "f90c0326-…" }
}
```

Response:
```json
{ "ok": true }
```

Hinweis: Kein Bearer-API-Key: Authentizität wird über die Postmark-Signatur bzw. ein geheimes URL-Token sichergestellt. Wird vom Kunden nicht direkt aufgerufen — hier nur zur Vollständigkeit dokumentiert.