Marketing: Kampagnen versenden und auswerten

Marketing-Kampagnen als Entwurf anlegen, mit der Handlung `marketing.send` senden oder einplanen, abbrechen und Zustellung, Öffnungen, Klicks und Empfänger auswerten.

Für Entwickler

Voraussetzungen

Recht `marketing:read` zum Lesen, `marketing:write` für Entwurf, Änderung, Abbruch und Löschen
Senden: zusätzlich die Handlung `action:marketing.send`
Empfängernamen: `guests:read`; volle Adressen zusätzlich `action:guests.personal`
Plan-Merkmal „Marketing"

ANLEGEN VERSENDET NICHTS. `POST …/campaigns` legt einen ENTWURF (`DRAFT`) an: Kanal, Liste, Vorlage, bei E-Mail Betreff und Vorschautext (leer heisst: die der Vorlage). `scheduledAt` im Entwurf ist nur eine Vormerkung. Gesendet oder eingeplant wird ausschliesslich mit `POST …/campaigns/{id}/send`.

DREI WÄNDE VOR DEM VERSAND. Erstens `marketing:write` UND die ausdrücklich vergebene Handlung `action:marketing.send` — ohne sie antwortet der Wächter mit 403 `forbidden_action`, auch einem Schlüssel mit vollem Schreibrecht. Zweitens ist `Idempotency-Key` PFLICHT: eine Wiederholung nach einem Netzabbruch bekommt die gespeicherte Antwort und sendet nie ein zweites Mal. Drittens eine Bremse von 20 Sendungen je Stunde und Betrieb, gemeinsam gezählt mit dem Dashboard (429 mit `scope: "marketing.send"`).

WAS BEIM SENDEN PASSIERT. Der Inhalt (Vorlage, Betreff, Vorschautext, Tracking-Modus) wird EINGEFROREN; spätere Änderungen an der Vorlage erreichen diese Kampagne nicht mehr. Ohne `scheduledAt` geht sie auf `SENDING` und der Versand beginnt sofort; mit einem Zeitpunkt in der Zukunft (höchstens 365 Tage) auf `SCHEDULED`. Die Empfänger werden erst dann bestimmt: Mitglieder der Liste mit bestätigter Einwilligung für den Kanal, ohne Einträge der Sperrliste. Jede Mail trägt einen Abmeldelink (auch als One-Click-Kopfzeile), jede SMS „Abmelden: <Link>".

FACHLICHE ABLEHNUNGEN SIND `conflict` MIT `reason`. Fehlt Liste oder Vorlage, ist die Vorlage leer, fehlt der Betreff, ist der SMS-Versand nicht eingerichtet, ist die SMS mit Abmeldelink länger als vier Teile, das E-Mail-Kontingent des Monats aufgebraucht oder beim Sofortversand einer SMS-Kampagne das SMS-Guthaben leer (ohne automatische Aufladung), antwortet `…/send` mit 409 und dem Marketing-Code in `reason` (z. B. `marketing-campaign-template-empty`, `marketing-sms-not-ready`, `marketing-email-quota-exhausted`, `marketing-sms-no-credit`). Einplanen prüft Kontingent und Guthaben nicht — bis zum Termin kann der Monat wechseln bzw. aufgeladen werden. Ein Zeitpunkt in der Vergangenheit ist 400 am Feld `scheduledAt`. Der Prüfmodus (`X-TacticTable-Dry-Run: 1`) läuft alle diese Prüfungen durch, sendet nichts und liefert zusätzlich `estimate` (Mitglieder, erreichbar, Kontingent, geschätzte SMS-Kosten in Cent).

STATUS: `DRAFT` Entwurf, `SCHEDULED` eingeplant, `SENDING` im Versand, `PAUSED` angehalten (von Hand im Dashboard oder durch die Engine — `pauseReason` sagt warum: `manual`, `quota_exceeded`, `email_not_configured`, `sms_not_ready`, `sms_no_credit`, `plan_inactive` oder `restaurant_inactive` für einen archivierten bzw. sich schliessenden Betrieb), `SENT` fertig, `CANCELED` abgebrochen, `FAILED` gescheitert. Ändern geht in `DRAFT`, `SCHEDULED` und `PAUSED`; ändert sich bei einer geplanten Kampagne Inhalt oder Zeitpunkt, wird sie wieder Entwurf und muss neu gesendet werden. Nach dem Versandstart sind Liste und Kanal fest. Löschen geht in jedem Status ausser `SENDING` und entfernt Kampagne und Auswertung. Das Protokoll bereits übergebener Nachrichten bleibt stehen: Abmeldelinks, One-Click-Abmeldung und Beschwerdemeldungen aus zugestellten Mails und SMS wirken weiter.

ABBRECHEN (`…/cancel`) braucht keine Handlung — es hält Werbung an, statt sie auszulösen. Noch nicht übergebene Nachrichten werden übersprungen; was schon beim Anbieter ist, lässt sich nicht zurückholen. Pausieren und Fortsetzen gibt es in v1 bewusst nicht: Fortsetzen löst wieder Versand aus und bleibt dem Dashboard vorbehalten.

RATEN SIND ANTEILE VON 0 BIS 1, NICHT PROZENT. `openRate` und `clickRate` beziehen sich auf die MESSBAREN Empfänger (`trackedCount` — nur wer der Auswertung zugestimmt hat, wenn der Tracking-Modus „Nur mit Einwilligung" gilt), `deliveryRate` und `bounceRate` auf `sentCount`. Gezählt werden eindeutige, menschliche Öffnungen und Klicks; Vorabrufe von Sicherheits-Scannern und Apple Mail Privacy Protection zählen nicht. SMS haben keine Zustellbestätigung: dort sind `openRate`, `deliveryRate` und `bounceRate` `null`. `null` heisst immer „kein Nenner", nie 0 %.

DAS EMPFÄNGERPROTOKOLL (`…/recipients`) ist eine Liste von Menschen: den Namen gibt es nur mit `guests:read`, die volle Adresse nur zusätzlich mit `action:guests.personal` — sonst maskiert (`a…@example.at`). Mit Namen zählt jede Seite gegen das Gästekontingent. Wer nur Zahlen braucht, liest `…/stats`: Zeitverlauf (die ersten 72 Stunden stündlich, danach täglich), Links mit Klicks und Programme — ohne eine einzige Person.

Die Routen

GET/api/v1/marketing/campaigns

Kampagnen mit Zählern und Raten lesen, gefiltert nach Status und Kanal.

Rechte

marketing:read

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Abfrageparameter

Name	Typ	Bedeutung
`status`	DRAFT \| SCHEDULED \| SENDING \| PAUSED \| SENT \| CANCELED \| FAILED	Nur Kampagnen in diesem Status, z. B. `SENT` für abgeschlossene. Bedeutung der Werte siehe oben.
`channel`	EMAIL \| SMS	Nur `EMAIL`- oder nur `SMS`-Kampagnen.
`q`	string, 2–200 Zeichen	Suche im Namen.
`sort`	updatedAt \| createdAt \| nameVorgabe: updatedAt	Sortierfeld.
`limit`	integer 1–200Vorgabe: 50	Zeilen je Seite.
`cursor`	undurchsichtiger Zeiger	`nextCursor` der vorigen Antwort.

Mögliche Fehler

validation — Unbekannter Parameter oder Wert.
forbidden — Dem Schlüssel fehlt `marketing:read`.
plan_upgrade_required — Der Plan enthält kein Marketing.

Auch `dir`, `ids`, `updatedAtFrom`, `updatedAtTo`, `includeTotal` wie bei jeder Liste.

POST/api/v1/marketing/campaigns

Eine Kampagne als Entwurf anlegen.

Rechte

marketing:write

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Kopfzeilen

Name	Typ	Bedeutung
`Idempotency-Key`Pflicht	string bis 255 Zeichen	PFLICHT beim Anlegen.

Felder im Rumpf

Name	Typ	Bedeutung
`name`Pflicht	string, 1–160 Zeichen	Interner Name.
`channel`Pflicht	EMAIL \| SMS	`EMAIL` oder `SMS`; die Vorlage muss denselben Kanal haben.
`listId`	UUID oder null	Die Liste (Zielgruppe). Eine fremde Kennung ist 400 `invalid_reference`.
`templateId`	UUID oder null	Die Vorlage passenden Kanals.
`subject`	string bis 200 Zeichen oder null	Nur E-Mail: überschreibt den Betreff der Vorlage.
`preheader`	string bis 200 Zeichen oder null	Nur E-Mail: überschreibt den Vorschautext.
`scheduledAt`	ISO-8601 mit Zone oder null	Vormerkung für die Oberfläche; wirksam erst über `…/send`.

Mögliche Fehler

validation — `Idempotency-Key` fehlt, Betreff bei SMS, fremde oder unpassende Liste/Vorlage, unbekanntes Feld.
read_only_field — `status`, Zähler, Raten oder Zeitstempel im Rumpf.
forbidden — Dem Schlüssel fehlt `marketing:write`.

Antwortet mit 201 und der Kampagne im Format des Einzelabrufs.

GET/api/v1/marketing/campaigns/{id}

Eine Kampagne mit Zählern, Raten, Nachrichten je Status und eingefrorenem Inhalt lesen.

Rechte

marketing:read

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne; eine fremde ergibt 404.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
forbidden — Dem Schlüssel fehlt `marketing:read`.

`frozen` zeigt, womit der Versand wirklich läuft (Vorlagenname, Betreff, Tracking-Modus, Zeitpunkt); `null` vor dem ersten Senden.

PATCH/api/v1/marketing/campaigns/{id}

Einen Entwurf, eine geplante oder pausierte Kampagne ändern.

Rechte

marketing:write

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Felder im Rumpf

Name	Typ	Bedeutung
`templateId`	UUID oder null	Neue Vorlage; bei einer geplanten Kampagne wird sie dadurch wieder Entwurf.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
conflict — Im Versand oder abgeschlossen (`marketing-campaign-not-editable`), Liste/Kanal nach Versandstart (`marketing-campaign-audience-locked`) oder gleichzeitig geändert (`marketing-campaign-changed`).
validation — Schema verletzt oder fremder Verweis.

Alle Felder aus `POST`, jedes einzeln und optional.

DELETE/api/v1/marketing/campaigns/{id}

Eine Kampagne samt Auswertung löschen; das Protokoll übergebener Nachrichten bleibt für Abmeldungen stehen.

Rechte

marketing:write

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
conflict — Die Kampagne wird gerade versendet (`marketing-campaign-not-deletable`) — erst abbrechen.

Antwort `{ "id", "deleted": true }`. Nie übergebene Nachrichten (wartend, übersprungen) fallen mit; Links bleiben, solange eine übergebene Nachricht sie braucht.

POST/api/v1/marketing/campaigns/{id}/send

Sofort senden oder für einen Zeitpunkt einplanen — löst echte Werbung aus.

Rechte

marketing:writeaction:marketing.send

Alle genannten Rechte zusammen, nicht wahlweise.

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne (Status `DRAFT` oder `SCHEDULED`).

Kopfzeilen

Name	Typ	Bedeutung
`Idempotency-Key`Pflicht	string bis 255 Zeichen	PFLICHT. Eine Wiederholung sendet nie ein zweites Mal.

Felder im Rumpf

Name	Typ	Bedeutung
`scheduledAt`	ISO-8601 mit Zone oder null	Leer oder fehlend: sofort. Sonst einplanen, höchstens 365 Tage voraus.

Mögliche Fehler

forbidden_action — Dem Schlüssel fehlt `action:marketing.send`.
validation — `Idempotency-Key` fehlt oder `scheduledAt` liegt in der Vergangenheit bzw. zu weit voraus.
conflict — Schon gestartet oder nicht versandbereit — der Grund steht in `reason`.
not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
rate_limited — Mehr als 20 Sendungen je Stunde für diesen Betrieb — Dashboard und API zusammen.

Antwort: die Kampagne im neuen Status. Im Prüfmodus zusätzlich `estimate` und `dryRun: true`, ohne dass etwas passiert.

POST/api/v1/marketing/campaigns/{id}/cancel

Eine geplante, laufende oder pausierte Kampagne abbrechen.

Rechte

marketing:write

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Mögliche Fehler

conflict — Die Kampagne ist nicht geplant, laufend oder pausiert (`marketing-campaign-invalid-transition`).
not_found — Diese Kampagne gibt es für diesen Betrieb nicht.

Leerer Rumpf. Antwort: die Kampagne mit Status `CANCELED`.

GET/api/v1/marketing/campaigns/{id}/recipients

Das Versandprotokoll je Empfänger lesen.

Rechte

marketing:read

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Abfrageparameter

Name	Typ	Bedeutung
`status`	QUEUED \| SENDING \| SENT \| DELIVERED \| BOUNCED \| COMPLAINED \| FAILED \| SKIPPED \| UNKNOWN \| OPENED \| CLICKED \| UNSUBSCRIBED	Versandstatus (z. B. `BOUNCED` unzustellbar, `SKIPPED` übersprungen mit `skipReason`) oder Verhalten (`OPENED`, `CLICKED`, `UNSUBSCRIBED`).
`limit`	integer 1–200Vorgabe: 50	Zeilen je Seite.
`cursor`	undurchsichtiger Zeiger	`nextCursor` der vorigen Antwort.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
rate_limited — Mit `guests:read`: das Gästekontingent ist ausgeschöpft (`scope: "guests.bulk"`).

`guestName` nur mit `guests:read`; `recipient` voll nur zusätzlich mit `action:guests.personal`, sonst maskiert.

GET/api/v1/marketing/campaigns/{id}/stats

Zeitverlauf, Link-Klicks und Programme einer Kampagne lesen.

Rechte

marketing:read

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.

`timeline.labels` sind fertige Beschriftungen in der Zeitzone des Betriebs; `links` höchstens 100, meistgeklickte zuerst.

Codebeispiele

curl — erst prüfen, dann senden

curl

1curl -sS -X POST https://tactictable.com/api/v1/marketing/campaigns/33122029-4360-426a-bd6a-d71ee99ec6dc/send \2  -H "Authorization: Bearer tt_live_if3u5vp6maf67xmw_PT1xP8EQF7reKUtLcZ7v9z5qaRKmoxeHmd27JpaDvfM" \3  -H "Content-Type: application/json" \4  -H "Idempotency-Key: 7c3e9a15-2b84-4f60-a1d7-5e9b0c4f2a86" \5  -H "X-TacticTable-Dry-Run: 1" \6  -d '{"scheduledAt": "2026-10-02T08:00:00+02:00"}'

Im Prüfmodus geht nichts hinaus und der Key wird nicht verbraucht. Stimmt `estimate`, denselben Aufruf ohne `X-TacticTable-Dry-Run` wiederholen.

Antwort 200 — Prüfmodus beim Einplanen

JSON

1{2  "id": "33122029-4360-426a-bd6a-d71ee99ec6dc",3  "name": "Herbstmenü 2026",4  "channel": "EMAIL",5  "status": "SCHEDULED",6  "list": { "id": "a3f9b69b-a7ac-4a7e-8d2d-1b6dcf0d6e63", "name": "Stammgäste 2026" },7  "template": { "id": "ce6d92ec-3bd6-4201-a65f-0b4bd7fd30b4", "name": "Herbstmenü" },8  "scheduledAt": "2026-10-02T06:00:00.000Z",9  "startedAt": null,10  "completedAt": null,11  "createdAt": "2026-09-20T09:40:00.000Z",12  "updatedAt": "2026-09-20T09:40:00.000Z",13  "counters": { "recipientCount": 0, "skippedCount": 0, "sentCount": 0, "deliveredCount": 0, "openCount": 0, "clickCount": 0, "bounceCount": 0, "complaintCount": 0, "failedCount": 0, "unsubscribeCount": 0, "trackedCount": 0 },14  "rates": { "openRate": null, "clickRate": null, "deliveryRate": null, "bounceRate": null },15  "subject": null,16  "preheader": null,17  "pauseReason": null,18  "canceledAt": null,19  "materializedAt": null,20  "frozen": null,21  "messageCounts": {},22  "estimate": {23    "members": 214,24    "reachable": 161,25    "quota": { "period": "2026-09", "limit": 5000, "used": 312, "remaining": 4688 },26    "smsCostCents": null27  },28  "dryRun": true29}

Raten sind `null`, weil noch nichts gesendet ist — kein Nenner, nicht 0 %.

Antwort 200 — GET /api/v1/marketing/campaigns/{id} nach dem Versand

JSON

1{2  "id": "33122029-4360-426a-bd6a-d71ee99ec6dc",3  "name": "Herbstmenü 2026",4  "channel": "EMAIL",5  "status": "SENT",6  "list": { "id": "a3f9b69b-a7ac-4a7e-8d2d-1b6dcf0d6e63", "name": "Stammgäste 2026" },7  "template": { "id": "ce6d92ec-3bd6-4201-a65f-0b4bd7fd30b4", "name": "Herbstmenü" },8  "scheduledAt": "2026-10-02T06:00:00.000Z",9  "startedAt": "2026-10-02T06:00:31.000Z",10  "completedAt": "2026-10-02T06:04:12.000Z",11  "createdAt": "2026-09-20T09:40:00.000Z",12  "updatedAt": "2026-10-02T06:04:12.000Z",13  "counters": {14    "recipientCount": 161,15    "skippedCount": 4,16    "sentCount": 161,17    "deliveredCount": 158,18    "openCount": 71,19    "clickCount": 19,20    "bounceCount": 3,21    "complaintCount": 0,22    "failedCount": 0,23    "unsubscribeCount": 2,24    "trackedCount": 11825  },26  "rates": { "openRate": 0.6016949152542372, "clickRate": 0.16101694915254236, "deliveryRate": 0.9813664596273292, "bounceRate": 0.018633540372670808 },27  "subject": null,28  "preheader": null,29  "pauseReason": null,30  "canceledAt": null,31  "materializedAt": "2026-10-02T06:00:33.000Z",32  "frozen": { "templateName": "Herbstmenü", "subject": "{{firstName}}, das Herbstmenü ist da", "preheader": "Kürbis, Wild und Maroni ab Freitag", "trackingMode": "CONSENT", "frozenAt": "2026-09-20T09:41:02.000Z" },33  "messageCounts": { "DELIVERED": 156, "BOUNCED": 3, "COMPLAINED": 0, "SENT": 2, "SKIPPED": 4 }34}

`openRate` ≈ 0,60 = 71 von 118 MESSBAREN Empfängern, nicht von 161. Die Raten kommen ungerundet; runden Sie erst bei der Anzeige. Mit Tracking-Modus `CONSENT` misst nur, wer der Auswertung zugestimmt hat.

Antwort 403 — Handlung fehlt

JSON

1{2  "error": "forbidden_action",3  "message": "Diese Operation verlangt zusaetzlich die Handlung „marketing.send“. Sie wird getrennt vom Schreibrecht vergeben, weil sie mehr bewirkt als ein gewoehnliches Aendern.",4  "action": "marketing.send",5  "module": "marketing",6  "op": "write",7  "docs": "https://tactictable.com/dokumentation/api/fehler/forbidden_action",8  "requestId": "req_8f31c0a94d2b47e6ba05"9}

Python — Kampagne anlegen und einplanen

Python

1import uuid2 3import requests4 5BASIS = "https://tactictable.com/api/v1"6 7 8def einplanen(sitzung: requests.Session, liste_id: str, vorlage_id: str, zeitpunkt: str) -> dict:9    entwurf = sitzung.post(10        f"{BASIS}/marketing/campaigns",11        json={"name": "Herbstmenü 2026", "channel": "EMAIL", "listId": liste_id, "templateId": vorlage_id},12        headers={"Idempotency-Key": str(uuid.uuid4())},13        timeout=20,14    )15    entwurf.raise_for_status()16    kampagne_id = entwurf.json()["id"]17 18    # Ein fester Key je Vorgang: die Wiederholung nach einem Abbruch sendet nie doppelt.19    key = f"einplanen-{kampagne_id}"20    antwort = sitzung.post(21        f"{BASIS}/marketing/campaigns/{kampagne_id}/send",22        json={"scheduledAt": zeitpunkt},23        headers={"Idempotency-Key": key},24        timeout=30,25    )26    if antwort.status_code == 409:27        raise RuntimeError(antwort.json().get("reason"))28    antwort.raise_for_status()29    return antwort.json()

Der Schlüssel braucht `marketing:write` UND `action:marketing.send`. Die Sitzung trägt `Authorization: Bearer …` zentral.

TypeScript — Bounces aus dem Protokoll holen

TypeScript

1interface Empfaenger {2    messageId: string3    guestId: string4    recipient: string | null5    status: string6    bounceType: string | null7}8 9export async function bounces(token: string, kampagneId: string): Promise<Empfaenger[]> {10    const gesammelt: Empfaenger[] = []11    let cursor: string | null = null12    do {13        const p = new URLSearchParams({ status: 'BOUNCED', limit: '200' })14        if (cursor) p.set('cursor', cursor)15        const antwort = await fetch('https://tactictable.com/api/v1/marketing/campaigns/' + encodeURIComponent(kampagneId) + '/recipients?' + p, {16            headers: { Authorization: 'Bearer ' + token },17        })18        if (!antwort.ok) throw new Error('HTTP ' + antwort.status)19        const seite = (await antwort.json()) as { data: Empfaenger[]; nextCursor: string | null }20        gesammelt.push(...seite.data)21        cursor = seite.nextCursor22    } while (cursor)23    return gesammelt24}

Harte Bounces (`bounceType: "HARD"`) stehen bereits auf der Sperrliste; niemand muss sie von Hand austragen.

Siehe auch

← Zurück zu REST-API

Marketing: Kampagnen versenden und auswerten

Marketing-Kampagnen als Entwurf anlegen, mit der Handlung `marketing.send` senden oder einplanen, abbrechen und Zustellung, Öffnungen, Klicks und Empfänger auswerten.

Für Entwickler

Voraussetzungen

Recht `marketing:read` zum Lesen, `marketing:write` für Entwurf, Änderung, Abbruch und Löschen
Senden: zusätzlich die Handlung `action:marketing.send`
Empfängernamen: `guests:read`; volle Adressen zusätzlich `action:guests.personal`
Plan-Merkmal „Marketing"

Die Routen

GET/api/v1/marketing/campaigns

Kampagnen mit Zählern und Raten lesen, gefiltert nach Status und Kanal.

Rechte

marketing:read

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Abfrageparameter

Name	Typ	Bedeutung
`status`	DRAFT \| SCHEDULED \| SENDING \| PAUSED \| SENT \| CANCELED \| FAILED	Nur Kampagnen in diesem Status, z. B. `SENT` für abgeschlossene. Bedeutung der Werte siehe oben.
`channel`	EMAIL \| SMS	Nur `EMAIL`- oder nur `SMS`-Kampagnen.
`q`	string, 2–200 Zeichen	Suche im Namen.
`sort`	updatedAt \| createdAt \| nameVorgabe: updatedAt	Sortierfeld.
`limit`	integer 1–200Vorgabe: 50	Zeilen je Seite.
`cursor`	undurchsichtiger Zeiger	`nextCursor` der vorigen Antwort.

Mögliche Fehler

validation — Unbekannter Parameter oder Wert.
forbidden — Dem Schlüssel fehlt `marketing:read`.
plan_upgrade_required — Der Plan enthält kein Marketing.

Auch `dir`, `ids`, `updatedAtFrom`, `updatedAtTo`, `includeTotal` wie bei jeder Liste.

POST/api/v1/marketing/campaigns

Eine Kampagne als Entwurf anlegen.

Rechte

marketing:write

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Kopfzeilen

Name	Typ	Bedeutung
`Idempotency-Key`Pflicht	string bis 255 Zeichen	PFLICHT beim Anlegen.

Felder im Rumpf

Name	Typ	Bedeutung
`name`Pflicht	string, 1–160 Zeichen	Interner Name.
`channel`Pflicht	EMAIL \| SMS	`EMAIL` oder `SMS`; die Vorlage muss denselben Kanal haben.
`listId`	UUID oder null	Die Liste (Zielgruppe). Eine fremde Kennung ist 400 `invalid_reference`.
`templateId`	UUID oder null	Die Vorlage passenden Kanals.
`subject`	string bis 200 Zeichen oder null	Nur E-Mail: überschreibt den Betreff der Vorlage.
`preheader`	string bis 200 Zeichen oder null	Nur E-Mail: überschreibt den Vorschautext.
`scheduledAt`	ISO-8601 mit Zone oder null	Vormerkung für die Oberfläche; wirksam erst über `…/send`.

Mögliche Fehler

validation — `Idempotency-Key` fehlt, Betreff bei SMS, fremde oder unpassende Liste/Vorlage, unbekanntes Feld.
read_only_field — `status`, Zähler, Raten oder Zeitstempel im Rumpf.
forbidden — Dem Schlüssel fehlt `marketing:write`.

Antwortet mit 201 und der Kampagne im Format des Einzelabrufs.

GET/api/v1/marketing/campaigns/{id}

Eine Kampagne mit Zählern, Raten, Nachrichten je Status und eingefrorenem Inhalt lesen.

Rechte

marketing:read

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne; eine fremde ergibt 404.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
forbidden — Dem Schlüssel fehlt `marketing:read`.

`frozen` zeigt, womit der Versand wirklich läuft (Vorlagenname, Betreff, Tracking-Modus, Zeitpunkt); `null` vor dem ersten Senden.

PATCH/api/v1/marketing/campaigns/{id}

Einen Entwurf, eine geplante oder pausierte Kampagne ändern.

Rechte

marketing:write

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Felder im Rumpf

Name	Typ	Bedeutung
`templateId`	UUID oder null	Neue Vorlage; bei einer geplanten Kampagne wird sie dadurch wieder Entwurf.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
conflict — Im Versand oder abgeschlossen (`marketing-campaign-not-editable`), Liste/Kanal nach Versandstart (`marketing-campaign-audience-locked`) oder gleichzeitig geändert (`marketing-campaign-changed`).
validation — Schema verletzt oder fremder Verweis.

Alle Felder aus `POST`, jedes einzeln und optional.

DELETE/api/v1/marketing/campaigns/{id}

Eine Kampagne samt Auswertung löschen; das Protokoll übergebener Nachrichten bleibt für Abmeldungen stehen.

Rechte

marketing:write

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
conflict — Die Kampagne wird gerade versendet (`marketing-campaign-not-deletable`) — erst abbrechen.

Antwort `{ "id", "deleted": true }`. Nie übergebene Nachrichten (wartend, übersprungen) fallen mit; Links bleiben, solange eine übergebene Nachricht sie braucht.

POST/api/v1/marketing/campaigns/{id}/send

Sofort senden oder für einen Zeitpunkt einplanen — löst echte Werbung aus.

Rechte

marketing:writeaction:marketing.send

Alle genannten Rechte zusammen, nicht wahlweise.

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne (Status `DRAFT` oder `SCHEDULED`).

Kopfzeilen

Name	Typ	Bedeutung
`Idempotency-Key`Pflicht	string bis 255 Zeichen	PFLICHT. Eine Wiederholung sendet nie ein zweites Mal.

Felder im Rumpf

Name	Typ	Bedeutung
`scheduledAt`	ISO-8601 mit Zone oder null	Leer oder fehlend: sofort. Sonst einplanen, höchstens 365 Tage voraus.

Mögliche Fehler

forbidden_action — Dem Schlüssel fehlt `action:marketing.send`.
validation — `Idempotency-Key` fehlt oder `scheduledAt` liegt in der Vergangenheit bzw. zu weit voraus.
conflict — Schon gestartet oder nicht versandbereit — der Grund steht in `reason`.
not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
rate_limited — Mehr als 20 Sendungen je Stunde für diesen Betrieb — Dashboard und API zusammen.

Antwort: die Kampagne im neuen Status. Im Prüfmodus zusätzlich `estimate` und `dryRun: true`, ohne dass etwas passiert.

POST/api/v1/marketing/campaigns/{id}/cancel

Eine geplante, laufende oder pausierte Kampagne abbrechen.

Rechte

marketing:write

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Mögliche Fehler

conflict — Die Kampagne ist nicht geplant, laufend oder pausiert (`marketing-campaign-invalid-transition`).
not_found — Diese Kampagne gibt es für diesen Betrieb nicht.

Leerer Rumpf. Antwort: die Kampagne mit Status `CANCELED`.

GET/api/v1/marketing/campaigns/{id}/recipients

Das Versandprotokoll je Empfänger lesen.

Rechte

marketing:read

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Abfrageparameter

Name	Typ	Bedeutung
`status`	QUEUED \| SENDING \| SENT \| DELIVERED \| BOUNCED \| COMPLAINED \| FAILED \| SKIPPED \| UNKNOWN \| OPENED \| CLICKED \| UNSUBSCRIBED	Versandstatus (z. B. `BOUNCED` unzustellbar, `SKIPPED` übersprungen mit `skipReason`) oder Verhalten (`OPENED`, `CLICKED`, `UNSUBSCRIBED`).
`limit`	integer 1–200Vorgabe: 50	Zeilen je Seite.
`cursor`	undurchsichtiger Zeiger	`nextCursor` der vorigen Antwort.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.
rate_limited — Mit `guests:read`: das Gästekontingent ist ausgeschöpft (`scope: "guests.bulk"`).

`guestName` nur mit `guests:read`; `recipient` voll nur zusätzlich mit `action:guests.personal`, sonst maskiert.

GET/api/v1/marketing/campaigns/{id}/stats

Zeitverlauf, Link-Klicks und Programme einer Kampagne lesen.

Rechte

marketing:read

Plan-Merkmal marketing — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Kampagne.

Mögliche Fehler

not_found — Diese Kampagne gibt es für diesen Betrieb nicht.

`timeline.labels` sind fertige Beschriftungen in der Zeitzone des Betriebs; `links` höchstens 100, meistgeklickte zuerst.

Codebeispiele

curl — erst prüfen, dann senden

curl

1curl -sS -X POST https://tactictable.com/api/v1/marketing/campaigns/33122029-4360-426a-bd6a-d71ee99ec6dc/send \2  -H "Authorization: Bearer tt_live_if3u5vp6maf67xmw_PT1xP8EQF7reKUtLcZ7v9z5qaRKmoxeHmd27JpaDvfM" \3  -H "Content-Type: application/json" \4  -H "Idempotency-Key: 7c3e9a15-2b84-4f60-a1d7-5e9b0c4f2a86" \5  -H "X-TacticTable-Dry-Run: 1" \6  -d '{"scheduledAt": "2026-10-02T08:00:00+02:00"}'

Im Prüfmodus geht nichts hinaus und der Key wird nicht verbraucht. Stimmt `estimate`, denselben Aufruf ohne `X-TacticTable-Dry-Run` wiederholen.

Antwort 200 — Prüfmodus beim Einplanen

JSON

1{2  "id": "33122029-4360-426a-bd6a-d71ee99ec6dc",3  "name": "Herbstmenü 2026",4  "channel": "EMAIL",5  "status": "SCHEDULED",6  "list": { "id": "a3f9b69b-a7ac-4a7e-8d2d-1b6dcf0d6e63", "name": "Stammgäste 2026" },7  "template": { "id": "ce6d92ec-3bd6-4201-a65f-0b4bd7fd30b4", "name": "Herbstmenü" },8  "scheduledAt": "2026-10-02T06:00:00.000Z",9  "startedAt": null,10  "completedAt": null,11  "createdAt": "2026-09-20T09:40:00.000Z",12  "updatedAt": "2026-09-20T09:40:00.000Z",13  "counters": { "recipientCount": 0, "skippedCount": 0, "sentCount": 0, "deliveredCount": 0, "openCount": 0, "clickCount": 0, "bounceCount": 0, "complaintCount": 0, "failedCount": 0, "unsubscribeCount": 0, "trackedCount": 0 },14  "rates": { "openRate": null, "clickRate": null, "deliveryRate": null, "bounceRate": null },15  "subject": null,16  "preheader": null,17  "pauseReason": null,18  "canceledAt": null,19  "materializedAt": null,20  "frozen": null,21  "messageCounts": {},22  "estimate": {23    "members": 214,24    "reachable": 161,25    "quota": { "period": "2026-09", "limit": 5000, "used": 312, "remaining": 4688 },26    "smsCostCents": null27  },28  "dryRun": true29}

Raten sind `null`, weil noch nichts gesendet ist — kein Nenner, nicht 0 %.

Antwort 200 — GET /api/v1/marketing/campaigns/{id} nach dem Versand

JSON

1{2  "id": "33122029-4360-426a-bd6a-d71ee99ec6dc",3  "name": "Herbstmenü 2026",4  "channel": "EMAIL",5  "status": "SENT",6  "list": { "id": "a3f9b69b-a7ac-4a7e-8d2d-1b6dcf0d6e63", "name": "Stammgäste 2026" },7  "template": { "id": "ce6d92ec-3bd6-4201-a65f-0b4bd7fd30b4", "name": "Herbstmenü" },8  "scheduledAt": "2026-10-02T06:00:00.000Z",9  "startedAt": "2026-10-02T06:00:31.000Z",10  "completedAt": "2026-10-02T06:04:12.000Z",11  "createdAt": "2026-09-20T09:40:00.000Z",12  "updatedAt": "2026-10-02T06:04:12.000Z",13  "counters": {14    "recipientCount": 161,15    "skippedCount": 4,16    "sentCount": 161,17    "deliveredCount": 158,18    "openCount": 71,19    "clickCount": 19,20    "bounceCount": 3,21    "complaintCount": 0,22    "failedCount": 0,23    "unsubscribeCount": 2,24    "trackedCount": 11825  },26  "rates": { "openRate": 0.6016949152542372, "clickRate": 0.16101694915254236, "deliveryRate": 0.9813664596273292, "bounceRate": 0.018633540372670808 },27  "subject": null,28  "preheader": null,29  "pauseReason": null,30  "canceledAt": null,31  "materializedAt": "2026-10-02T06:00:33.000Z",32  "frozen": { "templateName": "Herbstmenü", "subject": "{{firstName}}, das Herbstmenü ist da", "preheader": "Kürbis, Wild und Maroni ab Freitag", "trackingMode": "CONSENT", "frozenAt": "2026-09-20T09:41:02.000Z" },33  "messageCounts": { "DELIVERED": 156, "BOUNCED": 3, "COMPLAINED": 0, "SENT": 2, "SKIPPED": 4 }34}

Antwort 403 — Handlung fehlt

JSON

1{2  "error": "forbidden_action",3  "message": "Diese Operation verlangt zusaetzlich die Handlung „marketing.send“. Sie wird getrennt vom Schreibrecht vergeben, weil sie mehr bewirkt als ein gewoehnliches Aendern.",4  "action": "marketing.send",5  "module": "marketing",6  "op": "write",7  "docs": "https://tactictable.com/dokumentation/api/fehler/forbidden_action",8  "requestId": "req_8f31c0a94d2b47e6ba05"9}

Python — Kampagne anlegen und einplanen

Python

1import uuid2 3import requests4 5BASIS = "https://tactictable.com/api/v1"6 7 8def einplanen(sitzung: requests.Session, liste_id: str, vorlage_id: str, zeitpunkt: str) -> dict:9    entwurf = sitzung.post(10        f"{BASIS}/marketing/campaigns",11        json={"name": "Herbstmenü 2026", "channel": "EMAIL", "listId": liste_id, "templateId": vorlage_id},12        headers={"Idempotency-Key": str(uuid.uuid4())},13        timeout=20,14    )15    entwurf.raise_for_status()16    kampagne_id = entwurf.json()["id"]17 18    # Ein fester Key je Vorgang: die Wiederholung nach einem Abbruch sendet nie doppelt.19    key = f"einplanen-{kampagne_id}"20    antwort = sitzung.post(21        f"{BASIS}/marketing/campaigns/{kampagne_id}/send",22        json={"scheduledAt": zeitpunkt},23        headers={"Idempotency-Key": key},24        timeout=30,25    )26    if antwort.status_code == 409:27        raise RuntimeError(antwort.json().get("reason"))28    antwort.raise_for_status()29    return antwort.json()

Der Schlüssel braucht `marketing:write` UND `action:marketing.send`. Die Sitzung trägt `Authorization: Bearer …` zentral.

TypeScript — Bounces aus dem Protokoll holen

TypeScript

1interface Empfaenger {2    messageId: string3    guestId: string4    recipient: string | null5    status: string6    bounceType: string | null7}8 9export async function bounces(token: string, kampagneId: string): Promise<Empfaenger[]> {10    const gesammelt: Empfaenger[] = []11    let cursor: string | null = null12    do {13        const p = new URLSearchParams({ status: 'BOUNCED', limit: '200' })14        if (cursor) p.set('cursor', cursor)15        const antwort = await fetch('https://tactictable.com/api/v1/marketing/campaigns/' + encodeURIComponent(kampagneId) + '/recipients?' + p, {16            headers: { Authorization: 'Bearer ' + token },17        })18        if (!antwort.ok) throw new Error('HTTP ' + antwort.status)19        const seite = (await antwort.json()) as { data: Empfaenger[]; nextCursor: string | null }20        gesammelt.push(...seite.data)21        cursor = seite.nextCursor22    } while (cursor)23    return gesammelt24}

Harte Bounces (`bounceType: "HARD"`) stehen bereits auf der Sperrliste; niemand muss sie von Hand austragen.

Siehe auch

← Zurück zu REST-API