Marketing & Outreach — API and MCP
Overview
This area exposes 83 operations. Each of them is at the same time an MCP tool.
This area is behind the module switch module.marketing. With the module off, these operations answer 404.
Operations
| Method | Path | Purpose | Permission | Parameters |
|---|---|---|---|---|
GET | /api/v1/marketing/ad-campaigns | Collection of MarketingAdCampaign | marketing.ads.view | page, status, platform, campaignId, q, order[name], order[status], order[startsAt], order[createdAt] |
POST | /api/v1/marketing/ad-campaigns | Werbekampagne als Entwurf anlegen — Legt eine Werbekampagne an. Sie entsteht IMMER als Entwurf und gibt kein Geld aus, bis sie über /activate scharf geschaltet wird. budgetCapCent ist Pflicht — der Deckel ist die einzige Stelle, an der das System Ausgaben begrenzt. | marketing.ads.manage | + body |
DELETE | /api/v1/marketing/ad-campaigns/{ulid} | Delete a MarketingAdCampaign | marketing.ads.manage | ulid |
GET | /api/v1/marketing/ad-campaigns/{ulid} | Read one MarketingAdCampaign | marketing.ads.view · object rule mkt.view | ulid |
PATCH | /api/v1/marketing/ad-campaigns/{ulid} | Update a MarketingAdCampaign | marketing.ads.manage | ulid, + body |
POST | /api/v1/marketing/ad-campaigns/{ulid}/activate | Werbekampagne scharf schalten — Legt die Kampagne beim Netzwerk an (falls noch nicht geschehen) und startet die Auslieferung. Ab hier kostet sie Geld. Verlangt das Freigabe-Recht marketing.ads.publish IN DER MARKE der Kampagne — nicht dasselbe wie Bearbeiten, und nicht dasselbe wie dieses Recht irgendwo zu halten. | marketing.ads.publish | ulid, + body |
POST | /api/v1/marketing/ad-campaigns/{ulid}/budget | Budget ändern — Setzt Tages- oder Laufzeitbudget. Verlangt marketing.ads.manage IN DER MARKE der Kampagne. Über dem Deckel wird abgelehnt; der Deckel selbst lässt sich nur mit dem Freigabe-Recht marketing.ads.publish in derselben Marke heben. | marketing.ads.manage | ulid, + body |
POST | /api/v1/marketing/ad-campaigns/{ulid}/pause | Werbekampagne anhalten — Stoppt die Auslieferung sofort. Anhalten darf, wer die Kampagne IN IHRER MARKE bearbeiten darf — Geld sparen ist nie der gefährlichere Weg. | marketing.ads.manage | ulid, + body |
GET | /api/v1/marketing/ads/report | Werbe-Auswertung — Ausgaben, Klicks, Ergebnisse und die daraus gerechneten Kennzahlen (Klickrate, Kosten je Klick, Kosten je Ergebnis, Werbeausgabenrendite) für einen Zeitraum — je Kampagne und als Summe. Geld je Zeile in der Konto-Währung der Kampagne (currency, spendCent, revenueCent, cpcCent, cpaCent) UND in EUR (spendEurCent, revenueEurCent) über den beim Anlegen eingefrorenen Kurs eurRate (Fremdwährung je 1 EUR). Fremdwährungs-Zeilen ohne Kurs tragen unconverted: true und bleiben ganz aus der Summe (totals.unconvertedRows). Die Summe und ihre Kennzahlen stehen ausschließlich in EUR (totals.currency). | marketing.ads.view | from, to, campaignUlid, level |
POST | /api/v1/marketing/ai | Create a MarketingAi | marketing.campaign.manage | + body |
GET | /api/v1/marketing/audiences | Collection of MarketingAudience | marketing.campaign.manage | page, kind, q, order[name], order[createdAt] |
POST | /api/v1/marketing/audiences | Create a MarketingAudience | marketing.campaign.manage | + body |
POST | /api/v1/marketing/audiences/preview | Create a MarketingAudience | marketing.campaign.manage | + body |
DELETE | /api/v1/marketing/audiences/{ulid} | Delete a MarketingAudience | marketing.campaign.manage | ulid |
GET | /api/v1/marketing/audiences/{ulid} | Read one MarketingAudience | marketing.campaign.manage · object rule mkt.view | ulid |
PATCH | /api/v1/marketing/audiences/{ulid} | Update a MarketingAudience | marketing.campaign.manage | ulid, + body |
POST | /api/v1/marketing/audiences/{ulid}/preview | Segmentgröße live berechnen — Rechnet die Größe des Segments live aus und schreibt sie an der Zielgruppe fort (estimatedSize) — die Regel selbst bleibt unberührt. Verlangt marketing.campaign.manage IN DER MARKE der Zielgruppe. | marketing.campaign.manage | ulid, + body |
GET | /api/v1/marketing/campaigns | Collection of MarketingCampaign | marketing.campaign.manage | page, q, active, entryMode, ownerId, order[name], order[createdAt] |
POST | /api/v1/marketing/campaigns | Strecke anlegen — Legt die Huelle UND ihre Automation in einem Zug an (die Automation ist die Laufzeit; die Huelle traegt nur den Marketing-Bezug). Die Strecke startet INAKTIV. | marketing.campaign.manage | + body |
DELETE | /api/v1/marketing/campaigns/{ulid} | Delete a MarketingCampaign | marketing.campaign.manage | ulid |
GET | /api/v1/marketing/campaigns/{ulid} | Read one MarketingCampaign | marketing.campaign.manage | ulid |
PATCH | /api/v1/marketing/campaigns/{ulid} | Update a MarketingCampaign | marketing.campaign.manage | ulid, + body |
POST | /api/v1/marketing/campaigns/{ulid}/enroll | Empfänger in die Strecke aufnehmen — Löst das Aufnahme-Ereignis aus (derselbe Weg wie die automatische Aufnahme). Gesperrte Adressen und inaktive Strecken nehmen niemanden auf; ein bereits aufgenommener Empfänger erzeugt keinen zweiten Lauf. NUR für Strecken (entryMode=per_recipient): ein Einmal-Versand wird mit 422 abgewiesen — dort wartet kein Ereignis-Trigger auf die Aufnahme, sie liefe ins Leere. | marketing.campaign.manage | ulid, + body |
POST | /api/v1/marketing/campaigns/{ulid}/scan | Zielgruppe jetzt abklappern — Nimmt sofort alle Empfänger der hinterlegten Zielgruppe auf, statt auf den täglichen Lauf zu warten. Idempotent: wer schon in der Strecke ist, kommt nicht erneut hinein. Antwortet mit der Zahl der tatsächlich neu Aufgenommenen (enrolled). | marketing.campaign.manage | ulid, + body |
GET | /api/v1/marketing/campaigns/{ulid}/stats | Statistik je Strecken-Schritt — Zahlen je Schritt-Position (erreicht, versendet, geoeffnet, geklickt) plus die Lauf-Zustaende der Strecke. reached ist KUMULATIV (R43-10): ein Lauf zaehlt an jedem Schritt, den er ausgefuehrt hat oder vor dem er in Bedingungs-Wartung steht — nicht am Schritt, auf dem sein Cursor gerade steht. | marketing.campaign.manage | ulid |
POST | /api/v1/marketing/campaigns/{ulid}/test-message | Testmail EINER Nachricht der Strecke — Verschickt die Nachricht an der angegebenen Schritt-Position an eine Adresse — mit ihrem eigenen Betreff und ihren eigenen Inhalten, gerendert wie im Versand. Ohne Einwilligungs-Prüfung, ohne Drossel und OHNE Tracking-Zeile: eine Testmail ist eine Ansicht, kein Versand, und dürfte die Zustellquote der Nachricht nicht verschieben. Der Betreff trägt sichtbar [TEST]. | marketing.campaign.manage | ulid, + body |
GET | /api/v1/marketing/consent-topics | Collection of MarketingConsentTopic | marketing.consent.view | page, brandId, active, q |
POST | /api/v1/marketing/consent-topics | Create a MarketingConsentTopic | marketing.consent.manage | + body |
DELETE | /api/v1/marketing/consent-topics/{ulid} | Delete a MarketingConsentTopic | marketing.consent.manage | ulid |
GET | /api/v1/marketing/consent-topics/{ulid} | Read one MarketingConsentTopic | marketing.consent.view · object rule mkt.view | ulid |
PATCH | /api/v1/marketing/consent-topics/{ulid} | Update a MarketingConsentTopic | marketing.consent.manage | ulid, + body |
GET | /api/v1/marketing/consents | Collection of MarketingConsent | marketing.consent.view | page, status, email, q, order[email], order[channel], order[status], order[createdAt] |
POST | /api/v1/marketing/consents | Create a MarketingConsent | marketing.consent.manage | + body |
GET | /api/v1/marketing/consents/{ulid} | Read one MarketingConsent | marketing.consent.view | ulid |
POST | /api/v1/marketing/consents/{ulid}/resend-doi | Bestaetigungsmail erneut senden — Schickt die Double-Opt-in-Mail noch einmal an die Adresse der Einwilligung. Verlangt marketing.consent.manage IN DER MARKE der Einwilligung. | marketing.consent.manage | ulid, + body |
POST | /api/v1/marketing/consents/{ulid}/withdraw | Einwilligung widerrufen — Setzt die Einwilligung auf widerrufen — ab sofort geht an diese Adresse keine Werbung mehr. Verlangt marketing.consent.manage IN DER MARKE der Einwilligung. | marketing.consent.manage | ulid, + body |
GET | /api/v1/marketing/dashboard | Collection of MarketingDashboard | marketing.report.view | — |
GET | /api/v1/marketing/dispatch-statuses | Collection of DispatchStatus | marketing.campaign.manage | page |
POST | /api/v1/marketing/dispatch-statuses | Create a DispatchStatus | marketing.config.manage | + body |
DELETE | /api/v1/marketing/dispatch-statuses/{key} | Delete a DispatchStatus | marketing.config.manage | key |
GET | /api/v1/marketing/dispatch-statuses/{key} | Read one DispatchStatus | marketing.campaign.manage | key |
PATCH | /api/v1/marketing/dispatch-statuses/{key} | Update a DispatchStatus | marketing.config.manage | key, + body |
GET | /api/v1/marketing/dispatches | Collection of MarketingDispatch | marketing.campaign.manage | page, campaignId, status, q, order[name], order[subject], order[status], order[scheduledAt], order[sentAt], order[createdAt] |
POST | /api/v1/marketing/dispatches | Geschlossen (410 Gone) — Geschlossen seit Befund R48-076: ein Versandlauf entsteht ausschließlich aus dem Nachrichten-Schritt seiner Kampagne. Antwortet 410 Gone. | marketing.campaign.manage | + body |
DELETE | /api/v1/marketing/dispatches/{ulid} | Delete a MarketingDispatch | marketing.campaign.manage | ulid |
GET | /api/v1/marketing/dispatches/{ulid} | Read one MarketingDispatch | marketing.campaign.manage · object rule mkt.view | ulid |
PATCH | /api/v1/marketing/dispatches/{ulid} | Geschlossen (410 Gone) — Geschlossen seit Befund R48-076: Inhalt und Zeitpunkt eines Versandlaufs kommen aus seiner Kampagne. Antwortet 410 Gone. | marketing.campaign.manage | ulid, + body |
POST | /api/v1/marketing/dispatches/{ulid}/schedule | Geschlossen (410 Gone) — Geschlossen seit Befund R48-076: geplant wird die Kampagne, nicht der einzelne Versandlauf. Antwortet 410 Gone. | marketing.campaign.send | ulid, + body |
POST | /api/v1/marketing/dispatches/{ulid}/send-now | Geschlossen (410 Gone) — Geschlossen seit Befund R48-076: ein Sofortversand ohne die Startregeln der Kampagne ging an jeder Prüfung vorbei. Antwortet 410 Gone. | marketing.campaign.send | ulid, + body |
POST | /api/v1/marketing/dispatches/{ulid}/test | Testmail der Kampagne verschicken — Verschickt eine Testmail der Kampagne an die angegebene Adresse, ohne die Zielgruppe anzufassen. | marketing.campaign.manage | ulid, + body |
GET | /api/v1/marketing/email-events | Collection of MarketingEmailEvent | marketing.campaign.manage | page, dispatchId |
GET | /api/v1/marketing/email-templates | Collection of MarketingEmailTemplate | marketing.campaign.manage | page, q, id, order[name], order[subject], order[createdAt] |
POST | /api/v1/marketing/email-templates | Create a MarketingEmailTemplate | marketing.campaign.manage | + body |
POST | /api/v1/marketing/email-templates/canvas | Kampagnen-Mail-Baum in den Editor-Canvas rendern — Rendert einen Mail-Baustein-Baum zu vollstaendigem Mail-HTML fuer den Editor-Canvas; der Abmelde-Block wird garantiert (angehaengt, wenn er im Baum fehlt). Persistiert nichts. | marketing.campaign.manage | + body |
POST | /api/v1/marketing/email-templates/preview | Create a MarketingEmailTemplate | marketing.campaign.manage | + body |
DELETE | /api/v1/marketing/email-templates/{ulid} | Delete a MarketingEmailTemplate | marketing.campaign.manage | ulid |
GET | /api/v1/marketing/email-templates/{ulid} | Read one MarketingEmailTemplate | marketing.campaign.manage | ulid |
PATCH | /api/v1/marketing/email-templates/{ulid} | Update a MarketingEmailTemplate | marketing.campaign.manage | ulid, + body |
POST | /api/v1/marketing/email-templates/{ulid}/preview | Vorlage zur Ansicht rendern — Rendert die Vorlage zur Ansicht — es wird weder versendet noch gespeichert. | marketing.campaign.manage | ulid, + body |
POST | /api/v1/marketing/email-templates/{ulid}/test-send | Vorlage als Testmail senden — Sendet die Vorlage mit Demo-Empfaengerdaten an EINE Adresse; Betreff mit [Test]-Vorsatz. Transportfehler werden als sent=false gemeldet, nicht als 500. | marketing.campaign.manage | ulid, + body |
GET | /api/v1/marketing/form-field-targets | Erlaubte Ziele der Feldzuordnung — Alle Ziele, die fields[].targetField eines Web-Formulars annehmen darf: Stammdaten-Ziele am Interessenten (lead.*) und die eigenen Felder des Interessenten (cf.<name>). | marketing.form.manage | — |
GET | /api/v1/marketing/form-submissions | Collection of MarketingFormSubmission | marketing.submission.view | page, status, webFormId, order[email], order[status], order[createdAt] |
GET | /api/v1/marketing/form-submissions/{ulid} | Read one MarketingFormSubmission | marketing.submission.view | ulid |
POST | /api/v1/marketing/form-submissions/{ulid}/convert | Formular-Absendung als Lead uebernehmen — Legt aus der Absendung einen Lead an und verknuepft beide. Verlangt marketing.submission.convert IN DER MARKE der Absendung. | marketing.submission.convert | ulid, + body |
POST | /api/v1/marketing/form-submissions/{ulid}/spam | Formular-Absendung als Spam markieren — Markiert die Formular-Absendung als Spam. | marketing.submission.spam | ulid, + body |
POST | /api/v1/marketing/form-submissions/{ulid}/unspam | Spam-Markierung zurücknehmen — Nimmt die Spam-Markierung der Formular-Absendung zurück. | marketing.submission.spam | ulid, + body |
GET | /api/v1/marketing/link-stats | Klickzahlen je Link — Klicks und verschiedene Empfänger je Ziel-Adresse, absteigend nach Klicks und gedeckelt. Genau eine Achse angeben: dispatchUlid (Versandlauf) ODER campaignUlid (Strecke, optional mit stepPosition). clicks zählt jeden Klick, recipients verschiedene Empfänger — zwölf Klicks eines Menschen sind keine zwölffache Nachfrage. | marketing.report.view | dispatchUlid, campaignUlid, stepPosition |
GET | /api/v1/marketing/mail-variables | Verfügbare Platzhalter — Alle Platzhalter einer Marketing-Mail mit Bedeutung, Beispielwert und Herkunft. pattern: true heißt: kein fester Name, sondern eine Form (eigene Felder). | marketing.campaign.manage | — |
GET | /api/v1/marketing/report | Collection of MarketingReport | marketing.report.view | from, to, campaignId |
GET | /api/v1/marketing/sender-profiles | Collection of MarketingSenderProfile | marketing.campaign.manage | page, brandId, active, q, order[name], order[createdAt] |
POST | /api/v1/marketing/sender-profiles | Create a MarketingSenderProfile | marketing.config.manage | + body |
DELETE | /api/v1/marketing/sender-profiles/{ulid} | Delete a MarketingSenderProfile | marketing.config.manage | ulid |
GET | /api/v1/marketing/sender-profiles/{ulid} | Read one MarketingSenderProfile | marketing.campaign.manage · object rule mkt.view | ulid |
PATCH | /api/v1/marketing/sender-profiles/{ulid} | Update a MarketingSenderProfile | marketing.config.manage | ulid, + body |
GET | /api/v1/marketing/suppressions | Collection of MarketingSuppression | marketing.consent.view | page, email, order[reason], order[createdAt] |
POST | /api/v1/marketing/suppressions | Create a MarketingSuppression | marketing.consent.manage | + body |
DELETE | /api/v1/marketing/suppressions/{ulid} | Sperreintrag aufheben — Nimmt die Adresse von der Sperrliste — sie kann danach wieder beworben werden. Verlangt marketing.consent.manage IN DER MARKE des Eintrags; eine globale Sperre (ohne Marke) verlangt das Recht ueberhaupt. | marketing.consent.manage | ulid |
GET | /api/v1/marketing/suppressions/{ulid} | Read one MarketingSuppression | marketing.consent.view | ulid |
GET | /api/v1/marketing/web-forms | Collection of MarketingWebForm | marketing.form.manage | page, active, q, order[name], order[createdAt] |
POST | /api/v1/marketing/web-forms | Create a MarketingWebForm | marketing.form.manage | + body |
DELETE | /api/v1/marketing/web-forms/{ulid} | Delete a MarketingWebForm | marketing.form.manage | ulid |
GET | /api/v1/marketing/web-forms/{ulid} | Read one MarketingWebForm | marketing.form.manage · object rule mkt.view | ulid |
PATCH | /api/v1/marketing/web-forms/{ulid} | Update a MarketingWebForm | marketing.form.manage | ulid, + body |
Purpose texts that do not follow the standard pattern are taken verbatim from the interface description in the code.