{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "Persolz REST API", "version": "1.1.0", "summary": "CRM & E-Mail-Marketing mit Seinfeld-Mails, Seifenopern, Newslettern, KI und Webhooks.", "description": "Die Persolz-API (v1) gibt Dir Zugriff auf Kontakte, Listen, Versände, Seinfeld-Mails, Seifenopern, Vorlagen, Termine, KI und Webhooks.\n\n**Authentifizierung:** `Authorization: Bearer pz_live_…` oder `X-API-Key: pz_live_…`.\n\n**Antworten:** Erfolg `{\"data\": …, \"meta\": {…}}`, Fehler `{\"error\": {\"code\", \"message\", \"fields\"}}`.\n\n**Rate-Limit:** 120 Anfragen pro Minute je Schlüssel (Header X-RateLimit-*).\n\n**Idempotenz:** Header `Idempotency-Key` für POST.\n\n**Zeiten:** ISO 8601, Zeitzone Europe/Berlin.", "contact": { "name": "Persolz Support", "url": "https://persolz.com/kontakt" }, "termsOfService": "https://persolz.com/agb" }, "servers": [ { "url": "https://persolz.com/api/v1", "description": "Persolz API v1" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "System", "description": "API-Index und die OpenAPI-Beschreibung (öffentlich)." }, { "name": "Konto & Tarif", "description": "Dein Konto, Tarif, Limits, Verbrauch und KI-Guthaben." }, { "name": "E-Mail-Listen", "description": "Listen anlegen, ändern, löschen und Mitglieder verwalten." }, { "name": "Kontakte", "description": "Kontakte suchen, anlegen (Upsert per E-Mail), ändern, abmelden, Massenabgleich und Aktivitäten." }, { "name": "Abmeldungen", "description": "Gesperrte Adressen (Abmeldeliste) lesen, ergänzen und aufheben." }, { "name": "E-Mails", "description": "Einzel-E-Mails (z. B. Transaktions- oder Follow-up-Mails) versenden oder planen." }, { "name": "Newsletter", "description": "Newsletter als Entwurf anlegen, testen, versenden, planen und auswerten." }, { "name": "Seinfeld-Mails", "description": "Tägliche Story-Mails: Einstellungen, Themen, Entwürfe, Planung und KI-Generierung." }, { "name": "Seifenopern", "description": "Story-Sequenzen (Soap-Opera-Sequenzen): Tage, Teilnehmer, Aktivierung und KI-Gliederung." }, { "name": "Vorlagen", "description": "Vorlagen-Bibliothek und eigene E-Mail-Vorlagen." }, { "name": "Anhänge", "description": "Dateien in der Anhang-Cloud hochladen, auflisten und löschen." }, { "name": "SMTP-Server", "description": "Verbundene SMTP-Konten (ohne Passwörter) und Verbindungstest." }, { "name": "Kampagnen & Analytics", "description": "Alle Versände mit Status und Kennzahlen, Gesamtauswertung." }, { "name": "A/B-Tests", "description": "A/B-Tests anlegen, Ergebnisse lesen und den Gewinner festlegen." }, { "name": "Termine", "description": "Terminbuch: Termine anlegen, ändern und abfragen." }, { "name": "Posteingang", "description": "Verbundene IMAP-Postfächer: Mails lesen und sortieren, antworten, KI-Entwürfe schreiben lassen und freigeben, Kennzahlen abrufen." }, { "name": "KI", "description": "KI-Texte erzeugen und den KI-Verbrauch abfragen." }, { "name": "Webhooks", "description": "Webhooks verwalten, testen und Zustellungen einsehen." }, { "name": "Protokolle", "description": "Aktivitätsprotokoll und API-Protokoll Deines Kontos." }, { "name": "Öffentliche Anmeldung", "description": "Anmeldeformulare (z. B. aus Deinem Funnel) – ohne API-Schlüssel." }, { "name": "Integrationen", "description": "Zahlungsanbieter (Digistore24, CopeCart) übertragen Käufer automatisch in Persolz." } ], "paths": { "/": { "get": { "operationId": "system_index", "summary": "API-Index", "description": "Name, Version und Links zur Dokumentation und zur OpenAPI-Beschreibung. Ohne API-Schlüssel abrufbar.\n\nÖffentlich – kein API-Schlüssel nötig.", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "base_url": { "type": "string" }, "docs_url": { "type": "string" }, "openapi_url": { "type": "string" }, "time": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "name": "Persolz REST API", "version": "1.1.0", "base_url": "https://persolz.com/api/v1", "docs_url": "https://persolz.com/api-docs", "openapi_url": "https://persolz.com/api/v1/openapi.json", "time": "2026-10-09T14:05:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } } } } }, "/ab-tests": { "get": { "operationId": "abtests_list", "summary": "A/B-Tests auflisten", "description": "Alle A/B-Tests, aktive zuerst.\n\nBenötigter Scope: `read`. Tarif-Funktion: `ab_tests`.", "tags": [ "A/B-Tests" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "all | active | draft | running | completed | stopped", "schema": { "type": "string" }, "example": "active" }, { "name": "type", "in": "query", "required": false, "description": "newsletter | email | seinfeld | soap", "schema": { "type": "string" }, "example": "newsletter" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "integer" }, "test_type": { "type": "string" }, "mode": { "type": "string" }, "split_a": { "type": "integer" }, "sample_pct": { "type": "integer" }, "wait_hours": { "type": "integer" }, "winner_metric": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "winner": {}, "auto_apply_winner": { "type": "boolean" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variant": { "type": "string" }, "subject": { "type": "string" } }, "additionalProperties": true } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 21, "name": "Betreff-Test: Herbst-Aktion", "target_type": "newsletter", "target_id": 812, "test_type": "subject", "mode": "winner", "split_a": 50, "sample_pct": 20, "wait_hours": 4, "winner_metric": "clicks", "status": "running", "status_label": "Läuft", "winner": null, "auto_apply_winner": true, "variants": [ { "variant": "A", "subject": "Anna, das hier ist nur für Dich" }, { "variant": "B", "subject": "Dein Herbst-Bonus wartet" } ], "created_at": "2026-10-08T17:30:00+02:00", "updated_at": "2026-10-09T09:00:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "abtests_create", "summary": "A/B-Test anlegen", "description": "Legt einen Test für eine noch nicht versendete Mail an. Variante A = aktueller Inhalt, Variante B = Deine Änderungen (b_subject, b_preheader, b_html, b_from_name). Der Test startet mit dem Versand der Mail.\n\nBenötigter Scope: `write`. Tarif-Funktion: `ab_tests`. Unterstützt `Idempotency-Key`.", "tags": [ "A/B-Tests" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_type": { "type": "string", "description": "newsletter | email | seinfeld | soap (Pflicht, außer bei campaign_id)" }, "target_id": { "type": "integer", "description": "ID der Kampagne (newsletter/email), Seinfeld-Mail bzw. Seifenopern-Tag (Pflicht, außer bei campaign_id)." }, "campaign_id": { "type": "integer", "description": "Kurzform für Newsletter und E-Mails: statt target_type + target_id nur die Kampagnen-ID." }, "test_type": { "type": "string", "description": "subject | content | design | sender | combo" }, "name": { "type": "string", "description": "Name." }, "mode": { "type": "string", "description": "split (Aufteilen) | winner (Testgruppe, dann Gewinner an alle)" }, "split_a": { "type": "integer", "description": "Anteil Variante A in % (10–90)." }, "sample_pct": { "type": "integer", "description": "Bei winner: Testgruppe in % (5–50)." }, "wait_hours": { "type": "integer", "description": "Bei winner: Wartezeit bis zur Entscheidung (1–72 Std.)." }, "winner_metric": { "type": "string", "description": "clicks | opens | ctr" }, "auto_apply_winner": { "type": "boolean", "description": "Gewinner automatisch übernehmen." }, "b_subject": { "type": "string", "description": "Betreff der Variante B." }, "b_preheader": { "type": "string", "description": "Preheader B." }, "b_html": { "type": "string", "description": "Inhalt B." }, "b_from_name": { "type": "string", "description": "Absendername B." } }, "additionalProperties": true, "required": [ "target_type", "target_id", "test_type" ] }, "example": { "target_type": "newsletter", "target_id": 812, "test_type": "subject", "mode": "winner", "b_subject": "Dein Herbst-Bonus wartet" } } } }, "responses": { "201": { "description": "Angelegt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "status_label": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "integer" }, "test_type": { "type": "string" }, "mode": { "type": "string" }, "split_a": { "type": "integer" }, "sample_pct": { "type": "integer" }, "wait_hours": { "type": "integer" }, "winner_metric": { "type": "string" }, "winner": {}, "auto_apply_winner": { "type": "boolean" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variant": { "type": "string" }, "subject": { "type": "string" } }, "additionalProperties": true } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "draft", "status_label": "Bereit", "id": 21, "name": "Betreff-Test: Herbst-Aktion", "target_type": "newsletter", "target_id": 812, "test_type": "subject", "mode": "winner", "split_a": 50, "sample_pct": 20, "wait_hours": 4, "winner_metric": "clicks", "winner": null, "auto_apply_winner": true, "variants": [ { "variant": "A", "subject": "Anna, das hier ist nur für Dich" }, { "variant": "B", "subject": "Dein Herbst-Bonus wartet" } ], "created_at": "2026-10-08T17:30:00+02:00", "updated_at": "2026-10-09T09:00:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ab-tests/{id}": { "get": { "operationId": "abtests_get", "summary": "A/B-Test abrufen", "description": "Test mit Varianten und Ergebnissen (Versand, Öffnungen, Klicks, Signifikanz).\n\nBenötigter Scope: `read`. Tarif-Funktion: `ab_tests`.", "tags": [ "A/B-Tests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "integer" }, "test_type": { "type": "string" }, "mode": { "type": "string" }, "split_a": { "type": "integer" }, "sample_pct": { "type": "integer" }, "wait_hours": { "type": "integer" }, "winner_metric": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "winner": {}, "auto_apply_winner": { "type": "boolean" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variant": { "type": "string" }, "subject": { "type": "string" } }, "additionalProperties": true } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "results": { "type": "object", "properties": { "metric": { "type": "string" }, "variants": { "type": "object", "properties": { "A": { "type": "object", "properties": { "sent": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" } }, "additionalProperties": true }, "B": { "type": "object", "properties": { "sent": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "confidence": { "type": "number" }, "leader": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 21, "name": "Betreff-Test: Herbst-Aktion", "target_type": "newsletter", "target_id": 812, "test_type": "subject", "mode": "winner", "split_a": 50, "sample_pct": 20, "wait_hours": 4, "winner_metric": "clicks", "status": "running", "status_label": "Läuft", "winner": null, "auto_apply_winner": true, "variants": [ { "variant": "A", "subject": "Anna, das hier ist nur für Dich" }, { "variant": "B", "subject": "Dein Herbst-Bonus wartet" } ], "created_at": "2026-10-08T17:30:00+02:00", "updated_at": "2026-10-09T09:00:00+02:00", "results": { "metric": "clicks", "variants": { "A": { "sent": 125, "unique_opens": 70, "unique_clicks": 11 }, "B": { "sent": 125, "unique_opens": 78, "unique_clicks": 19 } }, "confidence": 0.91, "leader": "B" } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ab-tests/{id}/winner": { "post": { "operationId": "abtests_winner", "summary": "Gewinner festlegen", "description": "Legt den Gewinner fest (variant A/B) oder lässt ihn aus den Daten ermitteln (variant=auto). Wartende Empfänger erhalten danach den Gewinner. Möglich, sobald der Test läuft (also nach dem Versand der Mail).\n\nBenötigter Scope: `write`. Tarif-Funktion: `ab_tests`. Unterstützt `Idempotency-Key`.", "tags": [ "A/B-Tests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant": { "type": "string", "description": "A | B | auto", "enum": [ "A", "B", "auto" ] } }, "additionalProperties": true }, "example": { "variant": "B" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "winner": { "type": "string" }, "released": { "type": "integer" }, "copied": { "type": "boolean" }, "message": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "winner": "B", "released": 1000, "copied": false, "message": "Variante B ist der Gewinner. 1.000 wartende Empfänger bekommen jetzt Variante B." }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ai/generate": { "post": { "operationId": "ai_generate", "summary": "KI-Text erzeugen", "description": "Schreibt oder überarbeitet Texte mit der Persolz-KI (wie im Editor): improve, shorten, expand, subject_ideas (8 Betreffzeilen), preheader (3 Vorschläge), urgency, story, emotional, fix, translate_en, custom. Statt action kannst Du einfach „prompt“ senden (= custom). Verbraucht KI-Guthaben; 30 Anfragen pro Minute.\n\nBenötigter Scope: `ai`. Tarif-Funktion: `ai`. Unterstützt `Idempotency-Key`.", "tags": [ "KI" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "Aktion (siehe Beschreibung).", "enum": [ "improve", "shorten", "expand", "subject_ideas", "preheader", "urgency", "story", "emotional", "fix", "translate_en", "custom" ] }, "prompt": { "type": "string", "description": "Freie Anweisung (setzt action=custom)." }, "text": { "type": "string", "description": "Ausgangstext." }, "html": { "type": "string", "description": "Alternativ: HTML-Fragment (Struktur bleibt erhalten)." }, "instruction": { "type": "string", "description": "Zusätzlicher Wunsch." }, "subject": { "type": "string", "description": "Betreff als Kontext." }, "context": { "type": "string", "description": "Hintergrund (max. 4000 Zeichen)." }, "scope": { "type": "string", "description": "seinfeld | soap | newsletter | email (nutzt passende A/B-Erkenntnisse)." }, "model": { "type": "string", "description": "haiku (Standard, schnell) | sonnet (beste Qualität)" } }, "additionalProperties": true }, "example": { "action": "subject_ideas", "text": "Unser Herbst-Workshop findet am 20.10. statt – nur 12 Plätze.", "scope": "newsletter" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "text": { "type": "string" }, "html": {}, "data": { "type": "object", "properties": { "ideas": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "cost_eur": { "type": "number" }, "remaining_eur": { "type": "number" }, "model": { "type": "string" }, "provider": { "type": "string" }, "fallback_used": { "type": "boolean" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "action": "subject_ideas", "text": "Nur 12 Plätze: Dein Herbst-Workshop\n…", "html": null, "data": { "ideas": [ "Nur 12 Plätze: Dein Herbst-Workshop", "…" ] }, "cost_eur": 0.0012, "remaining_eur": 7.68, "model": "claude-haiku-5-5", "provider": "anthropic", "fallback_used": false }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/ai/usage": { "get": { "operationId": "ai_usage", "summary": "KI-Verbrauch", "description": "Guthaben, Verbrauch und Anfragen im laufenden Monat.\n\nBenötigter Scope: `read`.", "tags": [ "KI" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "credit": { "type": "number" }, "used": { "type": "number" }, "remaining": { "type": "number" }, "requests": { "type": "integer" }, "limit": { "type": "integer" }, "period": { "type": "string" }, "bonus": { "type": "number" }, "percent": { "type": "number" }, "allowed": { "type": "boolean" }, "configured": { "type": "boolean" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "credit": 10, "used": 2.31, "remaining": 7.69, "requests": 12, "limit": 0, "period": "2026-10", "bonus": 0, "percent": 23.1, "allowed": true, "configured": true }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/overview": { "get": { "operationId": "analytics_overview", "summary": "Analytics-Übersicht", "description": "Gesamtauswertung für einen Zeitraum: KPIs mit Vorperioden-Vergleich, Verlauf, Module, Geräte, Top-Links und Listenwachstum. Bots werden ausgeschlossen (bots=true schließt sie ein).\n\nBenötigter Scope: `read`.", "tags": [ "Kampagnen & Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start YYYY-MM-DD (Standard: vor 29 Tagen).", "schema": { "type": "string" }, "example": "2026-09-10" }, { "name": "to", "in": "query", "required": false, "description": "Ende YYYY-MM-DD (Standard: heute).", "schema": { "type": "string" }, "example": "2026-10-09" }, { "name": "type", "in": "query", "required": false, "description": "all | seinfeld | soap | newsletter | email", "schema": { "type": "string", "enum": [ "all", "seinfeld", "soap", "newsletter", "email" ] }, "example": "all" }, { "name": "bots", "in": "query", "required": false, "description": "Bot-Öffnungen/-Klicks einbeziehen.", "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "type": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": true }, "kpis": { "type": "object", "properties": { "sent": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "timeline": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" } }, "series": { "type": "array", "items": {} } }, "additionalProperties": true }, "modules": { "type": "array", "items": {} }, "devices": { "type": "array", "items": {} }, "links": { "type": "array", "items": {} }, "growth": { "type": "array", "items": {} } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "period": { "from": "2026-09-10", "to": "2026-10-09", "days": 30, "type": "all", "label": "letzte 30 Tage (10.09.–09.10.2026)" }, "kpis": { "sent": 8420, "unique_opens": 4630, "unique_clicks": 912, "unsubs": 21, "open_rate": 0.55, "click_rate": 0.108 }, "timeline": { "labels": [ "10.09.", "11.09." ], "series": [] }, "modules": [], "devices": [], "links": [], "growth": [] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api-logs": { "get": { "operationId": "logs_api", "summary": "API-Protokoll", "description": "Deine API-Anfragen (aller Schlüssel) mit Status, Dauer, Herkunft und Fehlermeldung. Aufbewahrung 90 Tage.\n\nBenötigter Scope: `read`.", "tags": [ "Protokolle" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "success (2xx/3xx) | error (≥ 400) oder ein exakter Code wie 422", "schema": { "type": "string" }, "example": "error" }, { "name": "method", "in": "query", "required": false, "description": "GET | POST | PUT | PATCH | DELETE", "schema": { "type": "string" }, "example": "POST" }, { "name": "key_id", "in": "query", "required": false, "description": "Nur Anfragen dieses Schlüssels.", "schema": { "type": "integer" }, "example": 5 }, { "name": "q", "in": "query", "required": false, "description": "Suche in Pfad, IP, Fehler.", "schema": { "type": "string" }, "example": "contacts" }, { "name": "from", "in": "query", "required": false, "description": "Ab Datum.", "schema": { "type": "string" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "Bis Datum.", "schema": { "type": "string" }, "example": "2026-10-09" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "method": { "type": "string" }, "endpoint": { "type": "string" }, "route": { "type": "string" }, "status_code": { "type": "integer" }, "duration_ms": { "type": "integer" }, "ip": { "type": "string" }, "origin": { "type": "string" }, "user_agent": { "type": "string" }, "error": {}, "request_id": { "type": "string" }, "key": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 3301, "method": "POST", "endpoint": "/api/v1/contacts", "route": "/api/v1/contacts", "status_code": 201, "duration_ms": 48, "ip": "203.0.113.7", "origin": "https://kartenherz.com", "user_agent": "Mozilla/5.0", "error": null, "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "key": { "id": 5, "name": "Funnel kartenherz.com", "prefix": "pz_live_AbCdEf" }, "created_at": "2026-10-09T14:05:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/appointments": { "get": { "operationId": "appointments_list", "summary": "Termine abfragen", "description": "Termine im Zeitraum (Standard: heute bis +30 Tage), sortiert nach Beginn.\n\nBenötigter Scope: `read`. Tarif-Funktion: `calendar`.", "tags": [ "Termine" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Ab (YYYY-MM-DD oder ISO 8601).", "schema": { "type": "string" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "Bis (max. 1 Jahr Spanne).", "schema": { "type": "string" }, "example": "2026-10-31" }, { "name": "status", "in": "query", "required": false, "description": "Nur dieser Status.", "schema": { "type": "string" }, "example": "planned" }, { "name": "contact_id", "in": "query", "required": false, "description": "Nur Termine dieses Kontakts.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "all_day": { "type": "boolean" }, "contact_id": { "type": "integer" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } }, "additionalProperties": true }, "attendees": { "type": "array", "items": { "type": "string" } }, "phone": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "reminder_minutes": { "type": "integer" }, "remind_attendees": { "type": "boolean" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 55, "title": "Erstgespräch Anna Schmidt", "description": "Kennenlernen per Video", "location": "Zoom", "start_at": "2026-10-14T10:00:00+02:00", "end_at": "2026-10-14T10:30:00+02:00", "all_day": false, "contact_id": 42, "contact": { "id": 42, "name": "Anna Schmidt", "email": "anna@beispiel.de", "phone": "+49 30 1234567" }, "attendees": [ "anna@beispiel.de" ], "phone": "", "color": "violet", "status": "planned", "status_label": "Geplant", "reminder_minutes": 60, "remind_attendees": true, "source": "api", "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "appointments_create", "summary": "Termin anlegen", "description": "Legt einen Termin an (Webhook appointment.created; Google-Kalender-Sync, falls verbunden).\n\nBenötigter Scope: `write`. Tarif-Funktion: `calendar`. Unterstützt `Idempotency-Key`.", "tags": [ "Termine" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Titel." }, "start_at": { "type": "string", "description": "Beginn (ISO 8601)." }, "end_at": { "type": "string", "description": "Ende (Standard: +1 Stunde)." }, "all_day": { "type": "boolean", "description": "Ganztägig." }, "description": { "type": "string", "description": "Beschreibung." }, "location": { "type": "string", "description": "Ort oder Link." }, "contact_id": { "type": "integer", "description": "Verknüpfter Kontakt." }, "attendee_emails": { "type": "array", "items": { "type": "string" }, "description": "Teilnehmer-Adressen." }, "phone": { "type": "string", "description": "Telefon." }, "color": { "type": "string", "description": "Farbe: violet, coral, mint, gold, blue, pink, green, lilac.", "enum": [ "violet", "coral", "mint", "gold", "blue", "pink", "green", "lilac" ] }, "reminder_minutes": { "type": "integer", "description": "Erinnerung x Minuten vorher (-1 = keine, 0 = zum Beginn, max. 40320)." }, "remind_attendees": { "type": "boolean", "description": "Auch Teilnehmer erinnern." }, "status": { "type": "string", "description": "planned | done | cancelled | no_show", "enum": [ "planned", "done", "cancelled", "no_show" ] } }, "additionalProperties": true, "required": [ "title", "start_at" ] }, "example": { "title": "Erstgespräch Anna Schmidt", "start_at": "2026-10-14T10:00:00+02:00", "end_at": "2026-10-14T10:30:00+02:00", "contact_id": 42, "location": "Zoom" } } } }, "responses": { "201": { "description": "Angelegt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "all_day": { "type": "boolean" }, "contact_id": { "type": "integer" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } }, "additionalProperties": true }, "attendees": { "type": "array", "items": { "type": "string" } }, "phone": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "reminder_minutes": { "type": "integer" }, "remind_attendees": { "type": "boolean" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 55, "title": "Erstgespräch Anna Schmidt", "description": "Kennenlernen per Video", "location": "Zoom", "start_at": "2026-10-14T10:00:00+02:00", "end_at": "2026-10-14T10:30:00+02:00", "all_day": false, "contact_id": 42, "contact": { "id": 42, "name": "Anna Schmidt", "email": "anna@beispiel.de", "phone": "+49 30 1234567" }, "attendees": [ "anna@beispiel.de" ], "phone": "", "color": "violet", "status": "planned", "status_label": "Geplant", "reminder_minutes": 60, "remind_attendees": true, "source": "api", "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/appointments/{id}": { "get": { "operationId": "appointments_get", "summary": "Termin abrufen", "description": "Ein Termin.\n\nBenötigter Scope: `read`. Tarif-Funktion: `calendar`.", "tags": [ "Termine" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "all_day": { "type": "boolean" }, "contact_id": { "type": "integer" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } }, "additionalProperties": true }, "attendees": { "type": "array", "items": { "type": "string" } }, "phone": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "reminder_minutes": { "type": "integer" }, "remind_attendees": { "type": "boolean" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 55, "title": "Erstgespräch Anna Schmidt", "description": "Kennenlernen per Video", "location": "Zoom", "start_at": "2026-10-14T10:00:00+02:00", "end_at": "2026-10-14T10:30:00+02:00", "all_day": false, "contact_id": 42, "contact": { "id": 42, "name": "Anna Schmidt", "email": "anna@beispiel.de", "phone": "+49 30 1234567" }, "attendees": [ "anna@beispiel.de" ], "phone": "", "color": "violet", "status": "planned", "status_label": "Geplant", "reminder_minutes": 60, "remind_attendees": true, "source": "api", "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "appointments_update", "summary": "Termin ändern", "description": "Ändert nur die übergebenen Felder (Webhook appointment.updated).\n\nBenötigter Scope: `write`. Tarif-Funktion: `calendar`.", "tags": [ "Termine" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Titel." }, "start_at": { "type": "string", "description": "Beginn (ISO 8601)." }, "end_at": { "type": "string", "description": "Ende (Standard: +1 Stunde)." }, "all_day": { "type": "boolean", "description": "Ganztägig." }, "description": { "type": "string", "description": "Beschreibung." }, "location": { "type": "string", "description": "Ort oder Link." }, "contact_id": { "type": "integer", "description": "Verknüpfter Kontakt." }, "attendee_emails": { "type": "array", "items": { "type": "string" }, "description": "Teilnehmer-Adressen." }, "phone": { "type": "string", "description": "Telefon." }, "color": { "type": "string", "description": "Farbe: violet, coral, mint, gold, blue, pink, green, lilac.", "enum": [ "violet", "coral", "mint", "gold", "blue", "pink", "green", "lilac" ] }, "reminder_minutes": { "type": "integer", "description": "Erinnerung x Minuten vorher (-1 = keine, 0 = zum Beginn, max. 40320)." }, "remind_attendees": { "type": "boolean", "description": "Auch Teilnehmer erinnern." }, "status": { "type": "string", "description": "planned | done | cancelled | no_show", "enum": [ "planned", "done", "cancelled", "no_show" ] } }, "additionalProperties": true, "required": [ "title", "start_at" ] }, "example": { "start_at": "2026-10-14T11:00:00+02:00", "end_at": "2026-10-14T11:30:00+02:00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "all_day": { "type": "boolean" }, "contact_id": { "type": "integer" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } }, "additionalProperties": true }, "attendees": { "type": "array", "items": { "type": "string" } }, "phone": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "reminder_minutes": { "type": "integer" }, "remind_attendees": { "type": "boolean" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 55, "title": "Erstgespräch Anna Schmidt", "description": "Kennenlernen per Video", "location": "Zoom", "start_at": "2026-10-14T10:00:00+02:00", "end_at": "2026-10-14T10:30:00+02:00", "all_day": false, "contact_id": 42, "contact": { "id": 42, "name": "Anna Schmidt", "email": "anna@beispiel.de", "phone": "+49 30 1234567" }, "attendees": [ "anna@beispiel.de" ], "phone": "", "color": "violet", "status": "planned", "status_label": "Geplant", "reminder_minutes": 60, "remind_attendees": true, "source": "api", "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "appointments_delete", "summary": "Termin löschen", "description": "Löscht den Termin.\n\nBenötigter Scope: `write`. Tarif-Funktion: `calendar`.", "tags": [ "Termine" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/attachments": { "get": { "operationId": "attachments_list", "summary": "Anhänge auflisten", "description": "Dateien der Anhang-Cloud mit Speicherverbrauch. Bilder (JPG, PNG, GIF, WebP) haben zusätzlich `image_url` (öffentliche, nicht erratbare Adresse für das `src`-Attribut von Bildern in E-Mails) sowie `width`/`height` in Pixeln – bei allen anderen Dateien (auch SVG) sind diese Felder `null`. Die Liste zeigt nur bereits vorhandene Bild-Links (ein widerrufener Link wird hier nicht neu erzeugt); `GET /attachments/{id}` erzeugt den Link bei Bedarf.\n\nBenötigter Scope: `read`. Tarif-Funktion: `attachments`.", "tags": [ "Anhänge" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Suche im Namen/in der Beschreibung.", "schema": { "type": "string" }, "example": "preis" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "size_human": { "type": "string" }, "mime": { "type": "string" }, "ext": { "type": "string" }, "group": { "type": "string" }, "is_default": { "type": "boolean" }, "description": { "type": "string" }, "image_url": {}, "width": {}, "height": {}, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 9, "name": "Preisliste-2026.pdf", "size": 182340, "size_human": "178,1 KB", "mime": "application/pdf", "ext": "pdf", "group": "document", "is_default": false, "description": "Aktuelle Preisliste", "image_url": null, "width": null, "height": null, "created_at": "2026-10-01T09:00:00+02:00" }, { "id": 12, "name": "Team-Foto.jpg", "size": 248112, "size_human": "242,3 KB", "mime": "image/jpeg", "ext": "jpg", "group": "image", "is_default": false, "description": "Unser Team im Sommer", "image_url": "https://persolz.com/i/3f9a2c7d1e5b4a60b8c9d0e1f2a3b4c5/team-foto.jpg", "width": 1200, "height": 800, "created_at": "2026-10-02T11:30:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 2, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "attachments_upload", "summary": "Anhang hochladen", "description": "Upload als multipart/form-data (Feld „file“) oder JSON {name, content_base64}. Erlaubt sind u. a. PDF, Bilder, Office-Dateien, TXT/CSV, ICS, ZIP, MP3 (max. 10 MB je Datei). Ausführbare Dateien werden abgelehnt. Bei Bildern (JPG, PNG, GIF, WebP) enthält die Antwort `image_url` – damit baust Du das Bild direkt ins HTML Deiner E-Mails ein (z. B. bei `POST /emails/send`).\n\nBenötigter Scope: `write`. Tarif-Funktion: `attachments`. Unterstützt `Idempotency-Key`.", "tags": [ "Anhänge" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "Die Datei (multipart)." }, "name": { "type": "string", "description": "JSON: Dateiname mit Endung." }, "content_base64": { "type": "string", "description": "JSON: Dateiinhalt Base64-kodiert." }, "description": { "type": "string", "description": "Beschreibung." }, "is_default": { "type": "boolean", "description": "Standard-Anhang (wird bei „Standard-Anhänge mitsenden“ angehängt)." } }, "additionalProperties": true }, "example": { "name": "Preisliste-2026.pdf", "content_base64": "JVBERi0xLjQK…", "description": "Aktuelle Preisliste" } }, "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "Die Datei (multipart)." }, "name": { "type": "string", "description": "JSON: Dateiname mit Endung." }, "content_base64": { "type": "string", "description": "JSON: Dateiinhalt Base64-kodiert." }, "description": { "type": "string", "description": "Beschreibung." }, "is_default": { "type": "boolean", "description": "Standard-Anhang (wird bei „Standard-Anhänge mitsenden“ angehängt)." } }, "additionalProperties": true }, "example": { "name": "Preisliste-2026.pdf", "content_base64": "JVBERi0xLjQK…", "description": "Aktuelle Preisliste" } } } }, "responses": { "201": { "description": "Hochgeladen", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "size_human": { "type": "string" }, "mime": { "type": "string" }, "ext": { "type": "string" }, "group": { "type": "string" }, "is_default": { "type": "boolean" }, "description": { "type": "string" }, "image_url": {}, "width": {}, "height": {}, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 9, "name": "Preisliste-2026.pdf", "size": 182340, "size_human": "178,1 KB", "mime": "application/pdf", "ext": "pdf", "group": "document", "is_default": false, "description": "Aktuelle Preisliste", "image_url": null, "width": null, "height": null, "created_at": "2026-10-01T09:00:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/attachments/{id}": { "get": { "operationId": "attachments_get", "summary": "Anhang abrufen", "description": "Metadaten eines Anhangs (ohne Dateiinhalt). Bei Bildern mit `image_url`, `width` und `height` – fehlt noch ein öffentlicher Bild-Link (z. B. nach dem Widerrufen), wird hier ein neuer, anderer Link erzeugt.\n\nBenötigter Scope: `read`. Tarif-Funktion: `attachments`.", "tags": [ "Anhänge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "size_human": { "type": "string" }, "mime": { "type": "string" }, "ext": { "type": "string" }, "group": { "type": "string" }, "is_default": { "type": "boolean" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 12, "name": "Team-Foto.jpg", "size": 248112, "size_human": "242,3 KB", "mime": "image/jpeg", "ext": "jpg", "group": "image", "is_default": false, "description": "Unser Team im Sommer", "image_url": "https://persolz.com/i/3f9a2c7d1e5b4a60b8c9d0e1f2a3b4c5/team-foto.jpg", "width": 1200, "height": 800, "created_at": "2026-10-02T11:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "attachments_delete", "summary": "Anhang löschen", "description": "Löscht die Datei. In bereits geplanten Mails wird sie übersprungen; ist sie als Bild eingebaut, liefert ihre `image_url` danach 404.\n\nBenötigter Scope: `write`. Tarif-Funktion: `attachments`.", "tags": [ "Anhänge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/campaigns": { "get": { "operationId": "campaigns_list", "summary": "Kampagnen auflisten", "description": "Alle Versände (Newsletter, E-Mails, Seinfeld-Mails, Seifenopern-Tage) mit Status und Kennzahlen.\n\nBenötigter Scope: `read`.", "tags": [ "Kampagnen & Analytics" ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "email | newsletter | seinfeld | soap", "schema": { "type": "string", "enum": [ "email", "newsletter", "seinfeld", "soap" ] }, "example": "newsletter" }, { "name": "status", "in": "query", "required": false, "description": "draft | scheduled | queued | sending | sent | paused | cancelled | failed | active", "schema": { "type": "string" }, "example": "sent" }, { "name": "q", "in": "query", "required": false, "description": "Suche in Name/Betreff.", "schema": { "type": "string" }, "example": "herbst" }, { "name": "created_after", "in": "query", "required": false, "description": "Angelegt nach.", "schema": { "type": "string" }, "example": "2026-10-01" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "audience_label": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "ab_test_id": {}, "scheduled_at": {}, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 812, "type": "newsletter", "type_label": "Newsletter", "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "preheader": "Nur bis Sonntag: Dein Herbst-Bonus", "status": "sent", "status_label": "Gesendet", "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "audience_label": "1 Liste", "smtp_account_id": 1, "attachment_ids": [], "include_default_attachments": false, "track_opens": true, "track_clicks": true, "ab_test_id": null, "scheduled_at": null, "started_at": "2026-10-09T09:00:00+02:00", "finished_at": "2026-10-09T09:04:31+02:00", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "unique_opens": 702, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066 }, "created_at": "2026-10-08T17:20:00+02:00", "updated_at": "2026-10-09T09:04:31+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/campaigns/{id}": { "get": { "operationId": "campaigns_get", "summary": "Kampagne abrufen", "description": "Eine Kampagne mit Kennzahlen (HTML mit ?include=html).\n\nBenötigter Scope: `read`.", "tags": [ "Kampagnen & Analytics" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "include", "in": "query", "required": false, "description": "html = HTML-Inhalt mitliefern", "schema": { "type": "string" }, "example": "html" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "audience_label": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "ab_test_id": {}, "scheduled_at": {}, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "type": "newsletter", "type_label": "Newsletter", "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "preheader": "Nur bis Sonntag: Dein Herbst-Bonus", "status": "sent", "status_label": "Gesendet", "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "audience_label": "1 Liste", "smtp_account_id": 1, "attachment_ids": [], "include_default_attachments": false, "track_opens": true, "track_clicks": true, "ab_test_id": null, "scheduled_at": null, "started_at": "2026-10-09T09:00:00+02:00", "finished_at": "2026-10-09T09:04:31+02:00", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "unique_opens": 702, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066 }, "created_at": "2026-10-08T17:20:00+02:00", "updated_at": "2026-10-09T09:04:31+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/campaigns/{id}/stats": { "get": { "operationId": "campaigns_stats", "summary": "Kampagnen-Statistik", "description": "Detaillierte Zahlen und Quoten einer Kampagne, Top-Links und Geräteverteilung.\n\nBenötigter Scope: `read`.", "tags": [ "Kampagnen & Analytics" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "status": { "type": "string" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "held": { "type": "integer" }, "skipped": { "type": "integer" }, "cancelled": { "type": "integer" }, "opens": { "type": "integer" }, "unique_opens": { "type": "integer" }, "clicks": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "ctor": { "type": "number" }, "unsub_rate": { "type": "number" }, "bounce_rate": { "type": "number" }, "failed_rate": { "type": "number" }, "progress": { "type": "number" } }, "additionalProperties": true }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string" }, "clicks": { "type": "integer" }, "unique_clicks": { "type": "integer" } }, "additionalProperties": true } }, "devices": { "type": "object", "properties": { "desktop": { "type": "integer" }, "mobile": { "type": "integer" }, "tablet": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "type": "newsletter", "status": "sent", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "pending": 0, "held": 0, "skipped": 0, "cancelled": 0, "opens": 980, "unique_opens": 702, "clicks": 190, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066, "ctor": 0.1895, "unsub_rate": 0.0024, "bounce_rate": 0.0016, "failed_rate": 0.0016, "progress": 1 }, "links": [ { "url": "https://kartenherz.com/angebot", "label": "Jetzt ansehen", "clicks": 140, "unique_clicks": 118 } ], "devices": { "desktop": 312, "mobile": 365, "tablet": 25 } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts": { "get": { "operationId": "contacts_list", "summary": "Kontakte suchen", "description": "Kontakte mit Listen, gefiltert und sortiert. Für eine Synchronisation eignet sich updated_after + sort=updated_asc.\n\nBenötigter Scope: `read`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "email", "in": "query", "required": false, "description": "Exakte E-Mail-Adresse.", "schema": { "type": "string" }, "example": "anna@beispiel.de" }, { "name": "q", "in": "query", "required": false, "description": "Suche in Name, E-Mail, Telefon, Ort, PLZ.", "schema": { "type": "string" }, "example": "schmidt" }, { "name": "list_id", "in": "query", "required": false, "description": "Nur Mitglieder dieser Liste.", "schema": { "type": "integer" }, "example": 3 }, { "name": "status", "in": "query", "required": false, "description": "subscribed | pending | unsubscribed | bounced", "schema": { "type": "string", "enum": [ "subscribed", "pending", "unsubscribed", "bounced" ] }, "example": "subscribed" }, { "name": "tag", "in": "query", "required": false, "description": "Nur Kontakte mit diesem Tag.", "schema": { "type": "string" }, "example": "funnel" }, { "name": "source", "in": "query", "required": false, "description": "Herkunft: manual, import, form, api, digistore, copecart …", "schema": { "type": "string" }, "example": "api" }, { "name": "created_after", "in": "query", "required": false, "description": "Angelegt nach (ISO 8601 oder YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2026-10-01" }, { "name": "updated_after", "in": "query", "required": false, "description": "Geändert nach (ISO 8601).", "schema": { "type": "string" }, "example": "2026-10-09T00:00:00+02:00" }, { "name": "sort", "in": "query", "required": false, "description": "created_desc (Standard) | created_asc | updated_desc | updated_asc | email_asc | name_asc", "schema": { "type": "string", "enum": [ "created_desc", "created_asc", "updated_desc", "updated_asc", "email_asc", "name_asc" ] }, "example": "created_desc" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "status": "subscribed", "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ] } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "contacts_upsert", "summary": "Kontakt anlegen oder aktualisieren (Upsert)", "description": "Legt einen Kontakt an oder aktualisiert ihn anhand der E-Mail-Adresse (nur übergebene, nicht leere Werte werden übernommen, Tags ergänzt, Listen hinzugefügt). Double-Opt-in-Listen lösen eine Bestätigungsmail aus (Status pending). Optional startet soap_sequence_id eine Seifenoper (nur für aktive Kontakte). 201 = neu angelegt, 200 = aktualisiert.\n\nBenötigter Scope: `write`. Unterstützt `Idempotency-Key`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "E-Mail-Adresse (eindeutig je Konto, wird kleingeschrieben)." }, "first_name": { "type": "string", "description": "Vorname (Alias: vorname, firstName)." }, "last_name": { "type": "string", "description": "Nachname (Alias: nachname, lastName)." }, "name": { "type": "string", "description": "Voller Name – wird aufgeteilt, wenn Vor-/Nachname fehlen." }, "phone": { "type": "string", "description": "Telefon." }, "address": { "type": "string", "description": "Straße und Hausnummer." }, "zip": { "type": "string", "description": "PLZ." }, "city": { "type": "string", "description": "Ort." }, "note": { "type": "string", "description": "Notiz (max. 5000 Zeichen)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags (Array oder kommagetrennt). Beim Upsert werden Tags ergänzt." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Eigene Felder (max. 50 Schlüssel a–z, 0–9, _ und -) – auch als Platzhalter {{schluessel}} nutzbar." }, "status": { "type": "string", "description": "subscribed | pending | unsubscribed. Abgemeldete Adressen werden nur mit consent=true reaktiviert.", "enum": [ "subscribed", "pending", "unsubscribed" ] }, "list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Listen, in die der Kontakt aufgenommen wird (Double-Opt-in der Liste wird beachtet). Aliase: lists (IDs oder Listen-Objekte wie in der Antwort), list_id." }, "consent": { "type": "boolean", "description": "Bestätigt eine neue Einwilligung (nötig, um abgemeldete Kontakte wieder anzumelden)." }, "doi": { "type": "boolean", "description": "Erzwingt eine Bestätigungsmail (Double-Opt-in), auch wenn die Liste es nicht verlangt." }, "soap_sequence_id": { "type": "integer", "description": "Seifenoper, in die der Kontakt aufgenommen wird." }, "soap_start_date": { "type": "string", "description": "Startdatum der Seifenoper (YYYY-MM-DD, Standard heute)." } }, "additionalProperties": true, "required": [ "email" ] }, "example": { "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "tags": [ "funnel" ], "list_ids": [ 3 ], "custom_fields": { "kundennummer": "K-1001" }, "soap_sequence_id": 7 } } } }, "responses": { "200": { "description": "Bereits vorhanden – aktualisiert", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } }, "result": { "type": "object", "properties": { "created": { "type": "boolean" }, "updated": { "type": "boolean" }, "status": { "type": "string" }, "doi_sent": { "type": "boolean" }, "message": {}, "soap_enrollment": { "type": "object", "properties": { "ok": { "type": "boolean" }, "enrollment_id": { "type": "integer" }, "error": {} }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "201": { "description": "Angelegt (200 bei Aktualisierung)", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } }, "result": { "type": "object", "properties": { "created": { "type": "boolean" }, "updated": { "type": "boolean" }, "status": { "type": "string" }, "doi_sent": { "type": "boolean" }, "message": {}, "soap_enrollment": { "type": "object", "properties": { "ok": { "type": "boolean" }, "enrollment_id": { "type": "integer" }, "error": {} }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "status": "subscribed", "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ], "result": { "created": true, "updated": false, "status": "subscribed", "doi_sent": false, "message": null, "soap_enrollment": { "ok": true, "enrollment_id": 501, "error": null } } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/bulk": { "post": { "operationId": "contacts_bulk", "summary": "Massenabgleich (max. 1000)", "description": "action=upsert: bis zu 1000 Kontakte anlegen/aktualisieren (optional in list_ids, mit tags). action=delete: Kontakte per ids oder emails löschen. Automationen (Seifenopern, Webhooks) laufen nur mit run_automations=true.\n\nBenötigter Scope: `write`. Unterstützt `Idempotency-Key`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "upsert | delete", "enum": [ "upsert", "delete" ] }, "contacts": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Für upsert: Kontakte (Felder wie POST /contacts)." }, "ids": { "type": "array", "items": { "type": "integer" }, "description": "Für delete: Kontakt-IDs." }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Für delete: E-Mail-Adressen." }, "list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Für upsert: Listen für alle Kontakte." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Für upsert: Tags für alle Kontakte." }, "duplicate": { "type": "string", "description": "Für upsert: update (Standard) oder skip für bestehende Adressen.", "enum": [ "update", "skip" ] }, "run_automations": { "type": "boolean", "description": "Webhooks und Listen-Automationen auslösen (Standard false)." } }, "additionalProperties": true, "required": [ "action" ] }, "example": { "action": "upsert", "list_ids": [ 3 ], "tags": [ "messe-2026" ], "contacts": [ { "email": "a@beispiel.de", "first_name": "Alex" }, { "email": "b@beispiel.de", "vorname": "Bea" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" }, "unchanged": { "type": "integer" }, "failed": { "type": "integer" }, "errors": { "type": "array", "items": {} } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "action": "upsert", "created": 2, "updated": 0, "skipped": 0, "unchanged": 0, "failed": 0, "errors": [] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/lookup": { "get": { "operationId": "contacts_lookup", "summary": "Kontakt per E-Mail finden", "description": "Liefert den Kontakt zur E-Mail-Adresse oder 404.\n\nBenötigter Scope: `read`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "email", "in": "query", "required": false, "description": "E-Mail-Adresse.", "schema": { "type": "string" }, "example": "anna@beispiel.de" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "status": "subscribed", "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/{id}": { "get": { "operationId": "contacts_get", "summary": "Kontakt abrufen", "description": "Ein Kontakt mit Listen, Engagement-Kennzahlen und Seifenopern-Teilnahmen.\n\nBenötigter Scope: `read`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } }, "engagement": { "type": "object", "properties": { "sent": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "failed": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "last_activity_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "soap_enrollments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "sequence_name": { "type": "string" }, "status": { "type": "string" }, "current_position": { "type": "integer" }, "start_date": { "type": "string", "format": "date" } }, "additionalProperties": true } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "status": "subscribed", "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ], "engagement": { "sent": 14, "opened": 11, "clicked": 4, "failed": 0, "open_rate": 0.7857, "click_rate": 0.2857, "last_activity_at": "2026-10-09T14:06:12+02:00" }, "soap_enrollments": [ { "id": 501, "sequence_id": 7, "sequence_name": "Willkommen bei Kartenherz", "status": "active", "current_position": 2, "start_date": "2026-10-08" } ] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "contacts_update", "summary": "Kontakt ändern", "description": "Ändert nur die übergebenen Felder. list_ids gleicht die Listen exakt ab (nicht genannte Listen werden entfernt), add_list_ids / remove_list_ids ändern einzelne Mitgliedschaften. Zum Reaktivieren abgemeldeter Kontakte ist consent=true nötig.\n\nBenötigter Scope: `write`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "E-Mail-Adresse (eindeutig je Konto, wird kleingeschrieben)." }, "first_name": { "type": "string", "description": "Vorname (Alias: vorname, firstName)." }, "last_name": { "type": "string", "description": "Nachname (Alias: nachname, lastName)." }, "name": { "type": "string", "description": "Voller Name – wird aufgeteilt, wenn Vor-/Nachname fehlen." }, "phone": { "type": "string", "description": "Telefon." }, "address": { "type": "string", "description": "Straße und Hausnummer." }, "zip": { "type": "string", "description": "PLZ." }, "city": { "type": "string", "description": "Ort." }, "note": { "type": "string", "description": "Notiz (max. 5000 Zeichen)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags (Array oder kommagetrennt). Beim Upsert werden Tags ergänzt." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Eigene Felder (max. 50 Schlüssel a–z, 0–9, _ und -) – auch als Platzhalter {{schluessel}} nutzbar." }, "status": { "type": "string", "description": "subscribed | pending | unsubscribed. Abgemeldete Adressen werden nur mit consent=true reaktiviert.", "enum": [ "subscribed", "pending", "unsubscribed" ] }, "list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Listen, in die der Kontakt aufgenommen wird (Double-Opt-in der Liste wird beachtet). Aliase: lists (IDs oder Listen-Objekte wie in der Antwort), list_id." }, "consent": { "type": "boolean", "description": "Bestätigt eine neue Einwilligung (nötig, um abgemeldete Kontakte wieder anzumelden)." }, "doi": { "type": "boolean", "description": "Erzwingt eine Bestätigungsmail (Double-Opt-in), auch wenn die Liste es nicht verlangt." }, "add_list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Listen hinzufügen." }, "remove_list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Aus Listen entfernen." } }, "additionalProperties": true }, "example": { "first_name": "Anna-Lena", "tags": [ "funnel", "kundin" ], "add_list_ids": [ 4 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "status": "subscribed", "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "contacts_replace", "summary": "Kontakt ersetzen", "description": "Setzt alle Profilfelder neu: nicht übergebene Felder (Name, Adresse, Notiz, Tags, eigene Felder) werden geleert. „email“ ist Pflicht. Listen werden nur mit list_ids abgeglichen.\n\nBenötigter Scope: `write`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "E-Mail-Adresse (eindeutig je Konto, wird kleingeschrieben)." }, "first_name": { "type": "string", "description": "Vorname (Alias: vorname, firstName)." }, "last_name": { "type": "string", "description": "Nachname (Alias: nachname, lastName)." }, "name": { "type": "string", "description": "Voller Name – wird aufgeteilt, wenn Vor-/Nachname fehlen." }, "phone": { "type": "string", "description": "Telefon." }, "address": { "type": "string", "description": "Straße und Hausnummer." }, "zip": { "type": "string", "description": "PLZ." }, "city": { "type": "string", "description": "Ort." }, "note": { "type": "string", "description": "Notiz (max. 5000 Zeichen)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags (Array oder kommagetrennt). Beim Upsert werden Tags ergänzt." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Eigene Felder (max. 50 Schlüssel a–z, 0–9, _ und -) – auch als Platzhalter {{schluessel}} nutzbar." }, "status": { "type": "string", "description": "subscribed | pending | unsubscribed. Abgemeldete Adressen werden nur mit consent=true reaktiviert.", "enum": [ "subscribed", "pending", "unsubscribed" ] }, "list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Listen, in die der Kontakt aufgenommen wird (Double-Opt-in der Liste wird beachtet). Aliase: lists (IDs oder Listen-Objekte wie in der Antwort), list_id." }, "consent": { "type": "boolean", "description": "Bestätigt eine neue Einwilligung (nötig, um abgemeldete Kontakte wieder anzumelden)." }, "doi": { "type": "boolean", "description": "Erzwingt eine Bestätigungsmail (Double-Opt-in), auch wenn die Liste es nicht verlangt." } }, "additionalProperties": true, "required": [ "email" ] }, "example": { "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt-Berg", "city": "Hamburg" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "status": "subscribed", "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "contacts_delete", "summary": "Kontakt löschen", "description": "Löscht den Kontakt mit Listen-Mitgliedschaften und Seifenopern-Teilnahmen. Eine Abmeldung der Adresse bleibt als Sperre erhalten.\n\nBenötigter Scope: `write`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/{id}/activity": { "get": { "operationId": "contacts_activity", "summary": "Aktivitäten eines Kontakts", "description": "Zeitstrahl (neueste zuerst): erhaltene, geöffnete und geklickte Mails, Abmeldung, Seifenopern, Termine, Listen, Double-Opt-in – plus Engagement-Kennzahlen.\n\nBenötigter Scope: `read`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "limit", "in": "query", "required": false, "description": "Max. Einträge (1–200, Standard 80).", "schema": { "type": "integer" }, "example": 80 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "engagement": { "type": "object", "properties": { "sent": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "failed": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "last_activity_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "time": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "engagement": { "sent": 14, "opened": 11, "clicked": 4, "failed": 0, "open_rate": 0.7857, "click_rate": 0.2857, "last_activity_at": "2026-10-09T14:06:12+02:00" }, "items": [ { "type": "opened", "title": "E-Mail geöffnet", "body": "„Was mein Kaffeebecher über Marketing weiß“", "time": "2026-10-09T14:05:00+02:00" }, { "type": "list", "title": "Zur Liste „Kartenherz Funnel“ hinzugefügt", "body": "", "time": "2026-10-01T09:00:00+02:00" } ] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/{id}/resubscribe": { "post": { "operationId": "contacts_resubscribe", "summary": "Kontakt wieder anmelden", "description": "Hebt eine Abmeldung auf. Nur mit consent=true (Du bestätigst eine neue, nachweisbare Einwilligung). Mit doi=true wird stattdessen eine Bestätigungsmail gesendet.\n\nBenötigter Scope: `write`. Unterstützt `Idempotency-Key`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "consent": { "type": "boolean", "description": "Neue Einwilligung liegt vor." }, "doi": { "type": "boolean", "description": "Statt sofortiger Anmeldung eine Bestätigungsmail senden." } }, "additionalProperties": true, "required": [ "consent" ] }, "example": { "consent": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "status": "subscribed", "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/{id}/unsubscribe": { "post": { "operationId": "contacts_unsubscribe", "summary": "Kontakt abmelden", "description": "Meldet den Kontakt ab: Die Adresse wird gesperrt, offene Versände und Seifenopern werden gestoppt (Webhook contact.unsubscribed).\n\nBenötigter Scope: `write`. Unterstützt `Idempotency-Key`.", "tags": [ "Kontakte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Grund (optional, max. 500 Zeichen)." } }, "additionalProperties": true }, "example": { "reason": "Wunsch per Telefon" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "unsubscribed", "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/emails": { "get": { "operationId": "emails_list", "summary": "E-Mails auflisten", "description": "Einzel-E-Mails (Kampagnen vom Typ email).\n\nBenötigter Scope: `read`. Tarif-Funktion: `email`.", "tags": [ "E-Mails" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "all | sent | scheduled | drafts", "schema": { "type": "string", "enum": [ "all", "sent", "scheduled", "drafts" ] }, "example": "all" }, { "name": "q", "in": "query", "required": false, "description": "Suche in Betreff/Name.", "schema": { "type": "string" }, "example": "bestellung" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "audience_label": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "ab_test_id": {}, "scheduled_at": {}, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 812, "type": "email", "type_label": "E-Mail", "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "preheader": "Nur bis Sonntag: Dein Herbst-Bonus", "status": "sent", "status_label": "Gesendet", "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "audience_label": "1 Liste", "smtp_account_id": 1, "attachment_ids": [], "include_default_attachments": false, "track_opens": true, "track_clicks": true, "ab_test_id": null, "scheduled_at": null, "started_at": "2026-10-09T09:00:00+02:00", "finished_at": "2026-10-09T09:04:31+02:00", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "unique_opens": 702, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066 }, "created_at": "2026-10-08T17:20:00+02:00", "updated_at": "2026-10-09T09:04:31+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/emails/send": { "post": { "operationId": "emails_send", "summary": "E-Mail senden oder planen", "description": "Versendet eine E-Mail an einzelne Adressen, Kontakte oder Listen – sofort oder geplant (scheduled_at). Inhalt als html, text oder aus einer Vorlage (template_key aus der Bibliothek bzw. template_id einer eigenen Vorlage). Platzhalter wie {{vorname}} werden je Empfänger ersetzt, „placeholders“ ersetzt zusätzlich eigene Platzhalter für alle Empfänger. Abgemeldete und unbestätigte Kontakte werden automatisch ausgeschlossen. Antwort 202: die Mail ist in der Warteschlange (Kampagnen-ID zum Nachverfolgen).\n\nBenötigter Scope: `send`. Tarif-Funktion: `email`. Unterstützt `Idempotency-Key`.", "tags": [ "E-Mails" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Empfänger: eine E-Mail, kommagetrennte E-Mails, ein Array aus E-Mails und/oder Kontakt-IDs." }, "list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Zusätzlich alle aktiven Mitglieder dieser Listen." }, "subject": { "type": "string", "description": "Betreff (Pflicht, außer die Vorlage liefert einen). Platzhalter erlaubt." }, "html": { "type": "string", "description": "HTML-Inhalt (max. 2 MB)." }, "text": { "type": "string", "description": "Alternativ: reiner Text (wird in eine schlichte HTML-Mail verpackt)." }, "template_key": { "type": "string", "description": "Bibliotheks-Vorlage, z. B. email-07." }, "template_id": { "type": "integer", "description": "Eigene Vorlage." }, "preheader": { "type": "string", "description": "Vorschautext." }, "placeholders": { "type": "object", "additionalProperties": true, "description": "Eigene Platzhalter für alle Empfänger, z. B. {\"bestellnummer\":\"4711\"} → {{bestellnummer}}." }, "smtp_account_id": { "type": "integer", "description": "SMTP-Konto (Standard: Modul- bzw. Standardkonto)." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge aus der Anhang-Cloud." }, "include_default_attachments": { "type": "boolean", "description": "Standard-Anhänge mitsenden (Standard false)." }, "scheduled_at": { "type": "string", "description": "Geplanter Versand (ISO 8601, max. 1 Jahr). Leer = sofort." }, "name": { "type": "string", "description": "Interner Name (Standard: Betreff)." }, "from_name": { "type": "string", "description": "Abweichender Absendername." }, "reply_to": { "type": "string", "description": "Abweichende Antwort-Adresse." }, "track_opens": { "type": "boolean", "description": "Öffnungen messen (Standard true)." }, "track_clicks": { "type": "boolean", "description": "Klicks messen (Standard true)." } }, "additionalProperties": true, "required": [ "to", "subject" ] }, "example": { "to": [ "anna@beispiel.de" ], "subject": "Deine Bestellung #{{bestellnummer}}", "html": "

Hallo {{vorname|Freund}},

danke für Deine Bestellung {{bestellnummer}}!

", "placeholders": { "bestellnummer": "4711" }, "attachment_ids": [ 9 ] } } } }, "responses": { "202": { "description": "In der Warteschlange bzw. geplant", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "status": { "type": "string" }, "scheduled_at": {}, "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "campaign_id": 813, "status": "sending", "scheduled_at": null, "recipients": 1, "queued": 1, "sent": 1, "failed": 0, "message": "Versand abgeschlossen: 1 E-Mail verschickt." }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/emails/{id}": { "get": { "operationId": "emails_get", "summary": "E-Mail abrufen", "description": "Eine E-Mail inklusive HTML und Versandstatistik.\n\nBenötigter Scope: `read`. Tarif-Funktion: `email`.", "tags": [ "E-Mails" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "audience_label": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "ab_test_id": {}, "scheduled_at": {}, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "html": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "type": "email", "type_label": "E-Mail", "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "preheader": "Nur bis Sonntag: Dein Herbst-Bonus", "status": "sent", "status_label": "Gesendet", "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "audience_label": "1 Liste", "smtp_account_id": 1, "attachment_ids": [], "include_default_attachments": false, "track_opens": true, "track_clicks": true, "ab_test_id": null, "scheduled_at": null, "started_at": "2026-10-09T09:00:00+02:00", "finished_at": "2026-10-09T09:04:31+02:00", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "unique_opens": 702, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066 }, "created_at": "2026-10-08T17:20:00+02:00", "updated_at": "2026-10-09T09:04:31+02:00", "html": "

Hallo {{vorname}} …

" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inbox/approvals": { "get": { "operationId": "inbox_approvals", "summary": "Freigaben auflisten", "description": "KI-Entwürfe mit Auszug der Originalmail und den Gründen, warum der Autopilot sie nicht selbst gesendet hat (reasons). status: pending (Standard – wartet auf Freigabe), scheduled (geplant, z. B. Autopilot in der Wartezeit), sent (von der KI geschrieben und gesendet), rejected, draft (Vorschläge „Antwort bereit“), all.\n\nBenötigter Scope: `read`. Tarif-Funktion: `inbox`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "pending | scheduled | sent | rejected | draft | all", "schema": { "type": "string", "enum": [ "pending", "scheduled", "sent", "rejected", "draft", "all" ] }, "example": "pending" }, { "name": "mailbox_id", "in": "query", "required": false, "description": "Nur dieses Postfach.", "schema": { "type": "integer" }, "example": 2 }, { "name": "q", "in": "query", "required": false, "description": "Suche in Betreff und Absender.", "schema": { "type": "string" }, "example": "hochzeit" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "reply_to_message_id": { "type": "integer" }, "thread_key": { "type": "string" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "bcc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "mail_attachment_ids": { "type": "array", "items": {} }, "send_at": {}, "sent_at": {}, "sent_message_id": {}, "error": {}, "ai": { "type": "object", "properties": { "model": { "type": "string" }, "confidence": { "type": "integer" }, "reason": { "type": "string" }, "flags": { "type": "array", "items": {} }, "flag_labels": { "type": "array", "items": {} }, "rating": {}, "edited": { "type": "boolean" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "reasons": { "type": "array", "items": {} }, "message": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "received_at": { "type": "string", "format": "date-time" }, "summary": { "type": "string" }, "category": { "type": "string" }, "category_label": { "type": "string" }, "priority": { "type": "string" }, "excerpt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 5502, "mailbox_id": 2, "kind": "reply", "kind_label": "Antwort", "status": "pending", "status_label": "Wartet auf Freigabe", "source": "ai", "reply_to_message_id": 9120, "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "to": [ { "email": "anna@beispiel.de", "name": "Anna Schmidt" } ], "cc": [], "bcc": [], "subject": "Re: Frage zu Hochzeitskarten", "html": "

Hallo Anna,

wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …

", "text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …", "attachment_ids": [], "mail_attachment_ids": [], "send_at": null, "sent_at": null, "sent_message_id": null, "error": null, "ai": { "model": "claude-sonnet-5-5", "confidence": 88, "reason": "Preis und Lieferzeit stehen im Wissen für die KI.", "flags": [], "flag_labels": [], "rating": null, "edited": false }, "created_at": "2026-10-09T14:06:10+02:00", "updated_at": "2026-10-09T14:06:10+02:00", "reasons": [], "message": { "id": 9120, "subject": "Frage zu Hochzeitskarten", "from": { "email": "anna@beispiel.de", "name": "Anna Schmidt" }, "received_at": "2026-10-09T14:05:00+02:00", "summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.", "category": "lead", "category_label": "Leads & Anfragen", "priority": "high", "excerpt": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung. Was kostet das und wie lange dauert die Lieferung?" } } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inbox/approvals/{id}/approve": { "post": { "operationId": "inbox_approve", "summary": "KI-Entwurf freigeben und senden", "description": "Gibt einen KI-Entwurf frei und sendet ihn sofort – optional mit Änderungen (subject, html/text, to, cc, bcc, attachment_ids). Deine Änderungen fließen als Erkenntnisse in künftige KI-Entwürfe ein.\n\nBenötigter Scope: `send`. Tarif-Funktion: `inbox`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Geänderter Betreff." }, "html": { "type": "string", "description": "Geänderter Text als HTML." }, "text": { "type": "string", "description": "Alternativ: geänderter reiner Text." }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Geänderte Empfänger." }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Kopie." }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Blindkopie." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge aus der Anhang-Cloud." } }, "additionalProperties": true }, "example": { "html": "

Hallo Anna,

herzlichen Glückwunsch! Ich schicke Dir gern Muster per Post …

" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "reply_to_message_id": { "type": "integer" }, "thread_key": { "type": "string" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "bcc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "mail_attachment_ids": { "type": "array", "items": {} }, "send_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": "string", "format": "date-time" }, "sent_message_id": {}, "error": {}, "ai": { "type": "object", "properties": { "model": { "type": "string" }, "confidence": { "type": "integer" }, "reason": { "type": "string" }, "flags": { "type": "array", "items": {} }, "flag_labels": { "type": "array", "items": {} }, "rating": {}, "edited": { "type": "boolean" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "reasons": { "type": "array", "items": {} }, "message": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "received_at": { "type": "string", "format": "date-time" }, "summary": { "type": "string" }, "category": { "type": "string" }, "category_label": { "type": "string" }, "priority": { "type": "string" }, "excerpt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 5502, "mailbox_id": 2, "kind": "reply", "kind_label": "Antwort", "status": "sent", "status_label": "Gesendet", "source": "ai", "reply_to_message_id": 9120, "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "to": [ { "email": "anna@beispiel.de", "name": "Anna Schmidt" } ], "cc": [], "bcc": [], "subject": "Re: Frage zu Hochzeitskarten", "html": "

Hallo Anna,

wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …

", "text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …", "attachment_ids": [], "mail_attachment_ids": [], "send_at": "2026-10-09T14:21:00+02:00", "sent_at": "2026-10-09T14:21:04+02:00", "sent_message_id": null, "error": null, "ai": { "model": "claude-sonnet-5-5", "confidence": 88, "reason": "Preis und Lieferzeit stehen im Wissen für die KI.", "flags": [], "flag_labels": [], "rating": null, "edited": true }, "created_at": "2026-10-09T14:06:10+02:00", "updated_at": "2026-10-09T14:06:10+02:00", "reasons": [], "message": { "id": 9120, "subject": "Frage zu Hochzeitskarten", "from": { "email": "anna@beispiel.de", "name": "Anna Schmidt" }, "received_at": "2026-10-09T14:05:00+02:00", "summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.", "category": "lead", "category_label": "Leads & Anfragen", "priority": "high", "excerpt": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung. Was kostet das und wie lange dauert die Lieferung?" } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/inbox/approvals/{id}/reject": { "post": { "operationId": "inbox_reject", "summary": "KI-Entwurf ablehnen", "description": "Lehnt einen KI-Entwurf ab. Typische Gründe („zu lang“, „falscher Ton“, „stimmt nicht“) werden zu Erkenntnissen für künftige Entwürfe.\n\nBenötigter Scope: `write`. Tarif-Funktion: `inbox`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Grund (optional, max. 250 Zeichen)." } }, "additionalProperties": true }, "example": { "reason": "Zu lang" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "reply_to_message_id": { "type": "integer" }, "thread_key": { "type": "string" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "bcc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "mail_attachment_ids": { "type": "array", "items": {} }, "send_at": {}, "sent_at": {}, "sent_message_id": {}, "error": {}, "ai": { "type": "object", "properties": { "model": { "type": "string" }, "confidence": { "type": "integer" }, "reason": { "type": "string" }, "flags": { "type": "array", "items": {} }, "flag_labels": { "type": "array", "items": {} }, "rating": {}, "edited": { "type": "boolean" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "reasons": { "type": "array", "items": {} }, "message": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "received_at": { "type": "string", "format": "date-time" }, "summary": { "type": "string" }, "category": { "type": "string" }, "category_label": { "type": "string" }, "priority": { "type": "string" }, "excerpt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 5502, "mailbox_id": 2, "kind": "reply", "kind_label": "Antwort", "status": "rejected", "status_label": "Abgelehnt", "source": "ai", "reply_to_message_id": 9120, "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "to": [ { "email": "anna@beispiel.de", "name": "Anna Schmidt" } ], "cc": [], "bcc": [], "subject": "Re: Frage zu Hochzeitskarten", "html": "

Hallo Anna,

wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …

", "text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …", "attachment_ids": [], "mail_attachment_ids": [], "send_at": null, "sent_at": null, "sent_message_id": null, "error": null, "ai": { "model": "claude-sonnet-5-5", "confidence": 88, "reason": "Preis und Lieferzeit stehen im Wissen für die KI.", "flags": [], "flag_labels": [], "rating": null, "edited": false }, "created_at": "2026-10-09T14:06:10+02:00", "updated_at": "2026-10-09T14:06:10+02:00", "reasons": [], "message": { "id": 9120, "subject": "Frage zu Hochzeitskarten", "from": { "email": "anna@beispiel.de", "name": "Anna Schmidt" }, "received_at": "2026-10-09T14:05:00+02:00", "summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.", "category": "lead", "category_label": "Leads & Anfragen", "priority": "high", "excerpt": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung. Was kostet das und wie lange dauert die Lieferung?" } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inbox/drafts": { "post": { "operationId": "inbox_createDraft", "summary": "Mail schreiben (Entwurf, senden oder planen)", "description": "Legt eine ausgehende Mail an und sendet sie sofort (Standard), zum Zeitpunkt send_at oder gar nicht (send=false → Entwurf). kind: new (neue Mail), reply / reply_all / forward (mit message_id – Empfänger, Betreff, Zitat und bei forward die Originalanhänge werden vorbelegt). Absender ist das Postfach (mailbox_id; bei message_id dessen Postfach).\n\nBenötigter Scope: `send`. Tarif-Funktion: `inbox`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "mailbox_id": { "type": "integer", "description": "Absender-Postfach (Pflicht ohne message_id)." }, "kind": { "type": "string", "description": "new (Standard), reply, reply_all oder forward.", "enum": [ "new", "reply", "reply_all", "forward" ] }, "message_id": { "type": "integer", "description": "Bezugsmail für reply, reply_all und forward." }, "subject": { "type": "string", "description": "Betreff (bei new Pflicht zum Senden)." }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Empfänger: E-Mail, kommagetrennte E-Mails („Name “ erlaubt) oder Liste aus E-Mails bzw. Objekten {email, name}." }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Kopie (wie to)." }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Blindkopie (wie to)." }, "html": { "type": "string", "description": "Inhalt als HTML (wird bereinigt; Skripte, Formulare & Co. werden entfernt). Signatur des Postfachs wird automatisch ergänzt." }, "text": { "type": "string", "description": "Alternativ: reiner Text (Links werden verlinkt)." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge aus der Anhang-Cloud (GET /attachments)." }, "send_at": { "type": "string", "description": "Später senden (ISO 8601, mind. 1 Minute, max. 1 Jahr in der Zukunft). Leer = sofort." }, "mail_attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "forward: Anhänge der Originalmail (Standard: alle)." }, "quote": { "type": "boolean", "description": "reply/forward: Original zitieren (Standard true)." }, "send": { "type": "boolean", "description": "false = nur als Entwurf speichern (Standard true)." } }, "additionalProperties": true }, "example": { "mailbox_id": 2, "to": [ "anna@beispiel.de" ], "subject": "Dein Angebot für Hochzeitskarten", "html": "

Hallo Anna,

anbei Dein Angebot …

", "attachment_ids": [ 9 ], "send_at": "2026-10-10T09:00:00+02:00" } } } }, "responses": { "201": { "description": "Angelegt (gesendet, geplant oder Entwurf)", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "reply_to_message_id": {}, "thread_key": { "type": "string" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "bcc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "attachment_ids": { "type": "array", "items": { "type": "integer" } }, "mail_attachment_ids": { "type": "array", "items": {} }, "send_at": { "type": "string", "format": "date-time" }, "sent_at": {}, "sent_message_id": {}, "error": {}, "ai": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 5502, "mailbox_id": 2, "kind": "new", "kind_label": "Neue Mail", "status": "scheduled", "status_label": "Geplant", "source": "user", "reply_to_message_id": null, "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "to": [ { "email": "anna@beispiel.de", "name": "Anna Schmidt" } ], "cc": [], "bcc": [], "subject": "Dein Angebot für Hochzeitskarten", "html": "

Hallo Anna,

wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …

", "text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …", "attachment_ids": [ 9 ], "mail_attachment_ids": [], "send_at": "2026-10-10T09:00:00+02:00", "sent_at": null, "sent_message_id": null, "error": null, "ai": null, "created_at": "2026-10-09T14:06:10+02:00", "updated_at": "2026-10-09T14:06:10+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/inbox/drafts/{id}": { "get": { "operationId": "inbox_draft", "summary": "Entwurf / ausgehende Mail abrufen", "description": "Status einer ausgehenden Mail: draft, pending (KI-Entwurf wartet auf Freigabe), scheduled (geplant oder im Rückgängig-Fenster), sending, sent, failed (error), rejected, cancelled.\n\nBenötigter Scope: `read`. Tarif-Funktion: `inbox`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "reply_to_message_id": { "type": "integer" }, "thread_key": { "type": "string" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "bcc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "mail_attachment_ids": { "type": "array", "items": {} }, "send_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": "string", "format": "date-time" }, "sent_message_id": { "type": "string" }, "error": {}, "ai": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 5502, "mailbox_id": 2, "kind": "reply", "kind_label": "Antwort", "status": "sent", "status_label": "Gesendet", "source": "user", "reply_to_message_id": 9120, "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "to": [ { "email": "anna@beispiel.de", "name": "Anna Schmidt" } ], "cc": [], "bcc": [], "subject": "Re: Frage zu Hochzeitskarten", "html": "

Hallo Anna,

wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …

", "text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …", "attachment_ids": [], "mail_attachment_ids": [], "send_at": "2026-10-09T14:21:00+02:00", "sent_at": "2026-10-09T14:21:04+02:00", "sent_message_id": "<6f1c0d9a2b7e4c1f@kartenherz.com>", "error": null, "ai": null, "created_at": "2026-10-09T14:06:10+02:00", "updated_at": "2026-10-09T14:06:10+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inbox/drafts/{id}/cancel": { "post": { "operationId": "inbox_cancelDraft", "summary": "Geplanten Versand stoppen", "description": "Stoppt eine geplante Mail (auch eine Autopilot-Antwort in der Wartezeit). Eigene Mails werden wieder Entwürfe, KI-Antworten landen wieder in den Freigaben. 409, wenn die Mail schon unterwegs ist.\n\nBenötigter Scope: `send`. Tarif-Funktion: `inbox`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "reply_to_message_id": { "type": "integer" }, "thread_key": { "type": "string" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "bcc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "mail_attachment_ids": { "type": "array", "items": {} }, "send_at": {}, "sent_at": {}, "sent_message_id": {}, "error": {}, "ai": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 5502, "mailbox_id": 2, "kind": "reply", "kind_label": "Antwort", "status": "draft", "status_label": "Entwurf", "source": "user", "reply_to_message_id": 9120, "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "to": [ { "email": "anna@beispiel.de", "name": "Anna Schmidt" } ], "cc": [], "bcc": [], "subject": "Re: Frage zu Hochzeitskarten", "html": "

Hallo Anna,

wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …

", "text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …", "attachment_ids": [], "mail_attachment_ids": [], "send_at": null, "sent_at": null, "sent_message_id": null, "error": null, "ai": null, "created_at": "2026-10-09T14:06:10+02:00", "updated_at": "2026-10-09T14:06:10+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inbox/drafts/{id}/send": { "post": { "operationId": "inbox_sendDraft", "summary": "Entwurf senden", "description": "Sendet einen Entwurf (auch einen fehlgeschlagenen oder gestoppten) sofort oder zum Zeitpunkt send_at. KI-Entwürfe gibst Du mit POST /inbox/approvals/{id}/approve frei.\n\nBenötigter Scope: `send`. Tarif-Funktion: `inbox`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_at": { "type": "string", "description": "Später senden (ISO 8601). Leer = sofort." } }, "additionalProperties": true }, "example": {} } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "reply_to_message_id": { "type": "integer" }, "thread_key": { "type": "string" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "bcc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "mail_attachment_ids": { "type": "array", "items": {} }, "send_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": "string", "format": "date-time" }, "sent_message_id": { "type": "string" }, "error": {}, "ai": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 5502, "mailbox_id": 2, "kind": "reply", "kind_label": "Antwort", "status": "sent", "status_label": "Gesendet", "source": "user", "reply_to_message_id": 9120, "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "to": [ { "email": "anna@beispiel.de", "name": "Anna Schmidt" } ], "cc": [], "bcc": [], "subject": "Re: Frage zu Hochzeitskarten", "html": "

Hallo Anna,

wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …

", "text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …", "attachment_ids": [], "mail_attachment_ids": [], "send_at": "2026-10-09T14:21:00+02:00", "sent_at": "2026-10-09T14:21:04+02:00", "sent_message_id": "<6f1c0d9a2b7e4c1f@kartenherz.com>", "error": null, "ai": null, "created_at": "2026-10-09T14:06:10+02:00", "updated_at": "2026-10-09T14:06:10+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/inbox/messages": { "get": { "operationId": "inbox_messages", "summary": "Mails auflisten", "description": "Mails aus dem Zwischenspeicher, neueste zuerst – ohne Inhalt (den liefert GET /inbox/messages/{id}?include_body=true). Ansichten wie in der App: focus (braucht eine Antwort, letzte 60 Tage), all (Posteingang), unread, flagged, waiting (Erinnerung gesetzt), snoozed (zurückgestellt), approvals (KI-Entwurf wartet), sent, archive, trash, spam, any (alle Ordner außer Papierkorb/Spam). has_ai_draft = es gibt eine KI-Antwort zur Freigabe oder als Vorschlag.\n\nBenötigter Scope: `read`. Tarif-Funktion: `inbox`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "view", "in": "query", "required": false, "description": "Ansicht (Standard all).", "schema": { "type": "string", "enum": [ "focus", "all", "unread", "flagged", "waiting", "snoozed", "approvals", "sent", "archive", "trash", "spam", "any" ] }, "example": "focus" }, { "name": "mailbox_id", "in": "query", "required": false, "description": "Nur dieses Postfach.", "schema": { "type": "integer" }, "example": 2 }, { "name": "folder_id", "in": "query", "required": false, "description": "Nur dieser Ordner (siehe GET /mailboxes/{id}); ersetzt view.", "schema": { "type": "integer" } }, { "name": "category", "in": "query", "required": false, "description": "KI-Kategorie, z. B. lead, customer, invoice, campaign_reply (Leser-Antworten).", "schema": { "type": "string", "enum": [ "lead", "customer", "appointment", "invoice", "order", "campaign_reply", "partner", "personal", "newsletter", "notification", "unsubscribe", "complaint", "spam", "other" ] }, "example": "lead" }, { "name": "q", "in": "query", "required": false, "description": "Suche in Betreff, Absender, Vorschau und Text.", "schema": { "type": "string" }, "example": "hochzeit" }, { "name": "contact_id", "in": "query", "required": false, "description": "Nur Mails dieses Kontakts.", "schema": { "type": "integer" }, "example": 42 }, { "name": "since", "in": "query", "required": false, "description": "Nur Mails, die ab diesem Zeitpunkt eingegangen sind (ISO 8601 oder YYYY-MM-DD) – ideal zum Abgleichen.", "schema": { "type": "string" }, "example": "2026-10-09T00:00:00+02:00" }, { "name": "label", "in": "query", "required": false, "description": "Nur Mails mit diesem Label.", "schema": { "type": "string" }, "example": "Hochzeit" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "mailbox_email": { "type": "string" }, "folder": { "type": "string" }, "folder_role": { "type": "string" }, "thread_key": { "type": "string" }, "message_id": { "type": "string" }, "direction": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "snippet": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "is_seen": { "type": "boolean" }, "is_flagged": { "type": "boolean" }, "is_answered": { "type": "boolean" }, "has_attachments": { "type": "boolean" }, "has_calendar": { "type": "boolean" }, "category": { "type": "string" }, "category_label": { "type": "string" }, "priority": { "type": "string" }, "sentiment": { "type": "string" }, "intent": { "type": "string" }, "summary": { "type": "string" }, "needs_reply": { "type": "boolean" }, "contact_id": { "type": "integer" }, "campaign_id": {}, "labels": { "type": "array", "items": { "type": "string" } }, "snoozed_until": {}, "follow_up_at": {}, "replied_at": {}, "has_ai_draft": { "type": "boolean" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 9120, "mailbox_id": 2, "mailbox_email": "hallo@kartenherz.com", "folder": "Posteingang", "folder_role": "inbox", "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "message_id": "", "direction": "in", "from": { "email": "anna@beispiel.de", "name": "Anna Schmidt" }, "to": [ { "email": "hallo@kartenherz.com", "name": "Kartenherz" } ], "cc": [], "subject": "Frage zu Hochzeitskarten", "snippet": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …", "received_at": "2026-10-09T14:05:00+02:00", "is_seen": false, "is_flagged": false, "is_answered": false, "has_attachments": false, "has_calendar": false, "category": "lead", "category_label": "Leads & Anfragen", "priority": "high", "sentiment": "positive", "intent": "Angebot für 80 Hochzeitskarten", "summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.", "needs_reply": true, "contact_id": 42, "campaign_id": null, "labels": [ "Hochzeit" ], "snoozed_until": null, "follow_up_at": null, "replied_at": null, "has_ai_draft": true } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inbox/messages/actions": { "post": { "operationId": "inbox_actions", "summary": "Mails bearbeiten (Massenaktion)", "description": "Dieselben Aktionen wie in der App, für bis zu 500 Mails auf einmal – Verschieben, Löschen und Markierungen werden auf den Mailserver übertragen. params: folder_id (move), until (snooze), at (follow_up = „Erinnern, falls keine Antwort kommt“), labels + mode set|add|remove (label), category (set_category). delete_forever löscht endgültig – auch auf dem Server.\n\nBenötigter Scope: `write`. Tarif-Funktion: `inbox`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs der Mails (max. 500)." }, "action": { "type": "string", "description": "Aktion.", "enum": [ "read", "unread", "flag", "unflag", "archive", "trash", "spam", "notspam", "move", "restore", "delete_forever", "snooze", "unsnooze", "follow_up", "clear_follow_up", "label", "set_category" ] }, "params": { "type": "object", "additionalProperties": true, "description": "Parameter der Aktion (siehe Beschreibung)." } }, "additionalProperties": true, "required": [ "ids", "action" ] }, "example": { "ids": [ 9120, 9121 ], "action": "snooze", "params": { "until": "2026-10-12T09:00:00+02:00" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "affected": { "type": "integer" }, "ids": { "type": "array", "items": { "type": "integer" } }, "not_found": { "type": "array", "items": {} }, "warning": {} }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "action": "snooze", "affected": 2, "ids": [ 9120, 9121 ], "not_found": [], "warning": null }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inbox/messages/{id}": { "get": { "operationId": "inbox_message", "summary": "Mail abrufen", "description": "Eine Mail mit Anhängen (Metadaten), KI-Auswertung (Aktionen, Risiken), Verlauf und Entwürfen. Mit include_body=true auch der Inhalt: text und html (bereits bereinigt – externe Bilder sind blockiert, solange images nicht true ist). Ist der Inhalt nicht mehr im Zwischenspeicher, wird er vom Mailserver geladen. Der Abruf markiert die Mail nicht als gelesen (dafür POST /inbox/messages/actions mit action=read).\n\nBenötigter Scope: `read`. Tarif-Funktion: `inbox`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "include_body", "in": "query", "required": false, "description": "Inhalt (text + html) mitliefern.", "schema": { "type": "boolean" }, "example": true }, { "name": "images", "in": "query", "required": false, "description": "Externe Bilder im HTML wiederherstellen (Vorsicht: Tracking-Pixel).", "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "mailbox_email": { "type": "string" }, "folder": { "type": "string" }, "folder_role": { "type": "string" }, "thread_key": { "type": "string" }, "message_id": { "type": "string" }, "direction": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "snippet": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "is_seen": { "type": "boolean" }, "is_flagged": { "type": "boolean" }, "is_answered": { "type": "boolean" }, "has_attachments": { "type": "boolean" }, "has_calendar": { "type": "boolean" }, "category": { "type": "string" }, "category_label": { "type": "string" }, "priority": { "type": "string" }, "sentiment": { "type": "string" }, "intent": { "type": "string" }, "summary": { "type": "string" }, "needs_reply": { "type": "boolean" }, "contact_id": { "type": "integer" }, "campaign_id": {}, "labels": { "type": "array", "items": { "type": "string" } }, "snoozed_until": {}, "follow_up_at": {}, "replied_at": {}, "ai": { "type": "object", "properties": { "status": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": true } }, "risk_flags": { "type": "array", "items": {} }, "risk_flag_labels": { "type": "array", "items": {} }, "language": { "type": "string" }, "confidence": { "type": "integer" } }, "additionalProperties": true }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "is_inline": { "type": "boolean" }, "content_id": {} }, "additionalProperties": true } }, "thread": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "direction": { "type": "string" }, "subject": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "received_at": { "type": "string", "format": "date-time" }, "snippet": { "type": "string" } }, "additionalProperties": true } }, "drafts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "subject": { "type": "string" }, "send_at": {} }, "additionalProperties": true } }, "body": { "type": "object", "properties": { "text": { "type": "string" }, "html": { "type": "string" }, "has_remote_images": { "type": "boolean" }, "missing": { "type": "boolean" }, "error": {} }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 9120, "mailbox_id": 2, "mailbox_email": "hallo@kartenherz.com", "folder": "Posteingang", "folder_role": "inbox", "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "message_id": "", "direction": "in", "from": { "email": "anna@beispiel.de", "name": "Anna Schmidt" }, "to": [ { "email": "hallo@kartenherz.com", "name": "Kartenherz" } ], "cc": [], "subject": "Frage zu Hochzeitskarten", "snippet": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …", "received_at": "2026-10-09T14:05:00+02:00", "is_seen": false, "is_flagged": false, "is_answered": false, "has_attachments": false, "has_calendar": false, "category": "lead", "category_label": "Leads & Anfragen", "priority": "high", "sentiment": "positive", "intent": "Angebot für 80 Hochzeitskarten", "summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.", "needs_reply": true, "contact_id": 42, "campaign_id": null, "labels": [ "Hochzeit" ], "snoozed_until": null, "follow_up_at": null, "replied_at": null, "ai": { "status": "done", "actions": [ { "key": "reply", "label": "Antwort entwerfen" }, { "key": "create_contact", "label": "Kontakt anlegen" } ], "risk_flags": [], "risk_flag_labels": [], "language": "de", "confidence": 92 }, "attachments": [ { "id": 301, "filename": "Wunschmotiv.jpg", "mime": "image/jpeg", "size": 184220, "is_inline": false, "content_id": null } ], "thread": [ { "id": 9120, "direction": "in", "subject": "Frage zu Hochzeitskarten", "from": { "email": "anna@beispiel.de", "name": "Anna Schmidt" }, "received_at": "2026-10-09T14:05:00+02:00", "snippet": "Hallo, wir heiraten im Mai …" } ], "drafts": [ { "id": 5502, "kind": "reply", "status": "pending", "source": "ai", "subject": "Re: Frage zu Hochzeitskarten", "send_at": null } ], "body": { "text": "Hallo,\n\nwir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …", "html": "

Hallo,

wir heiraten im Mai …

", "has_remote_images": false, "missing": false, "error": null } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inbox/messages/{id}/ai-draft": { "post": { "operationId": "inbox_aiDraft", "summary": "KI-Antwort entwerfen", "description": "Die KI schreibt eine Antwort im Stil des Postfachs (Ton, Wissen für die KI, Kontaktdaten, Anrede Du/Sie und Sprache des Absenders) – inklusive Selbsteinschätzung (confidence), Risiken und Begründung. Die Mail wird als nicht vertrauenswürdige Eingabe behandelt (Schutz vor Prompt-Injection). Ein unveränderter KI-Entwurf zur selben Mail wird ohne neue KI-Anfrage wiederverwendet (cached), außer bei fresh=true oder eigenen Vorgaben. save=draft speichert ihn als Vorschlag („Antwort bereit“), save=approval legt ihn in die Freigaben – senden mit POST /inbox/approvals/{id}/approve. Verbraucht KI-Guthaben.\n\nBenötigter Scope: `ai`. Tarif-Funktion: `inbox`, `ai`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "instruction": { "type": "string", "description": "Eigene Vorgabe (max. 600 Zeichen), z. B. „Biete einen Rückruf an“." }, "tone": { "type": "string", "description": "Ton: auto, freundlich, herzlich, locker, foermlich, sachlich, knapp." }, "length": { "type": "string", "description": "Länge: auto, kurz, mittel, lang." }, "include_slots": { "type": "boolean", "description": "Freie Termine aus dem Terminbuch vorschlagen." }, "model": { "type": "string", "description": "sonnet (Standard des Postfachs) oder haiku.", "enum": [ "sonnet", "haiku" ] }, "fresh": { "type": "boolean", "description": "Immer neu schreiben (keinen vorhandenen Entwurf wiederverwenden)." }, "save": { "type": "string", "description": "none (Standard), draft (Vorschlag speichern) oder approval (in die Freigaben).", "enum": [ "none", "draft", "approval" ] } }, "additionalProperties": true }, "example": { "tone": "herzlich", "instruction": "Biete Muster per Post an.", "save": "approval" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "confidence": { "type": "integer" }, "risk_flags": { "type": "array", "items": {} }, "risk_flag_labels": { "type": "array", "items": {} }, "needs_human": { "type": "boolean" }, "reason": { "type": "string" }, "language": { "type": "string" }, "form_of_address": { "type": "string" }, "slots": { "type": "array", "items": {} }, "model": { "type": "string" }, "cost_eur": { "type": "number" }, "cached": { "type": "boolean" }, "draft_id": { "type": "integer" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "subject": "Re: Frage zu Hochzeitskarten", "html": "

Hallo Anna,

herzlichen Glückwunsch! …

", "text": "Hallo Anna,\n\nherzlichen Glückwunsch! …", "confidence": 88, "risk_flags": [], "risk_flag_labels": [], "needs_human": false, "reason": "Preis und Lieferzeit stehen im Wissen für die KI.", "language": "de", "form_of_address": "du", "slots": [], "model": "claude-sonnet-5-5", "cost_eur": 0.0041, "cached": false, "draft_id": 5502 }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/inbox/messages/{id}/reply": { "post": { "operationId": "inbox_reply", "summary": "Auf eine Mail antworten", "description": "Antwortet über das Postfach der Mail (SMTP-Konto des Postfachs) – mit In-Reply-To/References, Signatur und zitiertem Original (quote=false lässt das Zitat weg). Empfänger und Betreff („Re: …“) werden wie in der App vorbelegt und können überschrieben werden; reply_all=true antwortet allen. Ohne send_at wird sofort gesendet; die Kopie landet im Ordner „Gesendet“. Schlägt der Versand fehl, antwortet die API mit 503 – der Entwurf bleibt (draft_id) und kann mit POST /inbox/drafts/{id}/send erneut gesendet werden.\n\nBenötigter Scope: `send`. Tarif-Funktion: `inbox`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "description": "Inhalt als HTML (wird bereinigt; Skripte, Formulare & Co. werden entfernt). Signatur des Postfachs wird automatisch ergänzt." }, "text": { "type": "string", "description": "Alternativ: reiner Text (Links werden verlinkt)." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge aus der Anhang-Cloud (GET /attachments)." }, "send_at": { "type": "string", "description": "Später senden (ISO 8601, mind. 1 Minute, max. 1 Jahr in der Zukunft). Leer = sofort." }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Empfänger: E-Mail, kommagetrennte E-Mails („Name “ erlaubt) oder Liste aus E-Mails bzw. Objekten {email, name}." }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Kopie (wie to)." }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Blindkopie (wie to)." }, "subject": { "type": "string", "description": "Betreff (Standard: „Re: “)." }, "reply_all": { "type": "boolean", "description": "Allen antworten (To + Cc der Mail, ohne Deine eigenen Adressen)." }, "quote": { "type": "boolean", "description": "Original zitieren (Standard true)." } }, "additionalProperties": true }, "example": { "html": "

Hallo Anna,

herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € und sind in 10 Tagen bei Dir.

Viele Grüße

" } } } }, "responses": { "201": { "description": "Gesendet bzw. geplant", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "reply_to_message_id": { "type": "integer" }, "thread_key": { "type": "string" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "cc": { "type": "array", "items": {} }, "bcc": { "type": "array", "items": {} }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "mail_attachment_ids": { "type": "array", "items": {} }, "send_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": "string", "format": "date-time" }, "sent_message_id": { "type": "string" }, "error": {}, "ai": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 5502, "mailbox_id": 2, "kind": "reply", "kind_label": "Antwort", "status": "sent", "status_label": "Gesendet", "source": "user", "reply_to_message_id": 9120, "thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b", "to": [ { "email": "anna@beispiel.de", "name": "Anna Schmidt" } ], "cc": [], "bcc": [], "subject": "Re: Frage zu Hochzeitskarten", "html": "

Hallo Anna,

wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …

", "text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …", "attachment_ids": [], "mail_attachment_ids": [], "send_at": "2026-10-09T14:21:00+02:00", "sent_at": "2026-10-09T14:21:04+02:00", "sent_message_id": "<6f1c0d9a2b7e4c1f@kartenherz.com>", "error": null, "ai": null, "created_at": "2026-10-09T14:06:10+02:00", "updated_at": "2026-10-09T14:06:10+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/inbox/stats": { "get": { "operationId": "inbox_stats", "summary": "Posteingang-Kennzahlen", "description": "Zähler wie in der App (Ansichten, Kategorien, Freigaben; badge = Zahl am Menüpunkt: ungelesen im Fokus + Freigaben), Status der Postfächer, eingegangene, gesendete und beantwortete Mails im Zeitraum sowie die KI-Statistik: Entwürfe, Freigaben, Bearbeitungs- und Freigabequote, Autopilot-Antworten, geschätzte gesparte Zeit und Entwürfe pro Tag.\n\nBenötigter Scope: `read`. Tarif-Funktion: `inbox`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Zeitraum in Tagen (1–365, Standard 30).", "schema": { "type": "integer" }, "example": 30 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "days": { "type": "integer" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "additionalProperties": true }, "mailboxes": { "type": "object", "properties": { "total": { "type": "integer" }, "ok": { "type": "integer" }, "error": { "type": "integer" }, "paused": { "type": "integer" }, "last_sync_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "views": { "type": "object", "properties": { "focus": { "type": "integer" }, "focus_unread": { "type": "integer" }, "all": { "type": "integer" }, "unread": { "type": "integer" }, "flagged": { "type": "integer" }, "waiting": { "type": "integer" }, "snoozed": { "type": "integer" }, "approvals": { "type": "integer" }, "scheduled": { "type": "integer" }, "failed": { "type": "integer" }, "drafts": { "type": "integer" }, "sent": { "type": "integer" }, "archive": { "type": "integer" }, "trash": { "type": "integer" }, "spam": { "type": "integer" } }, "additionalProperties": true }, "categories": { "type": "object", "properties": { "lead": { "type": "object", "properties": { "label": { "type": "string" }, "total": { "type": "integer" }, "unread": { "type": "integer" } }, "additionalProperties": true }, "campaign_reply": { "type": "object", "properties": { "label": { "type": "string" }, "total": { "type": "integer" }, "unread": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "approvals": { "type": "integer" }, "badge": { "type": "integer" }, "mails": { "type": "object", "properties": { "received": { "type": "integer" }, "sent": { "type": "integer" }, "replied": { "type": "integer" } }, "additionalProperties": true }, "ai": { "type": "object", "properties": { "drafts": { "type": "integer" }, "approved": { "type": "integer" }, "edited": { "type": "integer" }, "rejected": { "type": "integer" }, "auto_sent": { "type": "integer" }, "auto_planned": { "type": "integer" }, "pending": { "type": "integer" }, "thumbs_up": { "type": "integer" }, "thumbs_down": { "type": "integer" }, "approval_rate": { "type": "number" }, "edit_rate": { "type": "number" }, "avg_confidence": { "type": "integer" }, "triaged": { "type": "integer" }, "minutes_saved": { "type": "integer" }, "hours_saved": { "type": "number" }, "hours_saved_label": { "type": "string" }, "per_day": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "drafts": { "type": "integer" }, "auto": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "period": { "days": 30, "from": "2026-09-10", "to": "2026-10-09" }, "mailboxes": { "total": 2, "ok": 2, "error": 0, "paused": 0, "last_sync_at": "2026-10-09T14:05:00+02:00" }, "views": { "focus": 7, "focus_unread": 3, "all": 214, "unread": 5, "flagged": 4, "waiting": 2, "snoozed": 1, "approvals": 2, "scheduled": 1, "failed": 0, "drafts": 1, "sent": 96, "archive": 812, "trash": 12, "spam": 0 }, "categories": { "lead": { "label": "Leads & Anfragen", "total": 18, "unread": 2 }, "campaign_reply": { "label": "Leser-Antworten", "total": 9, "unread": 1 } }, "approvals": 2, "badge": 5, "mails": { "received": 320, "sent": 104, "replied": 87 }, "ai": { "drafts": 41, "approved": 33, "edited": 9, "rejected": 3, "auto_sent": 12, "auto_planned": 1, "pending": 2, "thumbs_up": 6, "thumbs_down": 1, "approval_rate": 0.9167, "edit_rate": 0.2727, "avg_confidence": 84, "triaged": 298, "minutes_saved": 462, "hours_saved": 7.7, "hours_saved_label": "ca. 7,7 Stunden", "per_day": [ { "date": "2026-10-08", "drafts": 3, "auto": 1 }, { "date": "2026-10-09", "drafts": 2, "auto": 0 } ] } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/integrations/copecart/{token}": { "post": { "operationId": "integrations_copecart", "summary": "CopeCart IPN", "description": "Empfänger für CopeCart-IPN (JSON). Ist ein IPN-Secret hinterlegt, wird der Header „X-Copecart-Signature“ (Base64-HMAC-SHA256 über den Body) geprüft. payment.made / payment.recurring übernehmen den Käufer als Kontakt (Liste + optional Seifenoper), payment.refunded / payment.charged_back / payment.failed / payment.recurring.cancelled setzen Tags.\n\nÖffentlich – kein API-Schlüssel nötig.", "tags": [ "Integrationen" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Dein persönlicher Integrations-Token.", "schema": { "type": "string" }, "example": "0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a" }, { "name": "X-Copecart-Signature", "in": "header", "required": false, "description": "Base64(HMAC-SHA256(Body, Secret)) – Pflicht, wenn ein Secret hinterlegt ist.", "schema": { "type": "string" }, "example": "k1R0…=" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "payment.made, payment.refunded, payment.charged_back, payment.failed, payment.recurring, payment.recurring.cancelled …" }, "buyer_email": { "type": "string", "description": "E-Mail des Käufers." }, "buyer_firstname": { "type": "string", "description": "Vorname." }, "buyer_lastname": { "type": "string", "description": "Nachname." }, "product_id": { "type": "string", "description": "Produkt-ID." }, "product_name": { "type": "string", "description": "Produktname." }, "order_id": { "type": "string", "description": "Bestell-ID." } }, "additionalProperties": true, "required": [ "event_type", "buyer_email" ] }, "example": { "event_type": "payment.made", "buyer_email": "anna@beispiel.de", "buyer_firstname": "Anna", "buyer_lastname": "Schmidt", "product_name": "Kartenset-Abo", "order_id": "CC-4711" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "received": { "type": "boolean" }, "action": { "type": "string" }, "contact_id": { "type": "integer" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "received": true, "action": "contact_upserted", "contact_id": 42 }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/integrations/digistore24/{token}": { "post": { "operationId": "integrations_digistore24", "summary": "Digistore24 IPN", "description": "Empfänger für die Digistore24-IPN (Instant Payment Notification). Trage die URL mit Deinem persönlichen Integrations-Token (siehe „API & Doku“ → Integrationen) in Digistore24 ein. Ist eine IPN-Passphrase hinterlegt, wird die Signatur „sha_sign“ geprüft. Zahlungsereignisse (on_payment, on_rebill_resumed) übernehmen den Käufer als Kontakt in die gewählte Liste (optional Start einer Seifenoper), on_refund / on_chargeback / on_payment_missed / on_rebill_cancelled setzen Tags. Antwort: „OK“ (text/plain).\n\nÖffentlich – kein API-Schlüssel nötig.", "tags": [ "Integrationen" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Dein persönlicher Integrations-Token.", "schema": { "type": "string" }, "example": "0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "event": { "type": "string", "description": "on_payment, on_refund, on_chargeback, on_payment_missed, on_rebill_resumed, on_rebill_cancelled, connection_test …" }, "email": { "type": "string", "description": "E-Mail des Käufers." }, "address_first_name": { "type": "string", "description": "Vorname." }, "address_last_name": { "type": "string", "description": "Nachname." }, "product_id": { "type": "string", "description": "Produkt-ID." }, "product_name": { "type": "string", "description": "Produktname." }, "order_id": { "type": "string", "description": "Bestell-ID." }, "sha_sign": { "type": "string", "description": "Signatur (SHA-512 über die sortierten Parameter + Passphrase)." } }, "additionalProperties": true, "required": [ "event", "email" ] }, "example": { "event": "on_payment", "email": "anna@beispiel.de", "address_first_name": "Anna", "address_last_name": "Schmidt", "product_id": "12345", "product_name": "Kartenset-Abo", "order_id": "ABCD1234" } } } }, "responses": { "200": { "description": "text/plain „OK“", "content": { "text/plain": { "schema": { "type": "string" }, "example": "OK" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/lists": { "get": { "operationId": "lists_list", "summary": "Listen auflisten", "description": "Alle E-Mail-Listen mit Mitgliederzahlen je Status (subscribed, pending, unsubscribed, bounced, total), dem öffentlichen Anmelde-Token und der Anmelde-URL.\n\nBenötigter Scope: `read`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Suche im Namen.", "schema": { "type": "string" }, "example": "funnel" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "double_optin": { "type": "boolean" }, "welcome_soap_id": { "type": "integer" }, "doi_redirect_url": { "type": "string" }, "redirect_domains": { "type": "array", "items": { "type": "string" } }, "public_token": { "type": "string" }, "subscribe_url": { "type": "string" }, "form_url": { "type": "string" }, "counts": { "type": "object", "properties": { "subscribed": { "type": "integer" }, "pending": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 3, "name": "Kartenherz Funnel", "description": "Leads aus dem Funnel auf kartenherz.com", "color": "#5B3DF5", "double_optin": true, "welcome_soap_id": 7, "doi_redirect_url": "https://kartenherz.com/danke", "redirect_domains": [ "kartenherz.com" ], "public_token": "9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "subscribe_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "form_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c/form", "counts": { "subscribed": 1180, "pending": 24, "unsubscribed": 41, "bounced": 5, "total": 1250 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "lists_create", "summary": "Liste anlegen", "description": "Legt eine neue Liste an. Im Free-Tarif ist nur eine Liste möglich (→ 402 limit_reached).\n\nBenötigter Scope: `write`. Unterstützt `Idempotency-Key`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name der Liste (eindeutig, max. 190 Zeichen)." }, "description": { "type": "string", "description": "Beschreibung (intern)." }, "color": { "type": "string", "description": "Farbe als Hex-Wert (#RRGGBB)." }, "double_optin": { "type": "boolean", "description": "Neue Anmeldungen über Formular/API müssen per Bestätigungsmail bestätigt werden." }, "welcome_soap_id": { "type": "integer", "description": "Seifenoper, die beim Eintrag automatisch startet (null = keine)." }, "doi_redirect_url": { "type": "string", "description": "Seite nach erfolgreicher Bestätigung (https://…)." }, "redirect_domains": { "type": "array", "items": {}, "description": "Erlaubte Weiterleitungs-Domains für success_url/error_url des öffentlichen Anmeldeformulars (inkl. Subdomains; Liste oder kommagetrennt, max. 20). Leer = jedes http(s)-Ziel ist erlaubt." } }, "additionalProperties": true, "required": [ "name" ] }, "example": { "name": "Kartenherz Funnel", "description": "Leads aus dem Funnel auf kartenherz.com", "double_optin": true, "welcome_soap_id": 7, "doi_redirect_url": "https://kartenherz.com/danke" } } } }, "responses": { "201": { "description": "Liste angelegt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "double_optin": { "type": "boolean" }, "welcome_soap_id": { "type": "integer" }, "doi_redirect_url": { "type": "string" }, "redirect_domains": { "type": "array", "items": { "type": "string" } }, "public_token": { "type": "string" }, "subscribe_url": { "type": "string" }, "form_url": { "type": "string" }, "counts": { "type": "object", "properties": { "subscribed": { "type": "integer" }, "pending": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 3, "name": "Kartenherz Funnel", "description": "Leads aus dem Funnel auf kartenherz.com", "color": "#5B3DF5", "double_optin": true, "welcome_soap_id": 7, "doi_redirect_url": "https://kartenherz.com/danke", "redirect_domains": [ "kartenherz.com" ], "public_token": "9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "subscribe_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "form_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c/form", "counts": { "subscribed": 1180, "pending": 24, "unsubscribed": 41, "bounced": 5, "total": 1250 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/lists/{id}": { "get": { "operationId": "lists_get", "summary": "Liste abrufen", "description": "Eine Liste mit Zahlen, Token und Anmelde-URLs.\n\nBenötigter Scope: `read`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "double_optin": { "type": "boolean" }, "welcome_soap_id": { "type": "integer" }, "doi_redirect_url": { "type": "string" }, "redirect_domains": { "type": "array", "items": { "type": "string" } }, "public_token": { "type": "string" }, "subscribe_url": { "type": "string" }, "form_url": { "type": "string" }, "counts": { "type": "object", "properties": { "subscribed": { "type": "integer" }, "pending": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 3, "name": "Kartenherz Funnel", "description": "Leads aus dem Funnel auf kartenherz.com", "color": "#5B3DF5", "double_optin": true, "welcome_soap_id": 7, "doi_redirect_url": "https://kartenherz.com/danke", "redirect_domains": [ "kartenherz.com" ], "public_token": "9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "subscribe_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "form_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c/form", "counts": { "subscribed": 1180, "pending": 24, "unsubscribed": 41, "bounced": 5, "total": 1250 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "lists_update", "summary": "Liste ändern", "description": "Ändert nur die übergebenen Felder.\n\nBenötigter Scope: `write`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name der Liste (eindeutig, max. 190 Zeichen)." }, "description": { "type": "string", "description": "Beschreibung (intern)." }, "color": { "type": "string", "description": "Farbe als Hex-Wert (#RRGGBB)." }, "double_optin": { "type": "boolean", "description": "Neue Anmeldungen über Formular/API müssen per Bestätigungsmail bestätigt werden." }, "welcome_soap_id": { "type": "integer", "description": "Seifenoper, die beim Eintrag automatisch startet (null = keine)." }, "doi_redirect_url": { "type": "string", "description": "Seite nach erfolgreicher Bestätigung (https://…)." }, "redirect_domains": { "type": "array", "items": {}, "description": "Erlaubte Weiterleitungs-Domains für success_url/error_url des öffentlichen Anmeldeformulars (inkl. Subdomains; Liste oder kommagetrennt, max. 20). Leer = jedes http(s)-Ziel ist erlaubt." } }, "additionalProperties": true }, "example": { "description": "Leads aus Funnel und Messe", "double_optin": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "double_optin": { "type": "boolean" }, "welcome_soap_id": { "type": "integer" }, "doi_redirect_url": { "type": "string" }, "redirect_domains": { "type": "array", "items": { "type": "string" } }, "public_token": { "type": "string" }, "subscribe_url": { "type": "string" }, "form_url": { "type": "string" }, "counts": { "type": "object", "properties": { "subscribed": { "type": "integer" }, "pending": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 3, "name": "Kartenherz Funnel", "description": "Leads aus dem Funnel auf kartenherz.com", "color": "#5B3DF5", "double_optin": true, "welcome_soap_id": 7, "doi_redirect_url": "https://kartenherz.com/danke", "redirect_domains": [ "kartenherz.com" ], "public_token": "9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "subscribe_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "form_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c/form", "counts": { "subscribed": 1180, "pending": 24, "unsubscribed": 41, "bounced": 5, "total": 1250 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "lists_replace", "summary": "Liste ersetzen", "description": "Setzt alle Felder neu (nicht übergebene optionale Felder werden geleert, double_optin wird false). „name“ ist Pflicht.\n\nBenötigter Scope: `write`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name der Liste (eindeutig, max. 190 Zeichen)." }, "description": { "type": "string", "description": "Beschreibung (intern)." }, "color": { "type": "string", "description": "Farbe als Hex-Wert (#RRGGBB)." }, "double_optin": { "type": "boolean", "description": "Neue Anmeldungen über Formular/API müssen per Bestätigungsmail bestätigt werden." }, "welcome_soap_id": { "type": "integer", "description": "Seifenoper, die beim Eintrag automatisch startet (null = keine)." }, "doi_redirect_url": { "type": "string", "description": "Seite nach erfolgreicher Bestätigung (https://…)." }, "redirect_domains": { "type": "array", "items": {}, "description": "Erlaubte Weiterleitungs-Domains für success_url/error_url des öffentlichen Anmeldeformulars (inkl. Subdomains; Liste oder kommagetrennt, max. 20). Leer = jedes http(s)-Ziel ist erlaubt." } }, "additionalProperties": true, "required": [ "name" ] }, "example": { "name": "Kartenherz Funnel", "description": "Leads aus dem Funnel auf kartenherz.com", "double_optin": true, "welcome_soap_id": 7, "doi_redirect_url": "https://kartenherz.com/danke" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "double_optin": { "type": "boolean" }, "welcome_soap_id": { "type": "integer" }, "doi_redirect_url": { "type": "string" }, "redirect_domains": { "type": "array", "items": { "type": "string" } }, "public_token": { "type": "string" }, "subscribe_url": { "type": "string" }, "form_url": { "type": "string" }, "counts": { "type": "object", "properties": { "subscribed": { "type": "integer" }, "pending": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 3, "name": "Kartenherz Funnel", "description": "Leads aus dem Funnel auf kartenherz.com", "color": "#5B3DF5", "double_optin": true, "welcome_soap_id": 7, "doi_redirect_url": "https://kartenherz.com/danke", "redirect_domains": [ "kartenherz.com" ], "public_token": "9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "subscribe_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c", "form_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c/form", "counts": { "subscribed": 1180, "pending": 24, "unsubscribed": 41, "bounced": 5, "total": 1250 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "lists_delete", "summary": "Liste löschen", "description": "Löscht die Liste. Kontakte bleiben erhalten – mit ?delete_contacts=true werden Kontakte gelöscht, die in keiner anderen Liste sind.\n\nBenötigter Scope: `write`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "delete_contacts", "in": "query", "required": false, "description": "Kontakte ohne andere Liste ebenfalls löschen.", "schema": { "type": "boolean" }, "example": false } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/lists/{id}/contacts": { "get": { "operationId": "lists_contacts", "summary": "Mitglieder einer Liste", "description": "Kontakte der Liste, filterbar nach Status und Suchbegriff.\n\nBenötigter Scope: `read`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "status", "in": "query", "required": false, "description": "subscribed | pending | unsubscribed | bounced", "schema": { "type": "string", "enum": [ "subscribed", "pending", "unsubscribed", "bounced" ] }, "example": "subscribed" }, { "name": "q", "in": "query", "required": false, "description": "Suche in Name, E-Mail, Telefon, Ort.", "schema": { "type": "string" }, "example": "anna" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" }, "note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "source": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "kundennummer": { "type": "string" } }, "additionalProperties": true }, "doi_confirmed_at": {}, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 42, "email": "anna@beispiel.de", "first_name": "Anna", "last_name": "Schmidt", "address": "Lindenweg 3", "zip": "10115", "city": "Berlin", "phone": "+49 30 1234567", "note": "Kam über den Kartenherz-Funnel", "tags": [ "funnel", "kartenherz" ], "status": "subscribed", "source": "api", "custom_fields": { "kundennummer": "K-1001" }, "doi_confirmed_at": null, "created_at": "2026-10-09T14:05:00+02:00", "updated_at": "2026-10-09T14:05:00+02:00", "lists": [ { "id": 3, "name": "Kartenherz Funnel", "color": "#5B3DF5" } ] } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "lists_addContacts", "summary": "Kontakte zur Liste hinzufügen", "description": "Fügt bestehende Kontakte (contact_ids) hinzu und/oder legt Kontakte per E-Mail an bzw. aktualisiert sie (contacts – Upsert, max. 1000). Bei Double-Opt-in-Listen erhalten neue Kontakte eine Bestätigungsmail. Automationen der Liste (Willkommens-Seifenoper) starten für aktive Kontakte.\n\nBenötigter Scope: `write`. Unterstützt `Idempotency-Key`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs bestehender Kontakte." }, "contacts": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Kontakte als Objekte (email Pflicht, weitere Felder wie bei POST /contacts)." } }, "additionalProperties": true }, "example": { "contact_ids": [ 42, 43 ], "contacts": [ { "email": "ben@beispiel.de", "first_name": "Ben", "tags": [ "messe" ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "errors": { "type": "array", "items": {} }, "list": { "type": "object", "properties": { "id": { "type": "integer" }, "counts": { "type": "object", "properties": { "subscribed": { "type": "integer" }, "pending": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "added": 2, "created": 1, "updated": 0, "skipped": 0, "failed": 0, "errors": [], "list": { "id": 3, "counts": { "subscribed": 1182, "pending": 25, "unsubscribed": 41, "bounced": 5, "total": 1253 } } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/lists/{id}/contacts/{contactId}": { "delete": { "operationId": "lists_removeContact", "summary": "Kontakt aus Liste entfernen", "description": "Entfernt die Mitgliedschaft (der Kontakt selbst bleibt erhalten).\n\nBenötigter Scope: `write`.", "tags": [ "E-Mail-Listen" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "contactId", "in": "path", "required": true, "description": "ID des Kontakts", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Entfernt" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/logs": { "get": { "operationId": "logs_list", "summary": "Aktivitätsprotokoll", "description": "Das Protokoll Deines Kontos (Versand, Kontakte, Automationen, Fehler …), neueste zuerst. Geheimnisse sind maskiert.\n\nBenötigter Scope: `read`.", "tags": [ "Protokolle" ], "parameters": [ { "name": "level", "in": "query", "required": false, "description": "debug | info | success | warning | error | critical | problems (= ab warning)", "schema": { "type": "string" }, "example": "problems" }, { "name": "channel", "in": "query", "required": false, "description": "Bereich, z. B. email, newsletter, soap, contacts, smtp, api", "schema": { "type": "string" }, "example": "smtp" }, { "name": "q", "in": "query", "required": false, "description": "Volltextsuche.", "schema": { "type": "string" }, "example": "zustellung" }, { "name": "from", "in": "query", "required": false, "description": "Ab Datum YYYY-MM-DD.", "schema": { "type": "string" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "Bis Datum YYYY-MM-DD.", "schema": { "type": "string" }, "example": "2026-10-09" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "level": { "type": "string" }, "channel": { "type": "string" }, "message": { "type": "string" }, "context": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "sent": { "type": "integer" } }, "additionalProperties": true }, "ip": {}, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 1201, "level": "success", "channel": "newsletter", "message": "Newsletter versendet: „Herbst-Aktion“", "context": { "campaign_id": 812, "sent": 1248 }, "ip": null, "created_at": "2026-10-09T09:04:31+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mailboxes": { "get": { "operationId": "mailboxes_list", "summary": "Postfächer auflisten", "description": "Alle verbundenen IMAP-Postfächer mit Status, letztem Abruf, ungelesenen Mails im Posteingang und den KI-Einstellungen. Passwörter werden nie ausgegeben.\n\nBenötigter Scope: `read`. Tarif-Funktion: `inbox`.", "tags": [ "Posteingang" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "email": { "type": "string" }, "display_name": { "type": "string" }, "color": { "type": "string" }, "provider": { "type": "string" }, "provider_name": { "type": "string" }, "imap_host": { "type": "string" }, "imap_port": { "type": "integer" }, "imap_encryption": { "type": "string" }, "imap_username": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "sync_enabled": { "type": "boolean" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "last_error": {}, "last_error_hint": {}, "last_sync_at": { "type": "string", "format": "date-time" }, "unread": { "type": "integer" }, "ai": { "type": "object", "properties": { "triage": { "type": "boolean" }, "mode": { "type": "string" }, "mode_label": { "type": "string" }, "model": { "type": "string" }, "auto_categories": { "type": "array", "items": { "type": "string" } }, "min_confidence": { "type": "integer" }, "disclosure": { "type": "boolean" }, "reply_delay_minutes": { "type": "integer" }, "daily_cap": { "type": "integer" }, "business_hours": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "from": { "type": "string" }, "to": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 2, "label": "Kartenherz Kundenservice", "email": "hallo@kartenherz.com", "display_name": "Kartenherz", "color": "#5B3DF5", "provider": "strato", "provider_name": "Strato", "imap_host": "imap.strato.de", "imap_port": 993, "imap_encryption": "ssl", "imap_username": "hallo@kartenherz.com", "smtp_account_id": 1, "sync_enabled": true, "status": "ok", "status_label": "Verbunden", "last_error": null, "last_error_hint": null, "last_sync_at": "2026-10-09T14:05:00+02:00", "unread": 3, "ai": { "triage": true, "mode": "approve", "mode_label": "Mit Freigabe – KI schreibt Antworten, Du gibst sie frei", "model": "sonnet", "auto_categories": [ "lead", "customer", "appointment" ], "min_confidence": 85, "disclosure": true, "reply_delay_minutes": 15, "daily_cap": 20, "business_hours": { "days": [ 1, 2, 3, 4, 5 ], "from": "08:00", "to": "18:00" } }, "created_at": "2026-10-01T09:00:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mailboxes/{id}": { "get": { "operationId": "mailboxes_get", "summary": "Postfach abrufen", "description": "Ein Postfach mit seinen Ordnern (Rolle, Synchronisation, ungelesen/gesamt im Zwischenspeicher).\n\nBenötigter Scope: `read`. Tarif-Funktion: `inbox`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "email": { "type": "string" }, "display_name": { "type": "string" }, "color": { "type": "string" }, "provider": { "type": "string" }, "provider_name": { "type": "string" }, "imap_host": { "type": "string" }, "imap_port": { "type": "integer" }, "imap_encryption": { "type": "string" }, "imap_username": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "sync_enabled": { "type": "boolean" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "last_error": {}, "last_error_hint": {}, "last_sync_at": { "type": "string", "format": "date-time" }, "unread": { "type": "integer" }, "ai": { "type": "object", "properties": { "triage": { "type": "boolean" }, "mode": { "type": "string" }, "mode_label": { "type": "string" }, "model": { "type": "string" }, "auto_categories": { "type": "array", "items": { "type": "string" } }, "min_confidence": { "type": "integer" }, "disclosure": { "type": "boolean" }, "reply_delay_minutes": { "type": "integer" }, "daily_cap": { "type": "integer" }, "business_hours": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "from": { "type": "string" }, "to": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "is_synced": { "type": "boolean" }, "unread": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 2, "label": "Kartenherz Kundenservice", "email": "hallo@kartenherz.com", "display_name": "Kartenherz", "color": "#5B3DF5", "provider": "strato", "provider_name": "Strato", "imap_host": "imap.strato.de", "imap_port": 993, "imap_encryption": "ssl", "imap_username": "hallo@kartenherz.com", "smtp_account_id": 1, "sync_enabled": true, "status": "ok", "status_label": "Verbunden", "last_error": null, "last_error_hint": null, "last_sync_at": "2026-10-09T14:05:00+02:00", "unread": 3, "ai": { "triage": true, "mode": "approve", "mode_label": "Mit Freigabe – KI schreibt Antworten, Du gibst sie frei", "model": "sonnet", "auto_categories": [ "lead", "customer", "appointment" ], "min_confidence": 85, "disclosure": true, "reply_delay_minutes": 15, "daily_cap": 20, "business_hours": { "days": [ 1, 2, 3, 4, 5 ], "from": "08:00", "to": "18:00" } }, "created_at": "2026-10-01T09:00:00+02:00", "folders": [ { "id": 11, "name": "INBOX", "display_name": "Posteingang", "role": "inbox", "is_synced": true, "unread": 3, "total": 214 }, { "id": 12, "name": "Gesendet", "display_name": "Gesendet", "role": "sent", "is_synced": true, "unread": 0, "total": 96 } ] }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mailboxes/{id}/sync": { "post": { "operationId": "mailboxes_sync", "summary": "Postfach jetzt abrufen", "description": "Ruft neue Mails sofort ab (statt auf den Cron zu warten; max. 15 Sekunden, große Postfächer werden in mehreren Läufen vollständig). Ohne KI-Funktion werden neue und noch nicht eingeordnete Mails dabei gleich regelbasiert sortiert (ohne KI-Kosten). Höchstens 8 Abrufe pro Minute.\n\nBenötigter Scope: `write`. Tarif-Funktion: `inbox`. Unterstützt `Idempotency-Key`.", "tags": [ "Posteingang" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "mailbox_id": { "type": "integer" }, "ok": { "type": "boolean" }, "new": { "type": "integer" }, "updated": { "type": "integer" }, "removed": { "type": "integer" }, "partial": { "type": "boolean" }, "busy": { "type": "boolean" }, "error": {}, "hint": {}, "duration_ms": { "type": "integer" }, "last_sync_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "mailbox_id": 2, "ok": true, "new": 4, "updated": 1, "removed": 0, "partial": false, "busy": false, "error": null, "hint": null, "duration_ms": 1830, "last_sync_at": "2026-10-09T14:05:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/me": { "get": { "operationId": "account_me", "summary": "Konto, Tarif & Verbrauch", "description": "Dein Konto, der aktive Tarif mit Limits und Funktionen, der aktuelle Verbrauch (Kontakte, Listen, Speicher, heutige Versände …), das KI-Guthaben und der verwendete API-Schlüssel.\n\nBenötigter Scope: `read`.", "tags": [ "Konto & Tarif" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "timezone": { "type": "string" }, "email_verified": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "plan": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "trial_days_left": { "type": "integer" }, "trial_ends_at": {}, "subscription_status": { "type": "string" } }, "additionalProperties": true }, "features": { "type": "object", "properties": { "ai": { "type": "boolean" }, "api": { "type": "boolean" }, "seinfeld": { "type": "boolean" }, "soap": { "type": "boolean" }, "newsletter": { "type": "boolean" }, "email": { "type": "boolean" }, "ab_tests": { "type": "boolean" }, "calendar": { "type": "boolean" } }, "additionalProperties": true }, "limits": { "type": "object", "properties": { "max_lists": { "type": "integer" }, "max_contacts": { "type": "integer" }, "emails_per_day": { "type": "integer" }, "storage_mb": { "type": "integer" } }, "additionalProperties": true }, "usage": { "type": "object", "properties": { "contacts": { "type": "integer" }, "lists": { "type": "integer" }, "soap_sequences": { "type": "integer" }, "smtp_accounts": { "type": "integer" }, "custom_templates": { "type": "integer" }, "storage_bytes": { "type": "integer" }, "active_ab_tests": { "type": "integer" }, "today": { "type": "object", "properties": { "email": { "type": "integer" }, "newsletter": { "type": "integer" }, "seinfeld": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "ai": { "type": "object", "properties": { "credit": { "type": "number" }, "used": { "type": "number" }, "remaining": { "type": "number" }, "requests": { "type": "integer" }, "limit": { "type": "integer" }, "period": { "type": "string" }, "allowed": { "type": "boolean" } }, "additionalProperties": true }, "api_key": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "account": { "id": 2, "email": "du@beispiel.de", "first_name": "Daniel", "last_name": "Scholz", "company": "Kartenherz", "timezone": "Europe/Berlin", "email_verified": true, "created_at": "2026-09-01T10:00:00+02:00" }, "plan": { "key": "pro", "label": "Pro", "trial_days_left": 0, "trial_ends_at": null, "subscription_status": "active" }, "features": { "ai": true, "api": true, "seinfeld": true, "soap": true, "newsletter": true, "email": true, "ab_tests": true, "calendar": true }, "limits": { "max_lists": -1, "max_contacts": -1, "emails_per_day": -1, "storage_mb": 2000 }, "usage": { "contacts": 1250, "lists": 3, "soap_sequences": 2, "smtp_accounts": 1, "custom_templates": 4, "storage_bytes": 5242880, "active_ab_tests": 1, "today": { "email": 3, "newsletter": 1, "seinfeld": 1 } }, "ai": { "credit": 10, "used": 2.31, "remaining": 7.69, "requests": 12, "limit": 0, "period": "2026-10", "allowed": true }, "api_key": { "id": 5, "name": "Funnel kartenherz.com", "prefix": "pz_live_AbCdEf", "scopes": [ "*" ], "rate_limit": 120 } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/newsletters": { "get": { "operationId": "newsletters_list", "summary": "Newsletter auflisten", "description": "Alle Newsletter mit Status und Kennzahlen.\n\nBenötigter Scope: `read`. Tarif-Funktion: `newsletter`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "all | drafts | scheduled | sent", "schema": { "type": "string", "enum": [ "all", "drafts", "scheduled", "sent" ] }, "example": "all" }, { "name": "q", "in": "query", "required": false, "description": "Suche in Betreff/Name.", "schema": { "type": "string" }, "example": "herbst" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "audience_label": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "ab_test_id": {}, "scheduled_at": {}, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 812, "type": "newsletter", "type_label": "Newsletter", "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "preheader": "Nur bis Sonntag: Dein Herbst-Bonus", "status": "sent", "status_label": "Gesendet", "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "audience_label": "1 Liste", "smtp_account_id": 1, "attachment_ids": [], "include_default_attachments": false, "track_opens": true, "track_clicks": true, "ab_test_id": null, "scheduled_at": null, "started_at": "2026-10-09T09:00:00+02:00", "finished_at": "2026-10-09T09:04:31+02:00", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "unique_opens": 702, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066 }, "created_at": "2026-10-08T17:20:00+02:00", "updated_at": "2026-10-09T09:04:31+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "newsletters_create", "summary": "Newsletter-Entwurf anlegen", "description": "Legt einen Newsletter als Entwurf an (es wird nichts versendet). Vollständigkeit (Betreff, Inhalt, Empfänger, SMTP) wird erst beim Versand geprüft.\n\nBenötigter Scope: `write`. Tarif-Funktion: `newsletter`. Unterstützt `Idempotency-Key`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Interner Name." }, "subject": { "type": "string", "description": "Betreff (zum Versand Pflicht)." }, "preheader": { "type": "string", "description": "Vorschautext." }, "html": { "type": "string", "description": "HTML-Inhalt." }, "text": { "type": "string", "description": "Alternativ reiner Text." }, "template_key": { "type": "string", "description": "Bibliotheks-Vorlage (übernimmt HTML, Betreff, Preheader, falls nicht angegeben)." }, "template_id": { "type": "integer", "description": "Eigene Vorlage." }, "audience": { "type": "object", "additionalProperties": true, "description": "Empfänger: {\"all\":false,\"lists\":[3],\"contacts\":[42],\"emails\":[\"x@y.de\"]}." }, "list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Kurzform für audience.lists." }, "smtp_account_id": { "type": "integer", "description": "SMTP-Konto." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge." }, "include_default_attachments": { "type": "boolean", "description": "Standard-Anhänge mitsenden." }, "from_name": { "type": "string", "description": "Abweichender Absendername." }, "reply_to": { "type": "string", "description": "Abweichende Antwort-Adresse." }, "track_opens": { "type": "boolean", "description": "Öffnungen messen." }, "track_clicks": { "type": "boolean", "description": "Klicks messen." } }, "additionalProperties": true }, "example": { "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "template_key": "newsletter-01", "list_ids": [ 3 ] } } } }, "responses": { "201": { "description": "Entwurf angelegt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "status_label": { "type": "string" }, "started_at": {}, "finished_at": {}, "id": { "type": "integer" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "audience_label": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "ab_test_id": {}, "scheduled_at": {}, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "draft", "status_label": "Entwurf", "started_at": null, "finished_at": null, "id": 812, "type": "newsletter", "type_label": "Newsletter", "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "preheader": "Nur bis Sonntag: Dein Herbst-Bonus", "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "audience_label": "1 Liste", "smtp_account_id": 1, "attachment_ids": [], "include_default_attachments": false, "track_opens": true, "track_clicks": true, "ab_test_id": null, "scheduled_at": null, "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "unique_opens": 702, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066 }, "created_at": "2026-10-08T17:20:00+02:00", "updated_at": "2026-10-09T09:04:31+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/newsletters/{id}": { "get": { "operationId": "newsletters_get", "summary": "Newsletter abrufen", "description": "Ein Newsletter inklusive HTML und Kennzahlen.\n\nBenötigter Scope: `read`. Tarif-Funktion: `newsletter`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "audience_label": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "ab_test_id": {}, "scheduled_at": {}, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "html": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "type": "newsletter", "type_label": "Newsletter", "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "preheader": "Nur bis Sonntag: Dein Herbst-Bonus", "status": "sent", "status_label": "Gesendet", "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "audience_label": "1 Liste", "smtp_account_id": 1, "attachment_ids": [], "include_default_attachments": false, "track_opens": true, "track_clicks": true, "ab_test_id": null, "scheduled_at": null, "started_at": "2026-10-09T09:00:00+02:00", "finished_at": "2026-10-09T09:04:31+02:00", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "unique_opens": 702, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066 }, "created_at": "2026-10-08T17:20:00+02:00", "updated_at": "2026-10-09T09:04:31+02:00", "html": "…" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "newsletters_update", "summary": "Newsletter ändern", "description": "Ändert einen Entwurf oder geplanten Newsletter (versendete sind gesperrt → 409).\n\nBenötigter Scope: `write`. Tarif-Funktion: `newsletter`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Interner Name." }, "subject": { "type": "string", "description": "Betreff (zum Versand Pflicht)." }, "preheader": { "type": "string", "description": "Vorschautext." }, "html": { "type": "string", "description": "HTML-Inhalt." }, "text": { "type": "string", "description": "Alternativ reiner Text." }, "template_key": { "type": "string", "description": "Bibliotheks-Vorlage (übernimmt HTML, Betreff, Preheader, falls nicht angegeben)." }, "template_id": { "type": "integer", "description": "Eigene Vorlage." }, "audience": { "type": "object", "additionalProperties": true, "description": "Empfänger: {\"all\":false,\"lists\":[3],\"contacts\":[42],\"emails\":[\"x@y.de\"]}." }, "list_ids": { "type": "array", "items": { "type": "integer" }, "description": "Kurzform für audience.lists." }, "smtp_account_id": { "type": "integer", "description": "SMTP-Konto." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge." }, "include_default_attachments": { "type": "boolean", "description": "Standard-Anhänge mitsenden." }, "from_name": { "type": "string", "description": "Abweichender Absendername." }, "reply_to": { "type": "string", "description": "Abweichende Antwort-Adresse." }, "track_opens": { "type": "boolean", "description": "Öffnungen messen." }, "track_clicks": { "type": "boolean", "description": "Klicks messen." } }, "additionalProperties": true }, "example": { "subject": "Neuer Betreff", "list_ids": [ 3, 4 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "audience_label": { "type": "string" }, "smtp_account_id": { "type": "integer" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "ab_test_id": {}, "scheduled_at": {}, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "unique_opens": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "type": "newsletter", "type_label": "Newsletter", "name": "Herbst-Aktion", "subject": "Anna, das hier ist nur für Dich", "preheader": "Nur bis Sonntag: Dein Herbst-Bonus", "status": "sent", "status_label": "Gesendet", "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "audience_label": "1 Liste", "smtp_account_id": 1, "attachment_ids": [], "include_default_attachments": false, "track_opens": true, "track_clicks": true, "ab_test_id": null, "scheduled_at": null, "started_at": "2026-10-09T09:00:00+02:00", "finished_at": "2026-10-09T09:04:31+02:00", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "unique_opens": 702, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066 }, "created_at": "2026-10-08T17:20:00+02:00", "updated_at": "2026-10-09T09:04:31+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "newsletters_delete", "summary": "Newsletter löschen", "description": "Löscht den Newsletter samt Statistik. Laufende Versände müssen zuerst abgebrochen werden (409).\n\nBenötigter Scope: `write`. Tarif-Funktion: `newsletter`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/newsletters/{id}/cancel": { "post": { "operationId": "newsletters_cancel", "summary": "Versand abbrechen", "description": "Geplante Newsletter werden wieder zum Entwurf, laufende Versände werden gestoppt.\n\nBenötigter Scope: `send`. Tarif-Funktion: `newsletter`. Unterstützt `Idempotency-Key`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "status": "draft", "message": "Versand abgebrochen – der Newsletter liegt wieder bei Deinen Entwürfen." }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/newsletters/{id}/schedule": { "post": { "operationId": "newsletters_schedule", "summary": "Newsletter planen", "description": "Plant den Versand für einen Zeitpunkt in der Zukunft (max. 1 Jahr).\n\nBenötigter Scope: `send`. Tarif-Funktion: `newsletter`. Unterstützt `Idempotency-Key`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "description": "Zeitpunkt (ISO 8601)." } }, "additionalProperties": true, "required": [ "scheduled_at" ] }, "example": { "scheduled_at": "2026-10-12T09:00:00+02:00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "message": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "status": "scheduled", "scheduled_at": "2026-10-12T09:00:00+02:00", "message": "Newsletter geplant für 12.10.2026 09:00 Uhr – wir senden pünktlich." }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/newsletters/{id}/send": { "post": { "operationId": "newsletters_send", "summary": "Newsletter jetzt senden", "description": "Prüft Vollständigkeit und Tageslimit, stellt alle Empfänger in die Warteschlange und verschickt einen ersten Schwung. Der Rest folgt über den Cron.\n\nBenötigter Scope: `send`. Tarif-Funktion: `newsletter`. Unterstützt `Idempotency-Key`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "responses": { "202": { "description": "Versand gestartet", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "queued": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "status": "sending", "queued": 1250, "sent": 150, "failed": 0, "message": "Versand gestartet: 150 von 1.250 E-Mails sind raus, der Rest folgt automatisch." }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/newsletters/{id}/stats": { "get": { "operationId": "newsletters_stats", "summary": "Newsletter-Statistik", "description": "Zahlen und Quoten (Öffnungen, Klicks, Abmeldungen, Bounces), Top-Links und Geräte.\n\nBenötigter Scope: `read`. Tarif-Funktion: `newsletter`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "held": { "type": "integer" }, "skipped": { "type": "integer" }, "cancelled": { "type": "integer" }, "opens": { "type": "integer" }, "unique_opens": { "type": "integer" }, "clicks": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "ctor": { "type": "number" }, "unsub_rate": { "type": "number" }, "bounce_rate": { "type": "number" }, "failed_rate": { "type": "number" }, "progress": { "type": "number" } }, "additionalProperties": true }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string" }, "clicks": { "type": "integer" }, "unique_clicks": { "type": "integer" } }, "additionalProperties": true } }, "devices": { "type": "object", "properties": { "desktop": { "type": "integer" }, "mobile": { "type": "integer" }, "tablet": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 812, "status": "sent", "stats": { "recipients": 1250, "sent": 1248, "failed": 2, "pending": 0, "held": 0, "skipped": 0, "cancelled": 0, "opens": 980, "unique_opens": 702, "clicks": 190, "unique_clicks": 133, "unsubs": 3, "open_rate": 0.5625, "click_rate": 0.1066, "ctor": 0.1895, "unsub_rate": 0.0024, "bounce_rate": 0.0016, "failed_rate": 0.0016, "progress": 1 }, "links": [ { "url": "https://kartenherz.com/angebot", "label": "Jetzt ansehen", "clicks": 140, "unique_clicks": 118 } ], "devices": { "desktop": 312, "mobile": 365, "tablet": 25 } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/newsletters/{id}/test": { "post": { "operationId": "newsletters_test", "summary": "Testmail senden", "description": "Sendet den aktuellen Stand als Testmail (Betreff mit „[TEST]“, ohne Tracking) an bis zu 5 Adressen. Ohne „to“ an Deine Konto-Adresse.\n\nBenötigter Scope: `send`. Tarif-Funktion: `newsletter`. Unterstützt `Idempotency-Key`.", "tags": [ "Newsletter" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "Bis zu 5 Adressen." }, "contact_id": { "type": "integer", "description": "Kontakt für die Personalisierung (Standard: Beispielkontakt „Max“)." } }, "additionalProperties": true }, "example": { "to": "du@beispiel.de" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "sent_to": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "sent_to": [ "du@beispiel.de" ], "message": "Testmail an du@beispiel.de gesendet." }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/openapi.json": { "get": { "operationId": "system_openapi", "summary": "OpenAPI-Beschreibung", "description": "Die vollständige, maschinenlesbare Beschreibung dieser API im Format OpenAPI 3.1 (z. B. für Postman, Insomnia, Code-Generatoren). Ohne Umschlag {data}.\n\nÖffentlich – kein API-Schlüssel nötig.", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "Persolz REST API", "version": "1.1.0" }, "paths": {} } } } } } } }, "/plan/limits": { "get": { "operationId": "account_limits", "summary": "Tarif-Limits mit Verbrauch", "description": "Alle Limits des Tarifs mit aktuellem Verbrauch und Rest (-1 = unbegrenzt) sowie alle Funktionen mit Freischaltung.\n\nBenötigter Scope: `read`.", "tags": [ "Konto & Tarif" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "plan": { "type": "string" }, "plan_label": { "type": "string" }, "limits": { "type": "object", "properties": { "max_contacts": { "type": "object", "properties": { "label": { "type": "string" }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" } }, "additionalProperties": true }, "emails_per_day": { "type": "object", "properties": { "label": { "type": "string" }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "features": { "type": "object", "properties": { "api": { "type": "object", "properties": { "label": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": true }, "ai": { "type": "object", "properties": { "label": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "plan": "pro", "plan_label": "Pro", "limits": { "max_contacts": { "label": "Kontakte", "limit": -1, "used": 1250, "remaining": -1 }, "emails_per_day": { "label": "E-Mails pro Tag", "limit": -1, "used": 3, "remaining": -1 } }, "features": { "api": { "label": "API & Webhooks", "enabled": true }, "ai": { "label": "KI-Assistent", "enabled": true } } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seinfeld/emails": { "get": { "operationId": "seinfeld_emails", "summary": "Seinfeld-Mails auflisten", "description": "Entwürfe, geplante und versendete Seinfeld-Mails.\n\nBenötigter Scope: `read`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "all | pending (KI-Entwürfe zur Freigabe) | draft | planned (freigegeben & geplant, Alias „scheduled“) | sent | problems (fehlgeschlagen / abgebrochen)", "schema": { "type": "string", "enum": [ "all", "pending", "draft", "planned", "sent", "problems" ] }, "example": "planned" }, { "name": "q", "in": "query", "required": false, "description": "Suche in Betreff und Story.", "schema": { "type": "string" }, "example": "kaffee" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "ai_generated": { "type": "boolean" }, "ai_model": { "type": "string" }, "topic_id": { "type": "integer" }, "arc_id": {}, "episode_no": {}, "story_title": { "type": "string" }, "story_summary": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "template_key": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "sent_at": {}, "campaign_id": { "type": "integer" }, "smtp_account_id": {}, "audience": {}, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 120, "subject": "Was mein Kaffeebecher über Marketing weiß", "preheader": "Eine Geschichte über Gewohnheiten", "html": "…", "status": "scheduled", "status_label": "Geplant", "ai_generated": true, "ai_model": "claude-sonnet-5-5", "topic_id": 15, "arc_id": null, "episode_no": null, "story_title": "Der Kaffeebecher", "story_summary": "Warum kleine Rituale Vertrauen schaffen.", "keywords": [ "kaffee", "gewohnheit" ], "template_key": "seinfeld-01", "scheduled_at": "2026-10-10T09:00:00+02:00", "sent_at": null, "campaign_id": 901, "smtp_account_id": null, "audience": null, "attachment_ids": [], "include_default_attachments": false, "created_at": "2026-10-09T07:00:00+02:00", "updated_at": "2026-10-09T08:12:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "seinfeld_createEmail", "summary": "Seinfeld-Mail anlegen", "description": "Legt einen Entwurf an (wird nicht automatisch versendet – plane ihn mit /schedule).\n\nBenötigter Scope: `write`. Tarif-Funktion: `seinfeld`. Unterstützt `Idempotency-Key`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Betreff." }, "preheader": { "type": "string", "description": "Vorschautext." }, "html": { "type": "string", "description": "HTML-Inhalt." }, "scheduled_at": { "type": "string", "description": "Geplanter Versand (ISO 8601); leer = nächster freier Termin beim Planen." }, "topic_id": { "type": "integer", "description": "Thema aus der Themenliste (wird als benutzt markiert)." }, "arc_id": { "type": "integer", "description": "Story-Bogen." }, "story_title": { "type": "string", "description": "Titel der Geschichte (Story-Gedächtnis)." }, "story_summary": { "type": "string", "description": "Kurze Zusammenfassung (Story-Gedächtnis gegen Wiederholungen)." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Stichworte." }, "smtp_account_id": { "type": "integer", "description": "SMTP-Konto (Standard: Einstellungen)." }, "audience": { "type": "object", "additionalProperties": true, "description": "Abweichende Empfänger (Standard: Einstellungen)." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge." }, "template_key": { "type": "string", "description": "Design-Vorlage." } }, "additionalProperties": true }, "example": { "subject": "Was mein Kaffeebecher über Marketing weiß", "html": "

Heute Morgen …

", "topic_id": 15 } } } }, "responses": { "201": { "description": "Angelegt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "status_label": { "type": "string" }, "campaign_id": {}, "ai_generated": { "type": "boolean" }, "id": { "type": "integer" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "ai_model": { "type": "string" }, "topic_id": { "type": "integer" }, "arc_id": {}, "episode_no": {}, "story_title": { "type": "string" }, "story_summary": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "template_key": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "sent_at": {}, "smtp_account_id": {}, "audience": {}, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "draft", "status_label": "Entwurf", "campaign_id": null, "ai_generated": false, "id": 120, "subject": "Was mein Kaffeebecher über Marketing weiß", "preheader": "Eine Geschichte über Gewohnheiten", "html": "…", "ai_model": "claude-sonnet-5-5", "topic_id": 15, "arc_id": null, "episode_no": null, "story_title": "Der Kaffeebecher", "story_summary": "Warum kleine Rituale Vertrauen schaffen.", "keywords": [ "kaffee", "gewohnheit" ], "template_key": "seinfeld-01", "scheduled_at": "2026-10-10T09:00:00+02:00", "sent_at": null, "smtp_account_id": null, "audience": null, "attachment_ids": [], "include_default_attachments": false, "created_at": "2026-10-09T07:00:00+02:00", "updated_at": "2026-10-09T08:12:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seinfeld/emails/{id}": { "get": { "operationId": "seinfeld_getEmail", "summary": "Seinfeld-Mail abrufen", "description": "Eine Seinfeld-Mail mit HTML und – nach dem Versand – Kennzahlen.\n\nBenötigter Scope: `read`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "ai_generated": { "type": "boolean" }, "ai_model": { "type": "string" }, "topic_id": { "type": "integer" }, "arc_id": {}, "episode_no": {}, "story_title": { "type": "string" }, "story_summary": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "template_key": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "sent_at": {}, "campaign_id": { "type": "integer" }, "smtp_account_id": {}, "audience": {}, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 120, "subject": "Was mein Kaffeebecher über Marketing weiß", "preheader": "Eine Geschichte über Gewohnheiten", "html": "…", "status": "scheduled", "status_label": "Geplant", "ai_generated": true, "ai_model": "claude-sonnet-5-5", "topic_id": 15, "arc_id": null, "episode_no": null, "story_title": "Der Kaffeebecher", "story_summary": "Warum kleine Rituale Vertrauen schaffen.", "keywords": [ "kaffee", "gewohnheit" ], "template_key": "seinfeld-01", "scheduled_at": "2026-10-10T09:00:00+02:00", "sent_at": null, "campaign_id": 901, "smtp_account_id": null, "audience": null, "attachment_ids": [], "include_default_attachments": false, "created_at": "2026-10-09T07:00:00+02:00", "updated_at": "2026-10-09T08:12:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "seinfeld_updateEmail", "summary": "Seinfeld-Mail ändern", "description": "Ändert die übergebenen Felder. Versendete Mails sind gesperrt (409) – nur das Story-Gedächtnis bleibt änderbar. Geplante Mails werden neu eingeplant.\n\nBenötigter Scope: `write`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Betreff." }, "preheader": { "type": "string", "description": "Vorschautext." }, "html": { "type": "string", "description": "HTML-Inhalt." }, "scheduled_at": { "type": "string", "description": "Geplanter Versand (ISO 8601); leer = nächster freier Termin beim Planen." }, "topic_id": { "type": "integer", "description": "Thema aus der Themenliste (wird als benutzt markiert)." }, "arc_id": { "type": "integer", "description": "Story-Bogen." }, "story_title": { "type": "string", "description": "Titel der Geschichte (Story-Gedächtnis)." }, "story_summary": { "type": "string", "description": "Kurze Zusammenfassung (Story-Gedächtnis gegen Wiederholungen)." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Stichworte." }, "smtp_account_id": { "type": "integer", "description": "SMTP-Konto (Standard: Einstellungen)." }, "audience": { "type": "object", "additionalProperties": true, "description": "Abweichende Empfänger (Standard: Einstellungen)." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge." }, "template_key": { "type": "string", "description": "Design-Vorlage." } }, "additionalProperties": true }, "example": { "subject": "Neuer Betreff" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "ai_generated": { "type": "boolean" }, "ai_model": { "type": "string" }, "topic_id": { "type": "integer" }, "arc_id": {}, "episode_no": {}, "story_title": { "type": "string" }, "story_summary": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "template_key": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "sent_at": {}, "campaign_id": { "type": "integer" }, "smtp_account_id": {}, "audience": {}, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 120, "subject": "Was mein Kaffeebecher über Marketing weiß", "preheader": "Eine Geschichte über Gewohnheiten", "html": "…", "status": "scheduled", "status_label": "Geplant", "ai_generated": true, "ai_model": "claude-sonnet-5-5", "topic_id": 15, "arc_id": null, "episode_no": null, "story_title": "Der Kaffeebecher", "story_summary": "Warum kleine Rituale Vertrauen schaffen.", "keywords": [ "kaffee", "gewohnheit" ], "template_key": "seinfeld-01", "scheduled_at": "2026-10-10T09:00:00+02:00", "sent_at": null, "campaign_id": 901, "smtp_account_id": null, "audience": null, "attachment_ids": [], "include_default_attachments": false, "created_at": "2026-10-09T07:00:00+02:00", "updated_at": "2026-10-09T08:12:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "seinfeld_deleteEmail", "summary": "Seinfeld-Mail löschen", "description": "Löscht die Mail (das Thema wird wieder frei). Laufende Versände → 409.\n\nBenötigter Scope: `write`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seinfeld/emails/{id}/schedule": { "post": { "operationId": "seinfeld_scheduleEmail", "summary": "Seinfeld-Mail freigeben & planen", "description": "Gibt die Mail frei und plant sie zum angegebenen Zeitpunkt, sonst zum geplanten Datum oder zum nächsten freien Termin im Rhythmus.\n\nBenötigter Scope: `send`. Tarif-Funktion: `seinfeld`. Unterstützt `Idempotency-Key`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "description": "Zeitpunkt (ISO 8601), optional." } }, "additionalProperties": true }, "example": { "scheduled_at": "2026-10-10T09:00:00+02:00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "campaign_id": { "type": "integer" }, "id": { "type": "integer" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "status_label": { "type": "string" }, "ai_generated": { "type": "boolean" }, "ai_model": { "type": "string" }, "topic_id": { "type": "integer" }, "arc_id": {}, "episode_no": {}, "story_title": { "type": "string" }, "story_summary": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "template_key": { "type": "string" }, "sent_at": {}, "smtp_account_id": {}, "audience": {}, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "scheduled", "scheduled_at": "2026-10-10T09:00:00+02:00", "campaign_id": 901, "id": 120, "subject": "Was mein Kaffeebecher über Marketing weiß", "preheader": "Eine Geschichte über Gewohnheiten", "html": "…", "status_label": "Geplant", "ai_generated": true, "ai_model": "claude-sonnet-5-5", "topic_id": 15, "arc_id": null, "episode_no": null, "story_title": "Der Kaffeebecher", "story_summary": "Warum kleine Rituale Vertrauen schaffen.", "keywords": [ "kaffee", "gewohnheit" ], "template_key": "seinfeld-01", "sent_at": null, "smtp_account_id": null, "audience": null, "attachment_ids": [], "include_default_attachments": false, "created_at": "2026-10-09T07:00:00+02:00", "updated_at": "2026-10-09T08:12:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seinfeld/emails/{id}/unschedule": { "post": { "operationId": "seinfeld_unscheduleEmail", "summary": "Planung aufheben", "description": "Setzt eine geplante Mail zurück auf Entwurf (das Datum bleibt erhalten). Laufende Versände → 409.\n\nBenötigter Scope: `write`. Tarif-Funktion: `seinfeld`. Unterstützt `Idempotency-Key`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "status_label": { "type": "string" }, "id": { "type": "integer" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "ai_generated": { "type": "boolean" }, "ai_model": { "type": "string" }, "topic_id": { "type": "integer" }, "arc_id": {}, "episode_no": {}, "story_title": { "type": "string" }, "story_summary": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "template_key": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "sent_at": {}, "campaign_id": { "type": "integer" }, "smtp_account_id": {}, "audience": {}, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "draft", "status_label": "Entwurf", "id": 120, "subject": "Was mein Kaffeebecher über Marketing weiß", "preheader": "Eine Geschichte über Gewohnheiten", "html": "…", "ai_generated": true, "ai_model": "claude-sonnet-5-5", "topic_id": 15, "arc_id": null, "episode_no": null, "story_title": "Der Kaffeebecher", "story_summary": "Warum kleine Rituale Vertrauen schaffen.", "keywords": [ "kaffee", "gewohnheit" ], "template_key": "seinfeld-01", "scheduled_at": "2026-10-10T09:00:00+02:00", "sent_at": null, "campaign_id": 901, "smtp_account_id": null, "audience": null, "attachment_ids": [], "include_default_attachments": false, "created_at": "2026-10-09T07:00:00+02:00", "updated_at": "2026-10-09T08:12:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seinfeld/generate": { "post": { "operationId": "seinfeld_generate", "summary": "Seinfeld-Mail mit KI schreiben", "description": "Die KI schreibt eine Seinfeld-Mail aus dem nächsten Thema, einem Story-Bogen, einem bestimmten Thema oder Deiner Idee – mit Story-Gedächtnis gegen Wiederholungen. Mit persist=true wird ein Entwurf gespeichert (Antwort enthält email_id). Verbraucht KI-Guthaben.\n\nBenötigter Scope: `ai`. Tarif-Funktion: `seinfeld`, `ai`. Unterstützt `Idempotency-Key`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "description": "auto | topic | next_topic | arc | idea", "enum": [ "auto", "topic", "next_topic", "arc", "idea" ] }, "topic_id": { "type": "integer", "description": "Bei source=topic." }, "arc_id": { "type": "integer", "description": "Bei source=arc." }, "idea": { "type": "string", "description": "Bei source=idea: Deine Idee in ein paar Sätzen." }, "model": { "type": "string", "description": "sonnet (Qualität) | haiku (schnell & günstig)" }, "date": { "type": "string", "description": "Geplantes Versanddatum (für Bezüge im Text)." }, "persist": { "type": "boolean", "description": "Als Entwurf speichern." }, "scheduled_at": { "type": "string", "description": "Bei persist: geplanter Zeitpunkt." } }, "additionalProperties": true }, "example": { "source": "idea", "idea": "Mein Hund hat heute die Post gefressen", "persist": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "story_title": { "type": "string" }, "story_summary": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "model": { "type": "string" }, "cost_eur": { "type": "number" }, "email_id": { "type": "integer" }, "warning": {} }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "subject": "Der Tag, an dem Bruno die Post fraß", "preheader": "Und warum das gut fürs Geschäft war", "html": "…", "story_title": "Bruno und die Post", "story_summary": "…", "keywords": [ "hund", "post" ], "model": "claude-sonnet-5-5", "cost_eur": 0.0123, "email_id": 121, "warning": null }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/seinfeld/settings": { "get": { "operationId": "seinfeld_settings", "summary": "Seinfeld-Einstellungen", "description": "Rhythmus, Versandzeit, Empfänger, KI-Persona, Angebot und Automatik-Optionen – plus aktuelle Serie (Streak).\n\nBenötigter Scope: `read`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "frequency": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "every_n_days": { "type": "integer" }, "anchor": { "type": "string", "format": "date" }, "send_time": { "type": "string" }, "smtp_account_id": {}, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "auto_generate": { "type": "boolean" }, "auto_send": { "type": "boolean" }, "plan_ahead_days": { "type": "integer" }, "ai_model": { "type": "string" }, "persona": { "type": "object", "properties": { "name": { "type": "string" }, "character": { "type": "string" }, "background": { "type": "string" }, "style": { "type": "string" } }, "additionalProperties": true }, "audience_desc": { "type": "string" }, "offer_name": { "type": "string" }, "offer_url": { "type": "string" }, "offer_desc": { "type": "string" }, "tone": { "type": "string" }, "signature": { "type": "string" }, "template_key": { "type": "string" }, "continuity_mode": { "type": "string" }, "include_default_attachments": { "type": "boolean" }, "rhythm": { "type": "string" }, "streak": { "type": "integer" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "enabled": true, "frequency": "weekdays", "weekdays": [ 1, 2, 3, 4, 5 ], "every_n_days": 2, "anchor": "2026-10-01", "send_time": "09:00", "smtp_account_id": null, "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "auto_generate": true, "auto_send": false, "plan_ahead_days": 3, "ai_model": "sonnet", "persona": { "name": "Daniel", "character": "Humorvoller Kartenmacher", "background": "Seit 10 Jahren Illustrator", "style": "locker, Du-Form" }, "audience_desc": "Menschen, die gern Karten verschicken", "offer_name": "Kartenset-Abo", "offer_url": "https://kartenherz.com/abo", "offer_desc": "Jeden Monat 5 handgezeichnete Karten", "tone": "unterhaltsam", "signature": "Dein Daniel", "template_key": "seinfeld-01", "continuity_mode": "arcs", "include_default_attachments": false, "rhythm": "Montag bis Freitag um 09:00 Uhr", "streak": 12 }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "seinfeld_saveSettings", "summary": "Seinfeld-Einstellungen speichern", "description": "Übernimmt die übergebenen Felder, alle anderen behalten ihren Wert.\n\nBenötigter Scope: `write`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Seinfeld-Mails aktiv." }, "frequency": { "type": "string", "description": "daily | weekdays | custom | interval", "enum": [ "daily", "weekdays", "custom", "interval" ] }, "weekdays": { "type": "array", "items": { "type": "integer" }, "description": "Bei custom: Wochentage 1 (Mo) – 7 (So)." }, "every_n_days": { "type": "integer", "description": "Bei interval: Abstand in Tagen (2–30)." }, "send_time": { "type": "string", "description": "Uhrzeit HH:MM." }, "audience": { "type": "object", "additionalProperties": true, "description": "Empfänger {all, lists, contacts, emails}." }, "auto_generate": { "type": "boolean", "description": "KI schreibt Entwürfe für freie Termine." }, "auto_send": { "type": "boolean", "description": "KI-Entwürfe ohne Freigabe automatisch planen." }, "plan_ahead_days": { "type": "integer", "description": "So viele Tage im Voraus vorbereiten (1–14)." }, "ai_model": { "type": "string", "description": "sonnet | haiku" }, "persona": { "type": "object", "additionalProperties": true, "description": "{name, character, background, style}." }, "offer_name": { "type": "string", "description": "Angebot." }, "offer_url": { "type": "string", "description": "Link zum Angebot." }, "tone": { "type": "string", "description": "Tonalität." }, "signature": { "type": "string", "description": "Grußformel." }, "template_key": { "type": "string", "description": "Seinfeld-Vorlage." }, "smtp_account_id": { "type": "integer", "description": "SMTP-Konto." } }, "additionalProperties": true }, "example": { "enabled": true, "frequency": "weekdays", "send_time": "09:00", "audience": { "lists": [ 3 ] }, "offer_url": "https://kartenherz.com/abo" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "frequency": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "every_n_days": { "type": "integer" }, "anchor": { "type": "string", "format": "date" }, "send_time": { "type": "string" }, "smtp_account_id": {}, "audience": { "type": "object", "properties": { "all": { "type": "boolean" }, "lists": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} } }, "additionalProperties": true }, "auto_generate": { "type": "boolean" }, "auto_send": { "type": "boolean" }, "plan_ahead_days": { "type": "integer" }, "ai_model": { "type": "string" }, "persona": { "type": "object", "properties": { "name": { "type": "string" }, "character": { "type": "string" }, "background": { "type": "string" }, "style": { "type": "string" } }, "additionalProperties": true }, "audience_desc": { "type": "string" }, "offer_name": { "type": "string" }, "offer_url": { "type": "string" }, "offer_desc": { "type": "string" }, "tone": { "type": "string" }, "signature": { "type": "string" }, "template_key": { "type": "string" }, "continuity_mode": { "type": "string" }, "include_default_attachments": { "type": "boolean" }, "rhythm": { "type": "string" }, "streak": { "type": "integer" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "enabled": true, "frequency": "weekdays", "weekdays": [ 1, 2, 3, 4, 5 ], "every_n_days": 2, "anchor": "2026-10-01", "send_time": "09:00", "smtp_account_id": null, "audience": { "all": false, "lists": [ 3 ], "contacts": [], "emails": [] }, "auto_generate": true, "auto_send": false, "plan_ahead_days": 3, "ai_model": "sonnet", "persona": { "name": "Daniel", "character": "Humorvoller Kartenmacher", "background": "Seit 10 Jahren Illustrator", "style": "locker, Du-Form" }, "audience_desc": "Menschen, die gern Karten verschicken", "offer_name": "Kartenset-Abo", "offer_url": "https://kartenherz.com/abo", "offer_desc": "Jeden Monat 5 handgezeichnete Karten", "tone": "unterhaltsam", "signature": "Dein Daniel", "template_key": "seinfeld-01", "continuity_mode": "arcs", "include_default_attachments": false, "rhythm": "Montag bis Freitag um 09:00 Uhr", "streak": 12 }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seinfeld/slots": { "get": { "operationId": "seinfeld_slots", "summary": "Termine im Rhythmus", "description": "Alle Versandtermine im Zeitraum mit zugeordneter Mail oder Lücke (is_gap).\n\nBenötigter Scope: `read`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Startdatum YYYY-MM-DD (Standard heute).", "schema": { "type": "string" }, "example": "2026-10-09" }, { "name": "to", "in": "query", "required": false, "description": "Enddatum YYYY-MM-DD (Standard +14 Tage, max. 120 Tage).", "schema": { "type": "string" }, "example": "2026-10-23" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "datetime": { "type": "string", "format": "date-time" }, "email": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true }, "is_gap": { "type": "boolean" }, "is_missed": { "type": "boolean" }, "is_extra": { "type": "boolean" }, "weekday": { "type": "string" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "date": "2026-10-10", "time": "09:00", "datetime": "2026-10-10T09:00:00+02:00", "email": { "id": 120, "subject": "Was mein Kaffeebecher über Marketing weiß", "status": "scheduled" }, "is_gap": false, "is_missed": false, "is_extra": false, "weekday": "Sa" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seinfeld/topics": { "get": { "operationId": "seinfeld_topics", "summary": "Themen auflisten", "description": "Die Themenliste (offen zuerst in manueller Reihenfolge).\n\nBenötigter Scope: `read`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "all | open | used | skipped", "schema": { "type": "string", "enum": [ "all", "open", "used", "skipped" ] }, "example": "open" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "topic": { "type": "string" }, "notes": { "type": "string" }, "priority": { "type": "boolean" }, "status": { "type": "string" }, "used_at": {}, "email_id": {}, "sort_order": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 15, "topic": "Der verlorene Schlüssel", "notes": "Bezug zu Ordnungssystemen", "priority": true, "status": "open", "used_at": null, "email_id": null, "sort_order": 3, "created_at": "2026-10-01T09:00:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "seinfeld_createTopic", "summary": "Thema hinzufügen", "description": "Fügt ein Thema hinzu – oder mehrere mit „topics“ (Array aus Texten oder {topic, note}). Doppelte Themen werden übersprungen.\n\nBenötigter Scope: `write`. Tarif-Funktion: `seinfeld`. Unterstützt `Idempotency-Key`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "Thema." }, "notes": { "type": "string", "description": "Notizen." }, "priority": { "type": "boolean", "description": "Mit Stern (wird zuerst genutzt)." }, "topics": { "type": "array", "items": {}, "description": "Mehrere Themen auf einmal." } }, "additionalProperties": true }, "example": { "topic": "Der verlorene Schlüssel", "priority": true } } } }, "responses": { "201": { "description": "Angelegt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "topic": { "type": "string" }, "notes": { "type": "string" }, "priority": { "type": "boolean" }, "status": { "type": "string" }, "used_at": {}, "email_id": {}, "sort_order": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 15, "topic": "Der verlorene Schlüssel", "notes": "Bezug zu Ordnungssystemen", "priority": true, "status": "open", "used_at": null, "email_id": null, "sort_order": 3, "created_at": "2026-10-01T09:00:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seinfeld/topics/{id}": { "patch": { "operationId": "seinfeld_updateTopic", "summary": "Thema ändern", "description": "Ändert Text, Notizen, Stern oder Status (open/skipped).\n\nBenötigter Scope: `write`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "Thema." }, "notes": { "type": "string", "description": "Notizen." }, "priority": { "type": "boolean", "description": "Stern." }, "status": { "type": "string", "description": "open | skipped" } }, "additionalProperties": true }, "example": { "priority": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "topic": { "type": "string" }, "notes": { "type": "string" }, "priority": { "type": "boolean" }, "status": { "type": "string" }, "used_at": {}, "email_id": {}, "sort_order": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 15, "topic": "Der verlorene Schlüssel", "notes": "Bezug zu Ordnungssystemen", "priority": true, "status": "open", "used_at": null, "email_id": null, "sort_order": 3, "created_at": "2026-10-01T09:00:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "seinfeld_deleteTopic", "summary": "Thema löschen", "description": "Löscht das Thema.\n\nBenötigter Scope: `write`. Tarif-Funktion: `seinfeld`.", "tags": [ "Seinfeld-Mails" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences": { "get": { "operationId": "sequences_list", "summary": "Seifenopern auflisten", "description": "Alle Sequenzen mit Kennzahlen (Tage, Teilnehmer, Öffnungs-/Klickrate).\n\nBenötigter Scope: `read`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "draft | active | paused | archived", "schema": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "example": "active" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "goal": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "trigger_type": { "type": "string" }, "trigger_list_id": { "type": "integer" }, "trigger_label": { "type": "string" }, "send_time": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "smtp_account_id": {}, "ai_model": { "type": "string" }, "template_key": { "type": "string" }, "include_default_attachments": { "type": "boolean" }, "step_count": { "type": "integer" }, "enrolled_active": { "type": "integer" }, "enrolled_completed": { "type": "integer" }, "sent": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 7, "name": "Willkommen bei Kartenherz", "description": "5 Tage Story-Sequenz für neue Leads", "goal": "Verkauf des Kartenset-Abos", "status": "active", "status_label": "Aktiv", "trigger_type": "list_join", "trigger_list_id": 3, "trigger_label": "Beim Eintrag in „Kartenherz Funnel“", "send_time": "09:00", "skip_weekends": false, "smtp_account_id": null, "ai_model": "sonnet", "template_key": "soap-01", "include_default_attachments": false, "step_count": 5, "enrolled_active": 312, "enrolled_completed": 845, "sent": 4980, "open_rate": 0.61, "click_rate": 0.14, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "sequences_create", "summary": "Seifenoper anlegen", "description": "Legt eine Sequenz als Entwurf an (optional mit 5 vorbereiteten Tagen). Free-Tarif: 1 Sequenz.\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`. Unterstützt `Idempotency-Key`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name der Seifenoper." }, "description": { "type": "string", "description": "Beschreibung." }, "goal": { "type": "string", "description": "Ziel / Angebot." }, "trigger_type": { "type": "string", "description": "manual | list_join | api", "enum": [ "manual", "list_join", "api" ] }, "trigger_list_id": { "type": "integer", "description": "Bei list_join: Liste, deren neue Mitglieder automatisch starten." }, "send_time": { "type": "string", "description": "Versandzeit HH:MM." }, "skip_weekends": { "type": "boolean", "description": "Wochenenden überspringen." }, "smtp_account_id": { "type": "integer", "description": "SMTP-Konto." }, "ai_model": { "type": "string", "description": "sonnet | haiku" }, "template_key": { "type": "string", "description": "Design-Vorlage (soap-…)." }, "include_default_attachments": { "type": "boolean", "description": "Standard-Anhänge mitsenden." }, "starter": { "type": "string", "description": "Beim Anlegen: hints (5 vorbereitete Tage mit Schreibhinweisen), library (Beispieltexte der Vorlagen-Serie) oder none.", "enum": [ "hints", "library", "none" ] } }, "additionalProperties": true, "required": [ "name" ] }, "example": { "name": "Willkommen bei Kartenherz", "trigger_type": "list_join", "trigger_list_id": 3, "starter": "hints" } } } }, "responses": { "201": { "description": "Angelegt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "status_label": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "goal": { "type": "string" }, "trigger_type": { "type": "string" }, "trigger_list_id": { "type": "integer" }, "trigger_label": { "type": "string" }, "send_time": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "smtp_account_id": {}, "ai_model": { "type": "string" }, "template_key": { "type": "string" }, "include_default_attachments": { "type": "boolean" }, "step_count": { "type": "integer" }, "enrolled_active": { "type": "integer" }, "enrolled_completed": { "type": "integer" }, "sent": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "draft", "status_label": "Entwurf", "id": 7, "name": "Willkommen bei Kartenherz", "description": "5 Tage Story-Sequenz für neue Leads", "goal": "Verkauf des Kartenset-Abos", "trigger_type": "list_join", "trigger_list_id": 3, "trigger_label": "Beim Eintrag in „Kartenherz Funnel“", "send_time": "09:00", "skip_weekends": false, "smtp_account_id": null, "ai_model": "sonnet", "template_key": "soap-01", "include_default_attachments": false, "step_count": 5, "enrolled_active": 312, "enrolled_completed": 845, "sent": 4980, "open_rate": 0.61, "click_rate": 0.14, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences/generate": { "post": { "operationId": "sequences_generate", "summary": "Gliederung mit KI planen", "description": "Die KI plant eine Seifenoper (3–10 Tage) aus Deinem Briefing: je Tag Etappe, Betreff, Inhalt und Cliffhanger. Mit create=true wird direkt eine Sequenz (Entwurf) mit diesen Tagen angelegt. Verbraucht KI-Guthaben.\n\nBenötigter Scope: `ai`. Tarif-Funktion: `soap`, `ai`. Unterstützt `Idempotency-Key`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "description": "Was verkaufst Du?" }, "audience": { "type": "string", "description": "Für wen?" }, "story": { "type": "string", "description": "Deine Geschichte (Hintergrund, Tiefpunkt)." }, "epiphany": { "type": "string", "description": "Der Aha-Moment." }, "objections": { "type": "string", "description": "Typische Einwände." }, "url": { "type": "string", "description": "Link zum Angebot." }, "tone": { "type": "string", "description": "Tonalität." }, "days": { "type": "integer", "description": "Anzahl Tage (3–10, Standard 5)." }, "model": { "type": "string", "description": "sonnet | haiku" }, "create": { "type": "boolean", "description": "Sequenz direkt anlegen." }, "name": { "type": "string", "description": "Name der Sequenz bei create." } }, "additionalProperties": true, "required": [ "product", "audience", "story" ] }, "example": { "product": "Kartenset-Abo", "audience": "Kartenliebhaber", "story": "Ich habe als Illustrator fast aufgegeben, bis …", "days": 5 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "title": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer" }, "stage": { "type": "string" }, "subject": { "type": "string" }, "summary": { "type": "string" }, "hook": { "type": "string" } }, "additionalProperties": true } }, "warning": {}, "cost_eur": { "type": "number" }, "sequence_id": {} }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "title": "Von der leeren Mappe zum Abo", "days": [ { "day": 1, "stage": "buehne", "subject": "Wie alles mit einer Postkarte begann", "summary": "…", "hook": "Morgen erzähle ich Dir, was dann schiefging." } ], "warning": null, "cost_eur": 0.021, "sequence_id": null }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/sequences/{id}": { "get": { "operationId": "sequences_get", "summary": "Seifenoper abrufen", "description": "Sequenz mit Tagen (ohne HTML) und Statistik.\n\nBenötigter Scope: `read`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "goal": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "trigger_type": { "type": "string" }, "trigger_list_id": { "type": "integer" }, "trigger_label": { "type": "string" }, "send_time": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "smtp_account_id": {}, "ai_model": { "type": "string" }, "template_key": { "type": "string" }, "include_default_attachments": { "type": "boolean" }, "step_count": { "type": "integer" }, "enrolled_active": { "type": "integer" }, "enrolled_completed": { "type": "integer" }, "sent": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "position": { "type": "integer" }, "day": { "type": "integer" }, "is_active": { "type": "boolean" }, "stage": { "type": "string" }, "stage_label": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "campaign_id": { "type": "integer" }, "ab_test_id": {}, "stats": { "type": "object", "properties": { "sent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "stats": { "type": "object", "properties": { "sent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "completion_rate": { "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 7, "name": "Willkommen bei Kartenherz", "description": "5 Tage Story-Sequenz für neue Leads", "goal": "Verkauf des Kartenset-Abos", "status": "active", "status_label": "Aktiv", "trigger_type": "list_join", "trigger_list_id": 3, "trigger_label": "Beim Eintrag in „Kartenherz Funnel“", "send_time": "09:00", "skip_weekends": false, "smtp_account_id": null, "ai_model": "sonnet", "template_key": "soap-01", "include_default_attachments": false, "step_count": 5, "enrolled_active": 312, "enrolled_completed": 845, "sent": 4980, "open_rate": 0.61, "click_rate": 0.14, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00", "steps": [ { "id": 31, "sequence_id": 7, "position": 1, "day": 1, "is_active": true, "stage": "buehne", "stage_label": "Bühne bereiten", "subject": "Wie alles mit einer Postkarte begann", "preheader": "Tag 1 von 5", "attachment_ids": [], "include_default_attachments": false, "campaign_id": 950, "ab_test_id": null, "stats": { "sent": 1157, "opens": 760, "clicks": 98, "unsubs": 4, "open_rate": 0.6569, "click_rate": 0.0847 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-09-02T11:00:00+02:00" } ], "stats": { "sent": 4980, "opens": 3038, "clicks": 697, "open_rate": 0.61, "click_rate": 0.14, "completion_rate": 0.73 } }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "sequences_update", "summary": "Seifenoper ändern", "description": "Ändert die übergebenen Einstellungen.\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name der Seifenoper." }, "description": { "type": "string", "description": "Beschreibung." }, "goal": { "type": "string", "description": "Ziel / Angebot." }, "trigger_type": { "type": "string", "description": "manual | list_join | api", "enum": [ "manual", "list_join", "api" ] }, "trigger_list_id": { "type": "integer", "description": "Bei list_join: Liste, deren neue Mitglieder automatisch starten." }, "send_time": { "type": "string", "description": "Versandzeit HH:MM." }, "skip_weekends": { "type": "boolean", "description": "Wochenenden überspringen." }, "smtp_account_id": { "type": "integer", "description": "SMTP-Konto." }, "ai_model": { "type": "string", "description": "sonnet | haiku" }, "template_key": { "type": "string", "description": "Design-Vorlage (soap-…)." }, "include_default_attachments": { "type": "boolean", "description": "Standard-Anhänge mitsenden." }, "starter": { "type": "string", "description": "Beim Anlegen: hints (5 vorbereitete Tage mit Schreibhinweisen), library (Beispieltexte der Vorlagen-Serie) oder none.", "enum": [ "hints", "library", "none" ] } }, "additionalProperties": true, "required": [ "name" ] }, "example": { "send_time": "08:30", "skip_weekends": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "goal": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "trigger_type": { "type": "string" }, "trigger_list_id": { "type": "integer" }, "trigger_label": { "type": "string" }, "send_time": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "smtp_account_id": {}, "ai_model": { "type": "string" }, "template_key": { "type": "string" }, "include_default_attachments": { "type": "boolean" }, "step_count": { "type": "integer" }, "enrolled_active": { "type": "integer" }, "enrolled_completed": { "type": "integer" }, "sent": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 7, "name": "Willkommen bei Kartenherz", "description": "5 Tage Story-Sequenz für neue Leads", "goal": "Verkauf des Kartenset-Abos", "status": "active", "status_label": "Aktiv", "trigger_type": "list_join", "trigger_list_id": 3, "trigger_label": "Beim Eintrag in „Kartenherz Funnel“", "send_time": "09:00", "skip_weekends": false, "smtp_account_id": null, "ai_model": "sonnet", "template_key": "soap-01", "include_default_attachments": false, "step_count": 5, "enrolled_active": 312, "enrolled_completed": 845, "sent": 4980, "open_rate": 0.61, "click_rate": 0.14, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "sequences_delete", "summary": "Seifenoper löschen", "description": "Löscht die Sequenz mit allen Tagen, Statistiken und Teilnahmen.\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences/{id}/activate": { "post": { "operationId": "sequences_activate", "summary": "Seifenoper aktivieren", "description": "Startet die Sequenz. Voraussetzung: mindestens ein aktiver Tag mit Betreff und Inhalt, ein SMTP-Konto und bei list_join eine Liste.\n\nBenötigter Scope: `send`. Tarif-Funktion: `soap`. Unterstützt `Idempotency-Key`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "status_label": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "goal": { "type": "string" }, "trigger_type": { "type": "string" }, "trigger_list_id": { "type": "integer" }, "trigger_label": { "type": "string" }, "send_time": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "smtp_account_id": {}, "ai_model": { "type": "string" }, "template_key": { "type": "string" }, "include_default_attachments": { "type": "boolean" }, "step_count": { "type": "integer" }, "enrolled_active": { "type": "integer" }, "enrolled_completed": { "type": "integer" }, "sent": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "active", "status_label": "Aktiv", "id": 7, "name": "Willkommen bei Kartenherz", "description": "5 Tage Story-Sequenz für neue Leads", "goal": "Verkauf des Kartenset-Abos", "trigger_type": "list_join", "trigger_list_id": 3, "trigger_label": "Beim Eintrag in „Kartenherz Funnel“", "send_time": "09:00", "skip_weekends": false, "smtp_account_id": null, "ai_model": "sonnet", "template_key": "soap-01", "include_default_attachments": false, "step_count": 5, "enrolled_active": 312, "enrolled_completed": 845, "sent": 4980, "open_rate": 0.61, "click_rate": 0.14, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences/{id}/enroll": { "post": { "operationId": "sequences_enroll", "summary": "Kontakte aufnehmen", "description": "Nimmt Kontakte auf: per contact_ids, emails (unbekannte Adressen werden als Kontakte angelegt) oder alle aktiven Mitglieder einer Liste (list_id). Abgemeldete/unbestätigte Kontakte werden übersprungen. Die Mails starten, sobald die Sequenz aktiv ist.\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`. Unterstützt `Idempotency-Key`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_ids": { "type": "array", "items": { "type": "integer" }, "description": "Kontakt-IDs." }, "emails": { "type": "array", "items": { "type": "string" }, "description": "E-Mail-Adressen." }, "list_id": { "type": "integer", "description": "Alle aktiven Mitglieder dieser Liste." }, "start_date": { "type": "string", "description": "Startdatum YYYY-MM-DD, „today“ oder „tomorrow“ (Standard heute). Vergangene Daten holen verpasste Tage sofort nach." } }, "additionalProperties": true }, "example": { "contact_ids": [ 42 ], "emails": [ "ben@beispiel.de" ], "start_date": "tomorrow" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "enrolled": { "type": "integer" }, "already": { "type": "integer" }, "skipped": { "type": "integer" }, "created": { "type": "integer" }, "total": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "enrolled": 2, "already": 0, "skipped": 0, "created": 1, "total": 2, "message": "2 Kontakte aufgenommen. 1 neuer Kontakt wurde angelegt." }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences/{id}/enrollments": { "get": { "operationId": "sequences_enrollments", "summary": "Teilnehmer auflisten", "description": "Teilnahmen mit Fortschritt (aktueller Tag, nächster Versand).\n\nBenötigter Scope: `read`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "status", "in": "query", "required": false, "description": "active | paused | completed | cancelled | unsubscribed", "schema": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled", "unsubscribed" ] }, "example": "active" }, { "name": "q", "in": "query", "required": false, "description": "Suche in Name/E-Mail.", "schema": { "type": "string" }, "example": "anna" }, { "name": "page", "in": "query", "required": false, "description": "Seite (ab 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Einträge pro Seite (1–100).", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "contact_id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "current_position": { "type": "integer" }, "current_day": { "type": "integer" }, "total_steps": { "type": "integer" }, "progress": { "type": "number" }, "next_send_at": { "type": "string", "format": "date-time" }, "last_sent_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 501, "contact_id": 42, "email": "anna@beispiel.de", "name": "Anna Schmidt", "status": "active", "status_label": "Aktiv", "source": "api", "start_date": "2026-10-08", "current_position": 2, "current_day": 2, "total_steps": 5, "progress": 0.4, "next_send_at": "2026-10-10T09:00:00+02:00", "last_sent_at": "2026-10-09T09:00:12+02:00", "created_at": "2026-10-08T12:00:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e", "pagination": { "page": 1, "per_page": 25, "total": 1, "pages": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences/{id}/enrollments/{contactId}": { "delete": { "operationId": "sequences_unenroll", "summary": "Teilnehmer entfernen", "description": "Stoppt die Teilnahme des Kontakts (er erhält keine weiteren Mails dieser Sequenz).\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "contactId", "in": "path", "required": true, "description": "ID des Kontakts", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "204": { "description": "Entfernt" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences/{id}/pause": { "post": { "operationId": "sequences_pause", "summary": "Seifenoper pausieren", "description": "Pausiert die Sequenz – es gehen keine Mails mehr raus, bis sie wieder aktiviert wird.\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`. Unterstützt `Idempotency-Key`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "status_label": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "goal": { "type": "string" }, "trigger_type": { "type": "string" }, "trigger_list_id": { "type": "integer" }, "trigger_label": { "type": "string" }, "send_time": { "type": "string" }, "skip_weekends": { "type": "boolean" }, "smtp_account_id": {}, "ai_model": { "type": "string" }, "template_key": { "type": "string" }, "include_default_attachments": { "type": "boolean" }, "step_count": { "type": "integer" }, "enrolled_active": { "type": "integer" }, "enrolled_completed": { "type": "integer" }, "sent": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "status": "paused", "status_label": "Pausiert", "id": 7, "name": "Willkommen bei Kartenherz", "description": "5 Tage Story-Sequenz für neue Leads", "goal": "Verkauf des Kartenset-Abos", "trigger_type": "list_join", "trigger_list_id": 3, "trigger_label": "Beim Eintrag in „Kartenherz Funnel“", "send_time": "09:00", "skip_weekends": false, "smtp_account_id": null, "ai_model": "sonnet", "template_key": "soap-01", "include_default_attachments": false, "step_count": 5, "enrolled_active": 312, "enrolled_completed": 845, "sent": 4980, "open_rate": 0.61, "click_rate": 0.14, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-10-01T08:30:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences/{id}/steps": { "get": { "operationId": "sequences_steps", "summary": "Tage auflisten", "description": "Alle Tage der Sequenz in Reihenfolge, inkl. HTML und Kennzahlen.\n\nBenötigter Scope: `read`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "position": { "type": "integer" }, "day": { "type": "integer" }, "is_active": { "type": "boolean" }, "stage": { "type": "string" }, "stage_label": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "campaign_id": { "type": "integer" }, "ab_test_id": {}, "stats": { "type": "object", "properties": { "sent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 31, "sequence_id": 7, "position": 1, "day": 1, "is_active": true, "stage": "buehne", "stage_label": "Bühne bereiten", "subject": "Wie alles mit einer Postkarte begann", "preheader": "Tag 1 von 5", "html": "…", "attachment_ids": [], "include_default_attachments": false, "campaign_id": 950, "ab_test_id": null, "stats": { "sent": 1157, "opens": 760, "clicks": 98, "unsubs": 4, "open_rate": 0.6569, "click_rate": 0.0847 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-09-02T11:00:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "sequences_createStep", "summary": "Tag hinzufügen", "description": "Hängt einen Tag an (oder fügt ihn hinter after_step_id ein). Max. 60 Tage.\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`. Unterstützt `Idempotency-Key`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Betreff." }, "preheader": { "type": "string", "description": "Vorschautext." }, "html": { "type": "string", "description": "HTML-Inhalt." }, "day": { "type": "integer", "description": "Versandtag (1 = Starttag, max. 365). Spätere Tage werden bei Bedarf verschoben." }, "stage": { "type": "string", "description": "Etappe: buehne, drama, epiphanie, vorteile, dringlichkeit, einwaende, szenario, bonus, faq, letzte_chance, custom" }, "is_active": { "type": "boolean", "description": "Aktiv (ausgesetzte Tage werden übersprungen)." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge." }, "include_default_attachments": { "type": "boolean", "description": "Standard-Anhänge." }, "after_step_id": { "type": "integer", "description": "Nur beim Anlegen: hinter diesem Tag einfügen (Standard: ans Ende)." } }, "additionalProperties": true }, "example": { "subject": "Das Drama beginnt", "html": "

Gestern habe ich Dir erzählt …

", "day": 2, "stage": "drama" } } } }, "responses": { "201": { "description": "Angelegt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "position": { "type": "integer" }, "day": { "type": "integer" }, "is_active": { "type": "boolean" }, "stage": { "type": "string" }, "stage_label": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "campaign_id": { "type": "integer" }, "ab_test_id": {}, "stats": { "type": "object", "properties": { "sent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 31, "sequence_id": 7, "position": 1, "day": 1, "is_active": true, "stage": "buehne", "stage_label": "Bühne bereiten", "subject": "Wie alles mit einer Postkarte begann", "preheader": "Tag 1 von 5", "html": "…", "attachment_ids": [], "include_default_attachments": false, "campaign_id": 950, "ab_test_id": null, "stats": { "sent": 1157, "opens": 760, "clicks": 98, "unsubs": 4, "open_rate": 0.6569, "click_rate": 0.0847 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-09-02T11:00:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sequences/{id}/steps/{stepId}": { "patch": { "operationId": "sequences_updateStep", "summary": "Tag ändern", "description": "Ändert einen Tag. Ein neuer „day“ verschiebt bei Bedarf die folgenden Tage.\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "stepId", "in": "path", "required": true, "description": "ID des Tages", "schema": { "type": "integer" }, "example": 31 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Betreff." }, "preheader": { "type": "string", "description": "Vorschautext." }, "html": { "type": "string", "description": "HTML-Inhalt." }, "day": { "type": "integer", "description": "Versandtag (1 = Starttag, max. 365). Spätere Tage werden bei Bedarf verschoben." }, "stage": { "type": "string", "description": "Etappe: buehne, drama, epiphanie, vorteile, dringlichkeit, einwaende, szenario, bonus, faq, letzte_chance, custom" }, "is_active": { "type": "boolean", "description": "Aktiv (ausgesetzte Tage werden übersprungen)." }, "attachment_ids": { "type": "array", "items": { "type": "integer" }, "description": "Anhänge." }, "include_default_attachments": { "type": "boolean", "description": "Standard-Anhänge." }, "after_step_id": { "type": "integer", "description": "Nur beim Anlegen: hinter diesem Tag einfügen (Standard: ans Ende)." } }, "additionalProperties": true }, "example": { "subject": "Neuer Betreff für Tag 1", "is_active": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "position": { "type": "integer" }, "day": { "type": "integer" }, "is_active": { "type": "boolean" }, "stage": { "type": "string" }, "stage_label": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string" }, "attachment_ids": { "type": "array", "items": {} }, "include_default_attachments": { "type": "boolean" }, "campaign_id": { "type": "integer" }, "ab_test_id": {}, "stats": { "type": "object", "properties": { "sent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "unsubs": { "type": "integer" }, "open_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": 31, "sequence_id": 7, "position": 1, "day": 1, "is_active": true, "stage": "buehne", "stage_label": "Bühne bereiten", "subject": "Wie alles mit einer Postkarte begann", "preheader": "Tag 1 von 5", "html": "…", "attachment_ids": [], "include_default_attachments": false, "campaign_id": 950, "ab_test_id": null, "stats": { "sent": 1157, "opens": 760, "clicks": 98, "unsubs": 4, "open_rate": 0.6569, "click_rate": 0.0847 }, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-09-02T11:00:00+02:00" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "sequences_deleteStep", "summary": "Tag löschen", "description": "Löscht den Tag samt Statistik; Teilnehmer behalten ihren Fortschritt.\n\nBenötigter Scope: `write`. Tarif-Funktion: `soap`.", "tags": [ "Seifenopern" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "stepId", "in": "path", "required": true, "description": "ID des Tages", "schema": { "type": "integer" }, "example": 31 } ], "responses": { "204": { "description": "Gelöscht" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/smtp-accounts": { "get": { "operationId": "smtp_list", "summary": "SMTP-Konten auflisten", "description": "Verbundene SMTP-Server – Passwörter werden nie ausgegeben (nur has_password).\n\nBenötigter Scope: `read`.", "tags": [ "SMTP-Server" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "from_name": { "type": "string" }, "from_email": { "type": "string" }, "reply_to": {}, "host": { "type": "string" }, "port": { "type": "integer" }, "encryption": { "type": "string" }, "username": { "type": "string" }, "has_password": { "type": "boolean" }, "auth": { "type": "boolean" }, "hourly_limit": { "type": "integer" }, "daily_limit": { "type": "integer" }, "is_default": { "type": "boolean" }, "status": { "type": "string" }, "last_error": {}, "last_tested_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": 1, "label": "Strato Postfach", "from_name": "Kartenherz", "from_email": "hallo@kartenherz.com", "reply_to": null, "host": "smtp.strato.de", "port": 465, "encryption": "ssl", "username": "hallo@kartenherz.com", "has_password": true, "auth": true, "hourly_limit": 0, "daily_limit": 0, "is_default": true, "status": "ok", "last_error": null, "last_tested_at": "2026-10-01T09:00:00+02:00", "sent_today": 140, "created_at": "2026-09-01T10:00:00+02:00" } ], "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/smtp-accounts/{id}/test": { "post": { "operationId": "smtp_test", "summary": "Verbindung testen", "description": "Testet die Verbindung (Anmeldung beim Server). Mit send_to wird zusätzlich eine Testmail verschickt. Bei Fehlern gibt es einen deutschen Lösungshinweis.\n\nBenötigter Scope: `write`. Unterstützt `Idempotency-Key`.", "tags": [ "SMTP-Server" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID der Ressource", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: eindeutiger Wert, damit eine wiederholte Anfrage (z. B. nach einem Timeout) nichts doppelt anlegt oder versendet. 24 Stunden gültig.", "schema": { "type": "string" }, "example": "3f1c9a7e-5b2d-4c8f-9e0a-1d2b3c4d5e6f" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_to": { "type": "string", "description": "Testmail an diese Adresse (optional)." } }, "additionalProperties": true }, "example": { "send_to": "du@beispiel.de" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": {}, "hint": {}, "message": { "type": "string" }, "tested_at": { "type": "string", "format": "date-time" }, "sent_to": { "type": "string" } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "ok": true, "error": null, "hint": null, "message": "Verbindung erfolgreich.", "tested_at": "2026-10-09T14:05:00+02:00", "sent_to": "du@beispiel.de" }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/subscribe/{token}": { "post": { "operationId": "public_subscribe", "summary": "Öffentliche Anmeldung (ohne Schlüssel)", "description": "Anmeldung an eine Liste über deren öffentlichen Token – für Formulare, Landingpages und Funnels (CORS „*“). Akzeptiert JSON oder Formulardaten. Double-Opt-in der Liste wird beachtet (Status pending + Bestätigungsmail). Spamschutz: Das Honeypot-Feld „website“ muss leer bleiben; max. 10 Anmeldungen pro Minute je IP und 200 pro Tag je Liste. HTML-Formulare (Accept: text/html oder mit success_url) werden per 303 auf success_url weitergeleitet (bei Fehlern auf error_url, sonst eine kleine Danke-/Fehlerseite).\n\nÖffentlich – kein API-Schlüssel nötig.", "tags": [ "Öffentliche Anmeldung" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Öffentlicher Token der Liste (32 Zeichen, siehe GET /lists).", "schema": { "type": "string" }, "example": "9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "E-Mail-Adresse." }, "first_name": { "type": "string", "description": "Vorname." }, "last_name": { "type": "string", "description": "Nachname." }, "phone": { "type": "string", "description": "Telefon." }, "address": { "type": "string", "description": "Adresse." }, "zip": { "type": "string", "description": "PLZ." }, "city": { "type": "string", "description": "Ort." }, "note": { "type": "string", "description": "Notiz (max. 1000 Zeichen)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags (Array oder kommagetrennt, max. 10)." }, "website": { "type": "string", "description": "Honeypot – muss leer bleiben." }, "success_url": { "type": "string", "description": "Weiterleitung nach Erfolg (http/https). Hat die Liste „Erlaubte Weiterleitungs-Domains“, werden andere Hosts ignoriert (→ Persolz-Danke-Seite)." }, "error_url": { "type": "string", "description": "Weiterleitung bei Fehlern (?error=… wird angehängt) – nur bei gültigem Listen-Token und erlaubter Domain." } }, "additionalProperties": true, "required": [ "email" ] }, "example": { "email": "anna@beispiel.de", "first_name": "Anna", "tags": [ "funnel" ], "website": "" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "E-Mail-Adresse." }, "first_name": { "type": "string", "description": "Vorname." }, "last_name": { "type": "string", "description": "Nachname." }, "phone": { "type": "string", "description": "Telefon." }, "address": { "type": "string", "description": "Adresse." }, "zip": { "type": "string", "description": "PLZ." }, "city": { "type": "string", "description": "Ort." }, "note": { "type": "string", "description": "Notiz (max. 1000 Zeichen)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags (Array oder kommagetrennt, max. 10)." }, "website": { "type": "string", "description": "Honeypot – muss leer bleiben." }, "success_url": { "type": "string", "description": "Weiterleitung nach Erfolg (http/https). Hat die Liste „Erlaubte Weiterleitungs-Domains“, werden andere Hosts ignoriert (→ Persolz-Danke-Seite)." }, "error_url": { "type": "string", "description": "Weiterleitung bei Fehlern (?error=… wird angehängt) – nur bei gültigem Listen-Token und erlaubter Domain." } }, "additionalProperties": true, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Bereits vorhanden – aktualisiert", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "state": { "type": "string" }, "double_optin": { "type": "boolean" }, "message": { "type": "string" }, "redirect_url": {} }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "201": { "description": "Angemeldet (200 = bereits bekannt / aktualisiert)", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "state": { "type": "string" }, "double_optin": { "type": "boolean" }, "message": { "type": "string" }, "redirect_url": {} }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "state": "pending", "double_optin": true, "message": "Fast geschafft! Wir haben Dir eine E-Mail geschickt – bitte bestätige Deine Anmeldung über den Link darin.", "redirect_url": null }, "meta": { "request_id": "req_2b9f1c7d0e3a4b5c6d7e" } } } } }, "303": { "description": "Weiterleitung auf success_url / error_url (HTML-Formulare)." }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/subscribe/{token}/form": { "get": { "operationId": "public_form", "summary": "Einbettbares Anmeldeformular", "description": "Ein schlichtes, responsives HTML-Anmeldeformular für die Liste – zum Verlinken oder per