E-Mail-Vorlagen-API

Die E-Mail-Vorlagen-API verwaltet die wiederverwendbaren E-Mail-Vorlagen, die hinter den E-Mail-Presets einer Anwendung stehen – dieselben Vorlagen, die Sie im E-Mail-Editor des Control Panels erstellen. Jede Vorlage speichert lokalitätsspezifische Betreffzeilen, Absenderinformationen und Editor-Inhalte und wird durch den Code des E-Mail-Presets identifiziert, mit dem sie verbunden ist. Verwenden Sie diesen Code, um die Vorlage über Notify (E-Mail-Payload email_template) oder einen Customer Journey Send email-Punkt zu senden.

Basis-URL

https://rpc-api.svc-nue.pushwoosh.com

Alle Endpunkte werden über HTTPS bereitgestellt. Anfragen und Antworten verwenden application/json, sofern nicht anders angegeben.

Authentifizierung

Jede Anfrage muss einen Authorization-Header mit Ihrem Server-API-Token enthalten:

Authorization: Api IHR_API_TOKEN

Konventionen

Feldnamen: Anfragekörper und Query-/Pfadparameter akzeptieren lowerCamelCase (zum Beispiel previewSettings, searchByLabel, includeHtml) – der Server verarbeitet beide Schreibweisen. Antworten werden immer mit den Proto-Feldnamen in snake_case marshalled (per_page, email_template, sender_info, preview_settings usw.). Die Antwortbeispiele und die Objektreferenz unten verwenden diese Schreibweise.
code: Jede Vorlagenantwort enthält den Code des verbundenen E-Mail-Presets, nicht eine interne Vorlagen-ID. Übergeben Sie denselben Code an Get, Update, Delete und an die oben genannten Messaging-/Journey-APIs.
Nicht ausgefüllte Felder: Antworten enthalten alle Felder, auch wenn sie leer sind oder den Wert Null haben.

Fehlerantworten

HTTP-Status	Bedeutung
`400 Bad Request`	Ungültiges Argument – ein erforderliches Feld fehlt oder ist fehlerhaft, oder eine Vorbedingung ist fehlgeschlagen (z. B. das Löschen einer Vorlage, die noch von einer Journey verwendet wird).
`401 Unauthorized`	Fehlender oder ungültiger `Authorization`-Header.
`403 Forbidden`	Die Anwendung oder das Preset gehört nicht zum Konto des Aufrufers.
`404 Not Found`	Die Vorlage, das Preset oder die Anwendung wurde nicht gefunden.
`500 Internal Server Error`	Unerwarteter serverseitiger Fehler.

Endpunkte

Methode	Pfad	Beschreibung
`POST`	`/api/email_templates`	Eine neue E-Mail-Vorlage erstellen
`GET`	`/api/email_templates`	E-Mail-Vorlagen einer Anwendung auflisten
`GET`	`/api/email_templates/{code}`	Eine einzelne E-Mail-Vorlage abrufen
`PUT`	`/api/email_templates/{code}`	Eine E-Mail-Vorlage aktualisieren
`DELETE`	`/api/email_templates/{code}`	Eine E-Mail-Vorlage löschen
`POST`	`/api/email_templates:clone`	Eine E-Mail-Vorlage in eine Anwendung klonen

Erstellen

Erstellt eine neue E-Mail-Vorlage – ihren Editor-Inhalt plus ein verbundenes E-Mail-Preset – in einer Anwendung und gibt den generierten Vorlagencode zurück.

POST /api/email_templates

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
`application`	string	Ja	Der Pushwoosh-Anwendungscode, in dem die Vorlage erstellt werden soll.
`name`	string	Ja	Vorlagenname, 1–255 Zeichen.
`content`	object	Ja	Das E-Mail-Inhaltsobjekt.
`label`	string	Nein	Freitext-Label, bis zu 255 Zeichen.
`categories`	array of strings	Nein	Kategorienamen, mit denen die Vorlage getaggt werden soll.
`previewSettings`	object	Nein	Beliebige Editor-Vorschau-Einstellungen, die unverändert gespeichert und zurückgegeben werden.
`system`	boolean	Nein	Markiert die Vorlage als Systemvorlage – eine interne Funktion, z. B. ein synchronisiertes Blockfragment. Systemvorlagen sind in der `List`-Anzeige ausgeblendet (siehe Hinweis unten), bleiben aber per Code erreichbar. Standardmäßig `false`.

Beispiel für eine Anfrage

{
  "application": "XXXXX-XXXXX",
  "name": "Willkommens-E-Mail",
  "label": "Onboarding",
  "categories": ["Lifecycle"],
  "content": {
    "senderInfo": {
      "from": { "email": "hallo@acme.com", "name": "Acme" },
      "replyTo": { "email": "support@acme.com", "name": "Acme Support" }
    },
    "subject": { "en": "Willkommen bei Acme!", "default": "Willkommen bei Acme!" },
    "pushwoosh": {
      "html": "<html><body>Willkommen, {name|string|dort}!</body></html>",
      "localizationData": { "default": { "name": "dort" } }
    }
  }
}

Antwort

Gibt { "email_template": { ... } } zurück – das erstellte E-Mail-Vorlagenobjekt, aber ohne content (dieser Endpunkt gibt es nicht zurück). Rufen Sie Get mit dem zurückgegebenen code auf, wenn Sie den Inhalt zurücklesen müssen.

Auflisten

Listet die E-Mail-Vorlagen einer Anwendung auf – nur Metadaten, kein Inhalt – mit Paginierung, Sortierung und Filterung nach Name, Label oder Kategorie.

GET /api/email_templates

Query-Parameter

Parameter	Typ	Erforderlich	Beschreibung
`application`	string	Ja	Der Anwendungscode, für den Vorlagen aufgelistet werden sollen.
`orderBy`	string	Nein	`NAME` (Standard), `CREATED` oder `UPDATED`.
`orderDirection`	string	Nein	`ASC` (Standard) oder `DESC`.
`page`	integer	Nein	Nullbasierter Seitenindex.
`perPage`	integer	Nein	Seitengröße. Standardmäßig `100`, wenn weggelassen oder `0`. Dieser Endpunkt erzwingt kein explizites Maximum.
`searchByName`	string	Nein	Teilstring-Übereinstimmung (`like %value%`) mit dem Namen oder dem Code der Vorlage – eine der beiden Übereinstimmungen genügt.
`searchByLabel`	string	Nein	Teilstring-Übereinstimmung auf dem Label (`like %label%`) oder exakte Übereinstimmung, wenn `strictSearchByLabel` `true` ist.
`strictSearchByLabel`	boolean	Nein	Verwendet exakte Übereinstimmung anstelle von Teilstring für `searchByLabel`.
`searchByCategory`	array of strings	Nein	Wiederholen Sie den Parameter, um nach mehreren Kategorien zu filtern, z. B. `?searchByCategory=lifecycle&searchByCategory=promo`.

Antwort

Feld	Typ	Beschreibung
`email_templates`	array of objects	Die aktuelle Seite der E-Mail-Vorlagenobjekte. `content` ist bei jedem Element `null`.
`page`	integer	Der zurückgegebene Seitenindex.
`per_page`	integer	Die für diese Antwort verwendete Seitengröße.
`total`	integer	Gesamtzahl der Vorlagen, die den Filtern entsprechen, über alle Seiten hinweg.

Beispiel für eine Antwort

{
  "email_templates": [
    { "code": "AAAAA-BBBBB", "name": "Willkommens-E-Mail", "label": "Onboarding", "categories": ["Lifecycle"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Abrufen

Gibt eine einzelne E-Mail-Vorlage anhand ihres Codes zurück, einschließlich Absenderinformationen, lokalitätsspezifischer Betreffzeilen und des vollständigen Editor-Inhalts.

GET /api/email_templates/{code}

Pfadparameter

Parameter	Typ	Beschreibung
`code`	string	Der Code der Vorlage (der Code des verbundenen E-Mail-Presets).

Query-Parameter

Parameter	Typ	Erforderlich	Beschreibung
`includeHtml`	boolean	Nein	Ob das gerenderte `html` zusammen mit dem Editor-Inhalt zurückgegeben werden soll. Standardmäßig `true`. Setzen Sie es auf `false`, um es zu überspringen – es macht normalerweise über die Hälfte der Payload aus, und der Editor-Inhalt beschreibt die Vorlage bereits.

Antwort

Gibt { "email_template": { ... } } zurück, das vollständige E-Mail-Vorlagenobjekt.

Aktualisieren

Aktualisiert eine bestehende E-Mail-Vorlage anhand ihres Codes und überschreibt die angegebenen Felder.

PUT /api/email_templates/{code}

Pfadparameter

Parameter	Typ	Beschreibung
`code`	string	Der zu aktualisierende Code der Vorlage.

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
`name`	string	Nein	Neuer Name, 1–255 Zeichen. Weglassen, um den aktuellen Namen beizubehalten.
`content`	object	Nein	Neues E-Mail-Inhaltsobjekt, das den gespeicherten Inhalt vollständig ersetzt. Weglassen, um den Inhalt unverändert zu lassen.
`label`	string	Nein	Neues Label. Wird immer überschrieben – weglassen oder `""` senden, um es zu löschen.
`categories`	array of strings	Nein	Neuer vollständiger Satz von Kategorienamen. Weglassen, um Kategorien unverändert zu lassen; `[]` senden, um sie zu löschen.
`previewSettings`	object	Nein	Neue Vorschau-Einstellungen. Weglassen, um sie unverändert zu lassen.

Beispiel für eine Anfrage

{
  "name": "Willkommens-E-Mail v2",
  "label": "Onboarding",
  "content": {
    "senderInfo": { "from": { "email": "hallo@acme.com", "name": "Acme" } },
    "subject": { "default": "Willkommen bei Acme – aktualisiert!" },
    "pushwoosh": {
      "html": "<html>...</html>",
      "localizationData": {}
    }
  }
}

Antwort

Gibt { "email_template": { ... } } zurück – das aktualisierte E-Mail-Vorlagenobjekt, ebenfalls ohne content. Rufen Sie Get auf, wenn Sie den Inhalt zurücklesen müssen.

Löschen

Löscht eine E-Mail-Vorlage und das zugehörige Preset anhand des Codes und entfernt den gespeicherten Inhalt.

DELETE /api/email_templates/{code}

Pfadparameter

Parameter	Typ	Beschreibung
`code`	string	Der zu löschende Code der Vorlage.

Antwort

Ein leeres Objekt bei Erfolg: {}.

Klonen

Klont eine E-Mail-Vorlage – ihren Inhalt und ihr Preset – in eine Zielanwendung, optional unter einem neuen Namen.

POST /api/email_templates:clone

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
`emailPresetCode`	string	Ja	Der `code` der zu klonenden Vorlage (wie von `Create`, `Get`, `List` oder `Update` zurückgegeben). Hier `emailPresetCode` genannt, da es der Code des verbundenen E-Mail-Presets ist – siehe Konventionen.
`application`	string	Ja	Ziel-Anwendungscode. Kann dieselbe Anwendung sein oder eine andere, die zum selben Konto gehört.
`name`	string	Nein	Name für den Klon, 1–255 Zeichen. Standardmäßig der Name der Quellvorlage.

Beispiel für eine Anfrage

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "Willkommens-E-Mail (Kopie)"
}

Antwort

Feld	Typ	Beschreibung
`email_preset_code`	string	Der `code` der neuen Vorlage – derselbe Bezeichner, den `Get`/`Update`/`Delete` als `code` bezeichnen.

Objektreferenz

Die unten stehenden Feldnamen entsprechen dem, was Get, List, Update und Create tatsächlich zurückgeben – snake_case Proto-Feldnamen (siehe Konventionen). Wenn Sie dieselben Strukturen in einem Anfragekörper zurücksenden (Create, Update), funktioniert auch die in den obigen Anfragebeispielen verwendete lowerCamelCase-Form; der Server akzeptiert bei der Eingabe beide Schreibweisen.

E-Mail-Vorlagenobjekt

Feld	Typ	Beschreibung
`code`	string	Code des verbundenen E-Mail-Presets. Identifiziert diese Vorlage überall sonst in der API.
`name`	string	Vorlagenname.
`label`	string	Freitext-Label.
`categories`	array of strings	Kategorienamen.
`content`	object	Das E-Mail-Inhaltsobjekt. Nur von `Get` ausgefüllt; `null` in `Create`-, `List`- und `Update`-Antworten.
`preview_settings`	object	Beliebige Editor-Vorschau-Einstellungen.
`created`	string (RFC 3339)	Zeitstempel der Erstellung.
`updated`	string (RFC 3339)	Zeitstempel der letzten Aktualisierung.

E-Mail-Inhaltsobjekt

Feld	Typ	Beschreibung
`sender_info`	object	Absenderinformationsobjekt – `from`- und `reply_to`-Adressen.
`subject`	object (map)	Lokalitätsspezifischer Betreff, z. B. `{ "en": "Betreff", "default": "Betreff" }`.
`unlayer` / `pushwoosh` / `smartcards`	object	Der Editor-Inhalt. Genau eines davon muss gesetzt sein – es wählt aus, welcher Editor die Vorlage erstellt hat (und rendern wird). Siehe Editor-Arten unten.

Editor-Arten

Art	Feld	Erforderliche Unterfelder	Beschreibung
`unlayer`	`html`, `localization_data`, `editor_config`	`editor_config`, `localization_data`	Drag-and-Drop-Block-Editor (Unlayer). `editor_config` ist das Unlayer-Design-JSON.
`pushwoosh`	`html`, `localization_data`	`localization_data`	Pushwooshs eigener HTML-basierter Editor. Empfohlen für programmatisch/API-erstellte Vorlagen.
`smartcards`	`html`, `localization_data`, `content`	`content`, `localization_data`	Smart Cards Block-Editor; `content` ist sein editorspezifisches JSON.

Bei jeder Art ist html die gerenderte Ausgabe. localization_data ist der eigene lokalitätsspezifische Inhalt dieses Editors: ein Objekt, das nach Lokalisierungscode (en, es, default, …) geschlüsselt ist, wobei jeder Wert die Kopie der Editorfelder für diese Lokalisierung ist. Seine innere Struktur ist editorspezifisch und für diese API undurchsichtig – die API speichert und gibt sie unverändert zurück. Es ist bei Create/Update für jede Art erforderlich (senden Sie {}, wenn nichts zu lokalisieren ist).

Immer wenn die API content zurückgibt (derzeit nur Get, da Create und Update es nicht zurückgeben), garantiert sie, dass eine Lokalisierung als default verfügbar gemacht wird: Wenn Sie selbst keinen default-Schlüssel gesendet haben, wird en (oder, falls das nicht vorhanden ist, der erste Lokalisierungsschlüssel) zu default befördert und umbenannt – jede andere von Ihnen gesendete Lokalisierung bleibt unverändert. subject erhält die gleiche Behandlung. Dies unterscheidet sich von Clone, das nur diesen einen Standard-Lokalisierungswert beibehält und den Rest verwirft.

Diese Umbenennung wird nur beim Erstellen der Antwort angewendet – sie wird jedoch beim Schreiben nicht rückgängig gemacht. Wenn Sie eine Get-Antwort unverändert nehmen und direkt an Update senden, ist der beförderte Schlüssel (z. B. en) nun buchstäblich default, und Update speichert genau das, was Sie senden: Der ursprüngliche en-Schlüssel ist von da an dauerhaft verschwunden. Wenn Sie den ursprünglichen Lokalisierungsschlüssel beibehalten müssen, benennen Sie default selbst wieder um, bevor Sie Update aufrufen.

Text innerhalb von html oder einem localization_data-Wert kann Dynamic Content-Tags enthalten, z. B. {name|string|dort} – diese werden gegen die Tags des Empfängergeräts aufgelöst, wenn die E-Mail tatsächlich gesendet wird. Diese API löst sie nicht auf; sie speichert und gibt nur den Text zurück, den Sie dort eingefügt haben.

Absenderinformationsobjekt

Feld	Typ	Beschreibung
`from`	object	`{ "email": string, "name": string }` – Absenderadresse.
`reply_to`	object	`{ "email": string, "name": string }` – Antwortadresse.

Beide email-Unterfelder müssen, wenn sie nicht leer sind, gültige E-Mail-Adressen sein.

E-Mail-Vorlagen-API

Basis-URL

Authentifizierung

Konventionen

Fehlerantworten

Endpunkte

Erstellen

Anfragekörper

Beispiel für eine Anfrage

Antwort

Auflisten

Query-Parameter

Antwort

Beispiel für eine Antwort

Abrufen

Pfadparameter

Query-Parameter

Antwort

Aktualisieren

Pfadparameter

Anfragekörper

Beispiel für eine Anfrage

Antwort

Löschen

Pfadparameter

Antwort

Klonen

Anfragekörper

Beispiel für eine Anfrage

Antwort

Objektreferenz

E-Mail-Vorlagenobjekt

E-Mail-Inhaltsobjekt

Editor-Arten

Absenderinformationsobjekt

Verwandte Themen