E-Mail-Vorlagen-API

Die E-Mail-Vorlagen-API verwaltet die wiederverwendbaren E-Mail-Vorlagen hinter den E-Mail-Presets einer Anwendung – dieselben Vorlagen, die Sie im E-Mail-Editor des Control Panels erstellen. Jede Vorlage speichert Betreffzeilen, Absenderinformationen und Editor-Inhalte pro Gebietsschema 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 point 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 YOUR_API_TOKEN

Konventionen

Feldnamen: Anfragekörper und Abfrage-/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 zugehörigen 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, um die Vorlage zu taggen.
`previewSettings`	object	Nein	Beliebige Editor-Vorschau-Einstellungen, die unverändert gespeichert und zurückgegeben werden.
`system`	boolean	Nein	Markiert die Vorlage als System-Vorlage – eine interne Funktion, z. B. ein Fragment für synchronisierte Blöcke. System-Vorlagen sind in der `List` (siehe Hinweis unten) ausgeblendet, bleiben aber per Code erreichbar. Standard ist `false`.

Beispiel für eine Anfrage

{
  "application": "XXXXX-XXXXX",
  "name": "Welcome email",
  "label": "onboarding",
  "categories": ["lifecycle"],
  "content": {
    "senderInfo": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "replyTo": { "email": "support@acme.com", "name": "Acme Support" }
    },
    "subject": { "en": "Welcome to Acme!", "default": "Welcome to Acme!" },
    "pushwoosh": {
      "html": "<html><body>Welcome, {name|string|there}!</body></html>",
      "localizationData": { "default": { "name": "there" } }
    }
  }
}

Antwort

Gibt { "email_template": { ... } } zurück – das erstellte E-Mail-Vorlagenobjekt, aber ohne content (dieser Endpunkt gibt ihn 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

Abfrageparameter

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. Standard ist `100`, wenn weggelassen oder `0`. Dieser Endpunkt erzwingt kein explizites Maximum.
`searchByName`	string	Nein	Teilstring-Übereinstimmung (`like %value%`) mit dem Namen der Vorlage oder ihrem Code – eine der beiden Übereinstimmungen genügt.
`searchByLabel`	string	Nein	Teilstring-Übereinstimmung für das 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 einer von 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": "Welcome email", "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, Betreffzeilen pro Gebietsschema und dem vollständigen Editor-Inhalt.

GET /api/email_templates/{code}

Pfadparameter

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

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
`includeHtml`	boolean	Nein	Gibt an, ob das gerenderte `html` zusammen mit dem Editor-Inhalt zurückgegeben werden soll. Standard ist `true`. Setzen Sie es auf `false`, um es zu überspringen – es macht typischerweise ü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 nach Code und überschreibt die angegebenen Felder.

PUT /api/email_templates/{code}

Pfadparameter

Parameter	Typ	Beschreibung
`code`	string	Der Code der zu aktualisierenden 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": "Welcome email v2",
  "label": "onboarding",
  "content": {
    "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" } },
    "subject": { "default": "Welcome to Acme — updated!" },
    "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 nach Code und entfernt den gespeicherten Inhalt.

DELETE /api/email_templates/{code}

Pfadparameter

Parameter	Typ	Beschreibung
`code`	string	Der Code der zu löschenden 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 Vorlage (wie von `Create`, `Get`, `List` oder `Update` zurückgegeben), die geklont werden soll. Hier `emailPresetCode` genannt, weil es der Code des verbundenen E-Mail-Presets ist – siehe Konventionen.
`application`	string	Ja	Anwendungscode des Ziels. Kann dieselbe Anwendung sein oder eine andere, die zum selben Konto gehört.
`name`	string	Nein	Name für den Klon, 1–255 Zeichen. Standard ist der Name der Quellvorlage.

Beispiel für eine Anfrage

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "Welcome email (copy)"
}

Antwort

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

Objektreferenz

Die folgenden Feldnamen entsprechen dem, was Get, List, Update und Create tatsächlich zurückgeben – Proto-Feldnamen in snake_case (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. Wird nur von `Get` ausgefüllt; `null` in den Antworten von `Create`, `List` und `Update`.
`preview_settings`	object	Beliebige Editor-Vorschau-Einstellungen.
`created`	string (RFC 3339)	Erstellungszeitstempel.
`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)	Betreff pro Gebietsschema, z. B. `{ "en": "Subject", "default": "Subject" }`.
`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-Blockeditor (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-Blockeditor; `content` ist sein editorspezifisches JSON.

Bei jeder Art ist html die gerenderte Ausgabe. localization_data ist der eigene Inhalt dieses Editors pro Gebietsschema: ein Objekt, das nach Gebietsschemacode (en, es, default, …) geschlüsselt ist, wobei jeder Wert die Kopie der Editorfelder für dieses Gebietsschema ist. Seine innere Form 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 bei Get, da Create und Update ihn nicht zurückgeben), garantiert sie, dass ein Gebietsschema als default verfügbar gemacht wird: Wenn Sie selbst keinen default-Schlüssel gesendet haben, wird en (oder, falls das fehlschlägt, der erste Gebietsschemaschlüssel) zu default befördert und umbenannt – jedes andere von Ihnen gesendete Gebietsschema bleibt unverändert. subject erhält die gleiche Behandlung. Dies unterscheidet sich von Clone, das nur diesen einen Standard-Gebietsschema-Wert beibehält und den Rest verwirft.

Diese Umbenennung wird nur beim Erstellen der Antwort angewendet – aber sie wird beim Schreiben nicht rückgängig gemacht. Wenn Sie eine Get-Antwort unverändert übernehmen 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 Gebietsschemaschlü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|there} – 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 eingeben.

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

Abfrageparameter

Antwort

Beispiel für eine Antwort

Abrufen

Pfadparameter

Abfrageparameter

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