{"openapi":"3.1.0","info":{"title":"Newsletter API","version":"1.0.0","description":"Alle Funktionen der App. Auth: `Authorization: Bearer nl_…` (API-Key unter Einstellungen → API & MCP). MCP-Endpunkt: `/api/mcp`."},"servers":[{"url":"https://newsletter.baumanns.io/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"responses":{"Error":{"description":"Fehler","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Kampagne nicht gefunden"}}}}}}},"paths":{"/contacts":{"get":{"summary":"Kontakte suchen (q, listId, status, tag, limit, offset)","description":"Scope: `contacts:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Kontakt anlegen/aktualisieren (per E-Mail)","description":"Scope: `contacts:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"email":"max@example.com","firstName":"Max","listIds":["…"],"tags":["kunde"],"attributes":{"city":"Berlin"}}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/contacts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Kontakt inkl. Einwilligungen und Ereignissen","description":"Scope: `contacts:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Kontakt ändern","description":"Scope: `contacts:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Kontakt löschen (DSGVO)","description":"Scope: `contacts:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/contacts/{id}/unsubscribe":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Kontakt abmelden","description":"Scope: `contacts:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/contact-fields":{"get":{"summary":"Eigene Kontaktfelder","description":"Scope: `contacts:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Kontaktfeld anlegen (Admin)","description":"Scope: `contacts:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"label":"Branche","type":"select","options":["Handel","Industrie"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/contact-fields/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Kontaktfeld ändern (Bezeichnung, Optionen)","description":"Scope: `contacts:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Kontaktfeld löschen (?purgeValues=true löscht auch Werte)","description":"Scope: `contacts:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/mailboxes":{"get":{"summary":"Verbundene IMAP-Postfächer","description":"Scope: `inbox:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/mailboxes/{id}/sync":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Postfach sofort abrufen","description":"Scope: `inbox:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/forms":{"get":{"summary":"Formulare mit Statistik","description":"Scope: `forms:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Formular anlegen","description":"Scope: `forms:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Footer","listIds":["…"],"fields":[{"kind":"email","key":"email","label":"E-Mail","required":true}],"display":{"mode":"popup","trigger":"delay","delaySec":8}}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/lists/{id}/rules":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"put":{"summary":"Automatische Listenregeln setzen","description":"Scope: `lists:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"definition":{"match":"any","rules":[{"type":"field","field":"source","op":"eq","value":"form:…"}]},"applyToExisting":true}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/resend":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Nachfass-Kampagne an Nicht-Öffner als Entwurf","description":"Scope: `campaigns:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"subject":"Nicht verpassen: …"}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/lists":{"get":{"summary":"Listen","description":"Scope: `lists:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Liste anlegen","description":"Scope: `lists:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"VIP"}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Liste ändern","description":"Scope: `lists:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Liste löschen","description":"Scope: `lists:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/lists/{id}/contacts":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Kontakte hinzufügen (contactIds oder emails)","description":"Scope: `contacts:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"emails":["a@b.de"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Kontakte entfernen","description":"Scope: `contacts:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/segments":{"get":{"summary":"Segmente","description":"Scope: `lists:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Segment anlegen","description":"Scope: `lists:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Aktive","definition":{"match":"all","rules":[{"type":"engagement","event":"clicked","op":"within_days","days":90}]}}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/templates":{"get":{"summary":"Vorlagen (kind=marketing|transactional)","description":"Scope: `templates:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Vorlage anlegen","description":"Scope: `templates:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Bestellbestätigung","kind":"transactional","slug":"order-confirmation","subject":"Ihre Bestellung {{order.number}}","html":"<p>Danke {{first_name|}}!</p>"}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/templates/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Vorlage","description":"Scope: `templates:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Vorlage ändern","description":"Scope: `templates:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Vorlage löschen","description":"Scope: `templates:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns":{"get":{"summary":"Kampagnen","description":"Scope: `campaigns:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Entwurf anlegen","description":"Scope: `campaigns:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"November","subject":"Neu im November","listIds":["…"],"document":{"version":1,"blocks":[]}}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Kampagne + Varianten","description":"Scope: `campaigns:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Entwurf ändern, Varianten via variants[]","description":"Scope: `campaigns:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Kampagne löschen","description":"Scope: `campaigns:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/precheck":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Prüfung vor Versand (?links=1 prüft Links)","description":"Scope: `campaigns:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Testversand","description":"Scope: `campaigns:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"to":["ich@example.com"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/send":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Versand, zweistufig: ohne confirmationToken → Vorschau + Token","description":"Scope: `campaigns:send`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"scheduledAt":null,"confirmationToken":"…"}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/pause":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Pausieren","description":"Scope: `campaigns:send`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Abbrechen","description":"Scope: `campaigns:send`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/stats":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Statistik inkl. Links, Varianten, Verlauf","description":"Scope: `stats:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/recipients":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Empfänger mit Status (status, engagement)","description":"Scope: `stats:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/transactional/send":{"post":{"summary":"Transaktionsmail senden","description":"Scope: `transactional:send`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"template":"order-confirmation","to":"kunde@example.com","variables":{"order":{"number":"10023"}},"idempotencyKey":"order-10023"}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/inbox/threads":{"get":{"summary":"Postfach (status, category, q, mailboxId, folder, flagged, trash)","description":"Scope: `inbox:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/inbox/threads/{id}/action":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Gelesen/ungelesen, markieren, verschieben, Papierkorb, wiederherstellen (bei Abgleich auch im Postfach)","description":"Scope: `inbox:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"action":"move","folder":"INBOX/Kunden"}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/inbox/threads/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Konversation","description":"Scope: `inbox:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Status/Zuweisung ändern","description":"Scope: `inbox:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/inbox/threads/{id}/draft":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"KI-Antwortentwurf","description":"Scope: `inbox:read + ai:use`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/inbox/threads/{id}/reply":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Antwort senden, zweistufig","description":"Scope: `inbox:send`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"text":"Danke für Ihre Nachricht …","via":"mailbox","confirmationToken":"…"}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/ai/generate":{"post":{"summary":"Newsletter per KI erzeugen","description":"Scope: `ai:use`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"brief":"Neue Produkte im November","url":"https://shop.example.com/neu"}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/ai/subjects":{"post":{"summary":"Betreffzeilen vorschlagen","description":"Scope: `ai:use`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"content":"…","count":5}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/senders":{"get":{"summary":"Absender-Konten","description":"Scope: `senders:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/webhooks":{"get":{"summary":"Webhooks","description":"Scope: `webhooks:read`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Webhook anlegen (Secret wird einmalig angezeigt)","description":"Scope: `webhooks:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"url":"https://example.com/hook","events":["contact.unsubscribed","inbox.lead"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Webhook löschen","description":"Scope: `webhooks:write`","responses":{"200":{"description":"OK"},"4XX":{"$ref":"#/components/responses/Error"}}}}}}