Marketing: Vorlagen für E-Mail und SMS

Marketing-Vorlagen anlegen, lesen, ändern und löschen — E-Mails aus Blöcken, SMS als Text, mit denselben Platzhalterregeln wie im Editor.

Für Entwickler

Voraussetzungen

Recht `marketing:read` zum Lesen, `marketing:write` zum Anlegen, Ändern und Löschen
Plan-Merkmal „Marketing"

ZWEI KANÄLE, EIN ENDPUNKT. `channel` ist `EMAIL` oder `SMS` und wird beim Anlegen festgelegt. E-Mail-Vorlagen haben `name`, `subject`, `preheader` (Vorschautext) und `blocks`; SMS-Vorlagen `name` und `smsText`. Felder des anderen Kanals sind ein Fehler: beim Anlegen scheitert das Schema, beim Ändern kommt 400 mit `reason: "marketing-template-channel-mismatch"` und `fields`. Den Kanal zu wechseln geht nicht — `channel` ist im `PATCH` nur lesbar; legen Sie eine neue Vorlage an.

BLÖCKE sind dieselben wie im E-Mail-Editor des Dashboards (`heading`, `text`, `image`, `button`, `divider`, `spacer`, `grid` …), höchstens 60, mindestens einer. Den Reservierungsblock (`reservation-details`) gibt es in Marketing-Vorlagen nicht — eine Werbemail hat keine Reservierung. Abmeldelink, Absenderangaben und Adresse des Betriebs hängt der Versand AUTOMATISCH an; sie gehören nicht in die Vorlage.

PLATZHALTER stehen als `{{name}}` in Betreff, Vorschautext, Blöcken und SMS-Text: `firstName`, `guestName`, `restaurantName`, `bookingUrl`, `unsubscribeUrl` und die Restaurantdaten aus dem Branding; in Automatisierungen zusätzlich die Reservierungsdaten (`reservationDate`, `reservationTime`, `reservationPartySize`, `reservationAreaName`). Ein unbekannter Platzhalter ist 400 — er käme beim Gast als Rohtext oder als kaputter Link an. Die Platzhalter der Reservierungsmails (etwa `{{websiteUrl}}`) sind ein anderer Katalog und werden hier ebenfalls abgelehnt.

SMS-LÄNGE: höchstens 480 Zeichen Text. Der Versand hängt „Abmelden: <Link>" an (rund 35 Zeichen) und rechnet in SMS-Teilen (GSM-7 bzw. Unicode); mehr als vier Teile nimmt der Versand nicht an. Umlaute und Emojis können einen Text in Unicode kippen und damit die Teilezahl verdoppeln.

LÖSCHEN IST GESCHÜTZT. Solange eine geplante, laufende oder pausierte Kampagne oder eine aktive bzw. pausierte Automatisierung die Vorlage nutzt, ist `DELETE` 409 (`reason: "marketing-template-in-use"`, `usage` nennt Kampagnen und Automatisierungen). Entwürfe verlieren beim Löschen nur ihre Vorlagenauswahl — `detachedDrafts` sagt, wie viele. Versendete Kampagnen behalten ihren eingefrorenen Inhalt.

INHALT EINER VERWENDETEN VORLAGE ÄNDERN IST VERSAND. Automatisierungen lesen die Vorlage bei jedem Versand neu, und eine pausierte Kampagne friert sie beim Fortsetzen neu ein. Betreff, Vorschautext, Blöcke oder SMS-Text einer Vorlage zu ändern, die gerade verwendet wird (dieselben Nutzer wie beim Löschschutz), verlangt deshalb zusätzlich `action:marketing.send` — sonst 403 `forbidden_action` mit `reason: "marketing-template-live"` und `usage`. Den Namen ändern darf jeder Schlüssel mit `marketing:write`.

Die Routen

GET/api/v1/marketing/templates

Die Vorlagen des Betriebs lesen, wahlweise nur eines Kanals.

Rechte

marketing:read

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

Abfrageparameter

Name	Typ	Bedeutung
`channel`	EMAIL \| SMS	Nur Vorlagen dieses Kanals: `EMAIL` oder `SMS`.
`q`	string, 2–200 Zeichen	Suche in Name, Betreff und SMS-Text.
`sort`	updatedAt \| createdAt \| nameVorgabe: updatedAt	Sortierfeld.
`dir`	asc \| descVorgabe: desc	Sortierrichtung.
`limit`	integer 1–200Vorgabe: 50	Zeilen je Seite.
`cursor`	undurchsichtiger Zeiger	`nextCursor` der vorigen Antwort.

Mögliche Fehler

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

Listenzeilen ohne `blocks`; `excerpt` ist bei E-Mail der Betreff, bei SMS der Textanfang. Auch `ids`, `updatedAtFrom`, `updatedAtTo` und `includeTotal` wie bei jeder Liste.

POST/api/v1/marketing/templates

Eine E-Mail- oder SMS-Vorlage 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 — sonst entsteht bei einer Wiederholung eine zweite Vorlage.

Felder im Rumpf

Name	Typ	Bedeutung
`channel`Pflicht	EMAIL \| SMS	Kanal der Vorlage; danach fest. `EMAIL` verlangt `subject` und `blocks`, `SMS` verlangt `smsText`.
`name`Pflicht	string, 1–120 Zeichen	Interner Name.
`subject`	string bis 200 Zeichen	Nur E-Mail, dort Pflicht. Platzhalter erlaubt.
`preheader`	string bis 200 Zeichen oder null	Nur E-Mail: Vorschautext hinter dem Betreff im Posteingang.
`blocks`	Liste von 1–60 Blöcken	Nur E-Mail: der Inhalt aus Blöcken des E-Mail-Editors.
`smsText`	string, 1–480 Zeichen	Nur SMS, dort Pflicht. Der Abmeldelink wird angehängt.

Mögliche Fehler

validation — `Idempotency-Key` fehlt, Felder des anderen Kanals, unbekannter Platzhalter, ein Reservierungsblock oder ein unbekanntes Feld.
read_only_field — `id`, `excerpt` oder Zeitstempel im Rumpf.
forbidden — Dem Schlüssel fehlt `marketing:write`.
idempotency_key_reuse — Derselbe Schlüssel für eine andere Anfrage.

Antwortet mit 201 und der Vorlage ohne Umschlag.

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

Eine Vorlage vollständig lesen, bei E-Mail samt Blöcken.

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 Vorlage; eine fremde ergibt 404.

Mögliche Fehler

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

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

Name, Betreff, Vorschautext, Blöcke oder SMS-Text ä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 Vorlage.

Felder im Rumpf

Name	Typ	Bedeutung
`blocks`	Liste von 1–60 Blöcken	Ersetzt ALLE Blöcke; einzelne lassen sich nicht ändern.

Mögliche Fehler

not_found — Diese Vorlage gibt es für diesen Betrieb nicht.
read_only_field — `channel` im Rumpf — der Kanal ist fest.
validation — Feld des anderen Kanals (`reason: "marketing-template-channel-mismatch"`), unbekannter Platzhalter oder Schema verletzt.
forbidden_action — Inhalt einer Vorlage ändern, die eine Kampagne oder Automatisierung verwendet, ohne `action:marketing.send` (`reason: "marketing-template-live"`, `usage` nennt sie).
nothing_to_write — Leerer Rumpf.

Wirkt auf geplante Kampagnen erst beim nächsten Einplanen: deren Inhalt ist eingefroren. Aktive Automatisierungen versenden den neuen Inhalt sofort.

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

Eine Vorlage löschen, die keine Kampagne und keine Automatisierung mehr braucht.

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

Mögliche Fehler

not_found — Diese Vorlage gibt es für diesen Betrieb nicht.
conflict — Sie wird noch verwendet (`reason: "marketing-template-in-use"`, `usage`).

Antwort `{ "id", "deleted": true, "detachedDrafts" }`.

Codebeispiele

curl — E-Mail-Vorlage anlegen

curl

1curl -sS -X POST https://tactictable.com/api/v1/marketing/templates \2  -H "Authorization: Bearer tt_live_if3u5vp6maf67xmw_PT1xP8EQF7reKUtLcZ7v9z5qaRKmoxeHmd27JpaDvfM" \3  -H "Content-Type: application/json" \4  -H "Idempotency-Key: 9e1b4f62-7a0d-4c35-8b19-3d6e2f5a7c40" \5  -d '{6  "channel": "EMAIL",7  "name": "Herbstmenü",8  "subject": "{{firstName}}, das Herbstmenü ist da",9  "preheader": "Kürbis, Wild und Maroni ab Freitag",10  "blocks": [11    { "id": "b1", "type": "heading", "content": { "text": "Unser Herbstmenü ist da" } },12    { "id": "b2", "type": "text", "content": { "html": "<p>Hallo {{firstName}}, ab Freitag gibt es Kürbis, Wild und Maroni.</p>" } },13    { "id": "b3", "type": "button", "content": { "label": "Tisch reservieren", "url": "{{bookingUrl}}" } }14  ]15}'

Kein Abmeldelink im Inhalt nötig — der Versand hängt ihn samt Absenderangaben an jede Mail an.

Antwort 201 — Vorlage angelegt

JSON

1{2  "id": "ce6d92ec-3bd6-4201-a65f-0b4bd7fd30b4",3  "channel": "EMAIL",4  "name": "Herbstmenü",5  "subject": "{{firstName}}, das Herbstmenü ist da",6  "preheader": "Kürbis, Wild und Maroni ab Freitag",7  "blocks": [8    { "id": "b1", "type": "heading", "content": { "text": "Unser Herbstmenü ist da" } },9    { "id": "b2", "type": "text", "content": { "html": "<p>Hallo {{firstName}}, ab Freitag gibt es Kürbis, Wild und Maroni.</p>" } },10    { "id": "b3", "type": "button", "content": { "label": "Tisch reservieren", "url": "{{bookingUrl}}" } }11  ],12  "smsText": null,13  "createdAt": "2026-09-20T09:30:12.004Z",14  "updatedAt": "2026-09-20T09:30:12.004Z"15}

Antwort 400 — Platzhalter aus dem falschen Katalog

JSON

1{2  "error": "validation",3  "message": "Der Rumpf ist ungueltig. Unbekannte Felder werden abgelehnt statt stillschweigend abgestreift.",4  "issues": [5    { "path": "blocks", "code": "custom", "message": "Unbekannter Platzhalter in den Blöcken: {{websiteUrl}}. Bitte über „Platzhalter einfügen“ einen gültigen wählen." }6  ],7  "docs": "https://tactictable.com/dokumentation/api/fehler/validation",8  "requestId": "req_8f31c0a94d2b47e6ba05"9}

PHP — SMS-Vorlage anlegen

PHP

1<?php2$rumpf = json_encode([3    'channel' => 'SMS',4    'name' => 'Mittagsmenü',5    'smsText' => 'Hallo {{firstName}}, heute Mittagsmenü um 12,90: Kürbissuppe & Wildragout. {{bookingUrl}}',6]);7 8$ch = curl_init('https://tactictable.com/api/v1/marketing/templates');9curl_setopt_array($ch, [10    CURLOPT_POST => true,11    CURLOPT_POSTFIELDS => $rumpf,12    CURLOPT_RETURNTRANSFER => true,13    CURLOPT_HTTPHEADER => [14        'Authorization: Bearer ' . getenv('TT_API_KEY'),15        'Content-Type: application/json',16        'Idempotency-Key: ' . bin2hex(random_bytes(16)),17    ],18]);19$antwort = json_decode(curl_exec($ch), true);20if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 201) {21    throw new RuntimeException($antwort['message'] ?? 'Vorlage nicht angelegt');22}

Der Euro-Betrag steht hier nur im Text. Umlaute halten die SMS in GSM-7; ein Emoji würde sie in Unicode kippen und die Teilezahl verdoppeln.

TypeScript — Betreff einer Vorlage ändern

TypeScript

1export async function betreffAendern(token: string, vorlageId: string, betreff: string): Promise<void> {2    const antwort = await fetch('https://tactictable.com/api/v1/marketing/templates/' + encodeURIComponent(vorlageId), {3        method: 'PATCH',4        headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' },5        body: JSON.stringify({ subject: betreff }),6    })7    if (antwort.status === 400) {8        const fehler = (await antwort.json()) as { reason?: string; message: string }9        // Betreff an einer SMS-Vorlage: der Kanal ist fest.10        if (fehler.reason === 'marketing-template-channel-mismatch') throw new Error('Das ist eine SMS-Vorlage.')11        throw new Error(fehler.message)12    }13    if (!antwort.ok) throw new Error('HTTP ' + antwort.status)14}

Siehe auch

← Zurück zu REST-API

Die Routen

GET/api/v1/marketing/templates

Die Vorlagen des Betriebs lesen, wahlweise nur eines Kanals.

Rechte

marketing:read

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

Abfrageparameter

Name	Typ	Bedeutung
`channel`	EMAIL \| SMS	Nur Vorlagen dieses Kanals: `EMAIL` oder `SMS`.
`q`	string, 2–200 Zeichen	Suche in Name, Betreff und SMS-Text.
`sort`	updatedAt \| createdAt \| nameVorgabe: updatedAt	Sortierfeld.
`dir`	asc \| descVorgabe: desc	Sortierrichtung.
`limit`	integer 1–200Vorgabe: 50	Zeilen je Seite.
`cursor`	undurchsichtiger Zeiger	`nextCursor` der vorigen Antwort.

Mögliche Fehler

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

Listenzeilen ohne `blocks`; `excerpt` ist bei E-Mail der Betreff, bei SMS der Textanfang. Auch `ids`, `updatedAtFrom`, `updatedAtTo` und `includeTotal` wie bei jeder Liste.

POST/api/v1/marketing/templates

Eine E-Mail- oder SMS-Vorlage 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 — sonst entsteht bei einer Wiederholung eine zweite Vorlage.

Felder im Rumpf

Name	Typ	Bedeutung
`channel`Pflicht	EMAIL \| SMS	Kanal der Vorlage; danach fest. `EMAIL` verlangt `subject` und `blocks`, `SMS` verlangt `smsText`.
`name`Pflicht	string, 1–120 Zeichen	Interner Name.
`subject`	string bis 200 Zeichen	Nur E-Mail, dort Pflicht. Platzhalter erlaubt.
`preheader`	string bis 200 Zeichen oder null	Nur E-Mail: Vorschautext hinter dem Betreff im Posteingang.
`blocks`	Liste von 1–60 Blöcken	Nur E-Mail: der Inhalt aus Blöcken des E-Mail-Editors.
`smsText`	string, 1–480 Zeichen	Nur SMS, dort Pflicht. Der Abmeldelink wird angehängt.

Mögliche Fehler

validation — `Idempotency-Key` fehlt, Felder des anderen Kanals, unbekannter Platzhalter, ein Reservierungsblock oder ein unbekanntes Feld.
read_only_field — `id`, `excerpt` oder Zeitstempel im Rumpf.
forbidden — Dem Schlüssel fehlt `marketing:write`.
idempotency_key_reuse — Derselbe Schlüssel für eine andere Anfrage.

Antwortet mit 201 und der Vorlage ohne Umschlag.

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

Eine Vorlage vollständig lesen, bei E-Mail samt Blöcken.

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 Vorlage; eine fremde ergibt 404.

Mögliche Fehler

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

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

Name, Betreff, Vorschautext, Blöcke oder SMS-Text ä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 Vorlage.

Felder im Rumpf

Name	Typ	Bedeutung
`blocks`	Liste von 1–60 Blöcken	Ersetzt ALLE Blöcke; einzelne lassen sich nicht ändern.

Mögliche Fehler

not_found — Diese Vorlage gibt es für diesen Betrieb nicht.
read_only_field — `channel` im Rumpf — der Kanal ist fest.
validation — Feld des anderen Kanals (`reason: "marketing-template-channel-mismatch"`), unbekannter Platzhalter oder Schema verletzt.
forbidden_action — Inhalt einer Vorlage ändern, die eine Kampagne oder Automatisierung verwendet, ohne `action:marketing.send` (`reason: "marketing-template-live"`, `usage` nennt sie).
nothing_to_write — Leerer Rumpf.

Wirkt auf geplante Kampagnen erst beim nächsten Einplanen: deren Inhalt ist eingefroren. Aktive Automatisierungen versenden den neuen Inhalt sofort.

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

Eine Vorlage löschen, die keine Kampagne und keine Automatisierung mehr braucht.

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

Mögliche Fehler

not_found — Diese Vorlage gibt es für diesen Betrieb nicht.
conflict — Sie wird noch verwendet (`reason: "marketing-template-in-use"`, `usage`).

Antwort `{ "id", "deleted": true, "detachedDrafts" }`.

Codebeispiele

curl — E-Mail-Vorlage anlegen

curl

1curl -sS -X POST https://tactictable.com/api/v1/marketing/templates \2  -H "Authorization: Bearer tt_live_if3u5vp6maf67xmw_PT1xP8EQF7reKUtLcZ7v9z5qaRKmoxeHmd27JpaDvfM" \3  -H "Content-Type: application/json" \4  -H "Idempotency-Key: 9e1b4f62-7a0d-4c35-8b19-3d6e2f5a7c40" \5  -d '{6  "channel": "EMAIL",7  "name": "Herbstmenü",8  "subject": "{{firstName}}, das Herbstmenü ist da",9  "preheader": "Kürbis, Wild und Maroni ab Freitag",10  "blocks": [11    { "id": "b1", "type": "heading", "content": { "text": "Unser Herbstmenü ist da" } },12    { "id": "b2", "type": "text", "content": { "html": "<p>Hallo {{firstName}}, ab Freitag gibt es Kürbis, Wild und Maroni.</p>" } },13    { "id": "b3", "type": "button", "content": { "label": "Tisch reservieren", "url": "{{bookingUrl}}" } }14  ]15}'

Kein Abmeldelink im Inhalt nötig — der Versand hängt ihn samt Absenderangaben an jede Mail an.

Antwort 201 — Vorlage angelegt

JSON

1{2  "id": "ce6d92ec-3bd6-4201-a65f-0b4bd7fd30b4",3  "channel": "EMAIL",4  "name": "Herbstmenü",5  "subject": "{{firstName}}, das Herbstmenü ist da",6  "preheader": "Kürbis, Wild und Maroni ab Freitag",7  "blocks": [8    { "id": "b1", "type": "heading", "content": { "text": "Unser Herbstmenü ist da" } },9    { "id": "b2", "type": "text", "content": { "html": "<p>Hallo {{firstName}}, ab Freitag gibt es Kürbis, Wild und Maroni.</p>" } },10    { "id": "b3", "type": "button", "content": { "label": "Tisch reservieren", "url": "{{bookingUrl}}" } }11  ],12  "smsText": null,13  "createdAt": "2026-09-20T09:30:12.004Z",14  "updatedAt": "2026-09-20T09:30:12.004Z"15}

Antwort 400 — Platzhalter aus dem falschen Katalog

JSON

1{2  "error": "validation",3  "message": "Der Rumpf ist ungueltig. Unbekannte Felder werden abgelehnt statt stillschweigend abgestreift.",4  "issues": [5    { "path": "blocks", "code": "custom", "message": "Unbekannter Platzhalter in den Blöcken: {{websiteUrl}}. Bitte über „Platzhalter einfügen“ einen gültigen wählen." }6  ],7  "docs": "https://tactictable.com/dokumentation/api/fehler/validation",8  "requestId": "req_8f31c0a94d2b47e6ba05"9}

PHP — SMS-Vorlage anlegen

PHP

1<?php2$rumpf = json_encode([3    'channel' => 'SMS',4    'name' => 'Mittagsmenü',5    'smsText' => 'Hallo {{firstName}}, heute Mittagsmenü um 12,90: Kürbissuppe & Wildragout. {{bookingUrl}}',6]);7 8$ch = curl_init('https://tactictable.com/api/v1/marketing/templates');9curl_setopt_array($ch, [10    CURLOPT_POST => true,11    CURLOPT_POSTFIELDS => $rumpf,12    CURLOPT_RETURNTRANSFER => true,13    CURLOPT_HTTPHEADER => [14        'Authorization: Bearer ' . getenv('TT_API_KEY'),15        'Content-Type: application/json',16        'Idempotency-Key: ' . bin2hex(random_bytes(16)),17    ],18]);19$antwort = json_decode(curl_exec($ch), true);20if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 201) {21    throw new RuntimeException($antwort['message'] ?? 'Vorlage nicht angelegt');22}

Der Euro-Betrag steht hier nur im Text. Umlaute halten die SMS in GSM-7; ein Emoji würde sie in Unicode kippen und die Teilezahl verdoppeln.

TypeScript — Betreff einer Vorlage ändern

TypeScript

1export async function betreffAendern(token: string, vorlageId: string, betreff: string): Promise<void> {2    const antwort = await fetch('https://tactictable.com/api/v1/marketing/templates/' + encodeURIComponent(vorlageId), {3        method: 'PATCH',4        headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' },5        body: JSON.stringify({ subject: betreff }),6    })7    if (antwort.status === 400) {8        const fehler = (await antwort.json()) as { reason?: string; message: string }9        // Betreff an einer SMS-Vorlage: der Kanal ist fest.10        if (fehler.reason === 'marketing-template-channel-mismatch') throw new Error('Das ist eine SMS-Vorlage.')11        throw new Error(fehler.message)12    }13    if (!antwort.ok) throw new Error('HTTP ' + antwort.status)14}