REST-API-Referenz

Alle Pfade beziehen sich auf https://shopify.workflow-transactional-email.app. Für jeden Endpunkt mit Ausnahme des Index ist Authorization: Bearer fak_... erforderlich - siehe Authentifizierung und API-Schlüssel.

Die Antworten liegen im JSON-Format vor. Fehlermeldungen weisen durchgehend dieselbe Struktur auf:

{ "error": "Invalid or missing API key" }

Index und Identität

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1	keine	API-Index. Bestätigt, dass die API verfügbar ist, und gibt die aktuelle Version an
GET	/api/v1/me	lesen	Überprüfen Sie, ob ein Schlüssel funktioniert, und ermitteln Sie dessen Zugriffsebene

Da der Index keinen Schlüssel benötigt, eignet er sich gut als Ziel für einen Sicherheitscheck.

E-Mail-Layouts

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1/email-templates	lesen	E-Mail-Layouts auflisten. Unter q können Sie nach Name, Betreff und Beschreibung suchen; unter category=transactional oder category=marketing wird jeweils ein E-Mail-Typ aufgelistet.
BEITRAG	/api/v1/email-templates	schreiben	Ein Layout erstellen
GET	/api/v1/email-templates/:id	lesen	Ein Layout mit seinem Design bzw. seinen Anhängen, seinen Fußzeilentexten und der Liste seiner Sprachen
PUT / PATCH	/api/v1/email-templates/:id	schreiben	Ein Layout ändern. Es ändern sich nur die Felder, die Sie übermitteln.
LÖSCHEN	/api/v1/email-templates/:id	schreiben	Ein Layout mit seinen Übersetzungen und Versionen löschen
GET	/api/v1/layout-schema	lesen	So erstellen Sie ein Layout: das Designformat, die Standardeinstellungen der einzelnen Blöcke, die verfügbaren Liquid-Elemente, Einschränkungen und ein Beispiel

Die Liste akzeptiert page (Standardwert 1), limit (Standardwert 25, maximal 100) sowie q, wodurch nach Name, Betreff und Beschreibung gesucht wird. Über die API ist keine Filterung nach Typ möglich; lesen Sie stattdessen zu jedem Layout den Abschnitt category.

Ein Layout enthält folgende Felder:

Feld	Anmerkungen
name, description	Name erforderlich, maximal 200 Zeichen; Beschreibung maximal 2000
bodyType	visual (Standard) oder text. Nach der Erstellung unveränderlich
defaultLocale	Die Sprache des Layouts selbst: en, sofern nicht anders festgelegt
category	transactional (Standard) oder marketing. Siehe unten
subject, previewText	Getränke sind erlaubt. Das Fach ist Pflichtfach.
bodyDesign	Visuelle Layouts: { blocks, global?, header?, footer?, testVariables? }. Bitte senden Sie bei Änderungen das vollständige Design; der HTML-body wird daraus generiert.
body	Textlayouts: Der HTML-Body
attachments	Textlayouts: [{ filename, fileKey, sendAsLink? }] für hochgeladene Dateien (siehe Dateien unten) oder [{ filename, url }] für eine Datei, die beim Versenden der E-Mail über HTTPS abgerufen wird
marketingTexts	Die Fußzeilentexte eines Marketing-Layouts, auch null genannt. Siehe unten

„Liquid“ im Betreff, im Vorschautext, im Haupttext und in jedem Blocktext muss parst werden, und jede fileKey-Angabe muss zu Ihrem Shop gehören; andernfalls wird der Schreibvorgang mit einem 400-Fehler abgelehnt, der das betreffende Feld nennt. Lesen Sie GET /api/v1/layout-schema, bevor Sie ein visuelles Design erstellen: Es wird vom Builder selbst generiert und kann daher nicht abweichen.

Jeder Schreibvorgang über diese API wird im Versionsverlauf des Layouts gespeichert, genau wie beim Speichern in der App.

Layouts für Transaktionen und Marketing

category erläutert, wozu ein Layout dient. Ein Transaktionslayout wird unverändert an jeden Empfänger versendet. Ein Marketing-Layout überspringt Empfänger, die sich abgemeldet haben (ein Schritt, bei dem die E-Mail an die Empfänger im Feld „An“ nicht versendet wird und im Verlauf als SKIPPED angezeigt wird), wird als einzelne Nachricht pro Empfänger im Feld „An“ mit einem eigenen Abmeldelink versendet (maximal 20 pro Schritt) und endet mit dem Abmeldesatz sowie Ihren Unternehmensangaben. {{ unsubscribe_url }} sowie {{ unsubscribe_link }} - fügen Sie den Link selbst ein; in Transaktions-Layouts sind beide Felder leer. Die Händler-Seite hierzu finden Sie unter Marketing-E-Mails und Abmeldungen.

marketingTexts Ist der Text in der Fußzeile ein Marketinglayout, das anstelle der shopweiten Texte aus den Einstellungen verwendet wird:

{
  "marketingTexts": {
    "unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
    "unsubscribeLinkLabel": "Unsubscribe",
    "companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
  }
}

Jedes Feld ist optional. Ein festgelegtes Feld ersetzt den Einstellungstext für dieses Feld; die anderen bleiben unverändert. null (Standard) bedeutet, dass die Einstellungstexte in der Sprache der E-Mail verwendet werden. Beschränkungen: unsubscribeText und companyDetails sind auf 2000 Zeichen begrenzt, unsubscribeLinkLabel auf 100. Ein unsubscribeText muss {{ unsubscribe_link }} oder {{ unsubscribe_url }} enthalten, andernfalls wird der Schreibvorgang abgelehnt. Das Feld wird für jedes Layout gespeichert, jedoch nur bei Marketing-Layouts versendet.

Das Löschen eines Layouts wird niemals blockiert. Falls Schritte unter Shopify Flow noch auf dieses Layout verweisen, enthält die Antwort einen Parameter warning, der angibt, um wie viele Schritte es sich handelt; diese Schritte schlagen fehl, bis ein anderes Layout verwendet wird.

Übersetzungen

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1/email-templates/:id/translations	lesen	Jede Sprache eines Layouts mit ihrem Inhalt
GET	/api/v1/email-templates/:id/translations/:locale	lesen	Eine Sprache
PUT	/api/v1/email-templates/:id/translations/:locale	schreiben	Eine Sprache anlegen oder ersetzen
LÖSCHEN	/api/v1/email-templates/:id/translations/:locale	schreiben	Eine Sprache entfernen. In diesem Fall wird auf das Standardlayout zurückgegriffen.
BEITRAG	/api/v1/email-templates/:id/translations/:locale/promote	schreiben	Legen Sie diese Sprache als Hauptsprache des Layouts fest

:locale ist ein Sprachcode wie beispielsweise de, fr oder pt-br; Groß- und Kleinschreibung sowie Trennzeichen spielen keine Rolle. Pro Layout sind bis zu 30 Sprachen zulässig. Das Feld „Sprache“ im Schritt Shopify Flow wählt zum Zeitpunkt des Versands eine Sprache aus: zunächst die exakte Ländereinstellung, dann die Basissprache, anschließend eine regionale Variante und andernfalls das Layout selbst.

Eine PUT enthält den vollständigen übersetzten Inhalt: subject (erforderlich), previewText sowie bodyDesign (Bild) oder body (Text). Bitte lassen Sie Liquid-Tags und URLs unverändert. Zwei Felder beziehen sich speziell auf eine Übersetzung:

Feld	Textlayouts	Bedeutung
attachments	ja	Eine Liste (mit derselben Struktur wie die des Layouts) = sprachspezifische Anhänge; [] = keine Anhänge in dieser Sprache; null = die Anhänge des Layouts senden. Weggelassen = die aktuelle Auswahl beibehalten; eine neue Sprache verwendet die des Layouts. Visuelle Layouts übertragen ihre Anhänge als Blöcke in der Datei bodyDesign der jeweiligen Sprache und lehnen dieses Feld ab.
marketingTexts	irgendein	Die Fußzeilentexte dieser Sprache werden Feld für Feld über die des Layouts gelegt. null = die des Layouts. „Omitted“ = die aktuelle Auswahl beibehalten

Es wird eine Übersetzung mit denselben beiden Feldern zurückgegeben: attachments lautet null, während das Layout verwendet wird, und marketingTexts lautet null, während das Layout verwendet wird.

promote Tauscht das Layout und die Übersetzung aus: Das Layout übernimmt den Inhalt und die Ländereinstellung der Übersetzung, und sein ursprünglicher Inhalt wird zur Übersetzung für die Sprache, in der es zuvor verwendet wurde. Auch Anhänge und Fußzeilentexte tauschen ihre Plätze, sodass jede Sprache weiterhin das versendet, was sie zuvor versendet hat. Die Antwort enthält die Angaben promoted, previousMainLanguage sowie das Layout. Da es sich um eine einzige Version handelt, kann der Vorgang rückgängig gemacht werden.

Versionen

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1/email-templates/:id/versions	lesen	Gespeicherte Versionen, die neuesten zuerst. Die App behält die 25 neuesten Versionen bei
GET	/api/v1/email-templates/:id/versions/:version	lesen	Der vollständige Snapshot einer Version: Layout und alle Übersetzungen
BEITRAG	/api/v1/email-templates/:id/versions/:version/restore	schreiben	Bitte setzen Sie diese Version wieder ein. Als neue Version gespeichert
GET	/api/v1/email-templates/:id/versions/github?page=	lesen	Alle im verbundenen GitHub-Repository gespeicherten Versionen, 20 pro Seite
GET	/api/v1/email-templates/:id/versions/github/:sha	lesen	Das Layout, wie es zu einem bestimmten Commit stand
BEITRAG	/api/v1/email-templates/:id/versions/github/:sha/restore	schreiben	Eine GitHub-Version wiederherstellen, wie beim Speichern

Die GitHub-Endpunkte geben den Fehlercode 409 zurück, solange auf der Entwickler-Seite kein Repository verbunden ist. Siehe Versionsverlauf des Layouts und Speichern Sie einen unbegrenzten Layout-Verlauf auf GitHub.

E-Mail-Absender

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1/smtp-configs	lesen	SMTP-Absender auflisten
GET	/api/v1/senders	lesen	Verbundene Postfächer auflisten (Microsoft 365, Google)

SMTP-Absender geben hasUsername und hasPassword anstelle der Anmeldedaten selbst an - beide Teile werden zurückgehalten, da der Benutzername ebenso Teil der Anmeldedaten ist wie das Passwort. Ein Absender bleibt anhand seines Namens, seines Hosts und seiner Absenderadresse identifizierbar. Verbundene Postfächer geben eine teilweise maskierte Adresse wie beispielsweise so***@example.com an und niemals ihre Anmeldetoken.

Nur-Lese-Zugriff. Sie können Absender in der App verbinden und bearbeiten.

Geheimnisse

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1/secrets	lesen	Geheime Namen und Beschreibungen auflisten

Gibt hasValue zurück, niemals den Wert selbst. Es gibt keinen Endpunkt, über den ein Geheimnis wieder abgerufen werden kann. Erstellen und aktualisieren Sie Geheimnisse in der App.

Hochgeladene Dateien

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1/files	lesen	Liste der hochgeladenen Logos, Bilder und Anhänge
LÖSCHEN	/api/v1/files	schreiben	„Delete one“ von key im Hauptteil

Die Liste akzeptiert die Formate page, limit (maximal 100) und q für die Suche nach Dateinamen.

Fügen Sie „?usage=true“ hinzu, und jede Datei meldet zudem inUse sowie ein Array usedBy, in dem die Layouts und Voreinstellungen aufgeführt sind, die darauf verweisen. Auf diese Weise können Sie mit einer einzigen Abfrage alle Elemente ermitteln, die bedenkenlos gelöscht werden können. Da dabei Ihre Layouts und Voreinstellungen durchsucht werden, handelt es sich um eine Option, die aktiviert werden muss und nicht standardmäßig eingestellt ist.

Das Hochladen wird hier nicht unterstützt - fügen Sie Dateien über die Medienauswahl in der App hinzu.

HTTP-Anfragen

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1/http-requests	lesen	HTTP-Anfragen auflisten
BEITRAG	/api/v1/http-requests	schreiben	Erstellen Sie eines
GET	/api/v1/http-requests/:id	lesen	Holen Sie sich eines
PUT / PATCH	/api/v1/http-requests/:id	schreiben	Aktualisierung Nr. 1
LÖSCHEN	/api/v1/http-requests/:id	schreiben	Einen löschen
BEITRAG	/api/v1/http-requests/:id/test	ausführen	Führen Sie es am tatsächlichen Ziel aus

„List“ akzeptiert dieselben Parameter page, limit und q wie E-Mail-Layouts.

Die Ziel-url-Adresse muss http:// oder https:// lauten. Andere Schemata werden beim Speichern abgelehnt.

In den Header oder den Hauptteil eingetragene Anmeldedaten werden in jeder Antwort maskiert. Werte, auf die als {{ secrets.KEY }} verwiesen wird, werden unverändert zurückgegeben, da der Verweis selbst nicht sensibel ist.

Geschichte und Statistiken

Dies umfasst sowohl E-Mail-Versendungen als auch HTTP-Anfragen.

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1/history	lesen	Ausführung von Listen
GET	/api/v1/history/:id	lesen	Rufen Sie eine Ausführung mit Anforderungs- und Antwortdaten ab
GET	/api/v1/stats	lesen	Gesamtzahlen und Erfolgsquote

„History“ akzeptiert page, limit (max. 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) sowie actionConfigId, um nach einem einzelnen Layout oder einer einzelnen Anfrage zu filtern.

SKIPPED Es handelt sich um eine Marketing-E-Mail, deren Empfänger sich alle abgemeldet hatten: Es wurde nichts versendet, es wurde kein Kontingent verbraucht, und sie fließt nicht in die Erfolgsquote ein.

actionType Es muss sich genau um EMAIL oder HTTP_REQUEST handeln. Ein nicht erkannter Wert wird ignoriert und nicht abgelehnt, sodass bei einem Tippfehler das gesamte Ergebnis zurückgegeben wird, anstatt eine Fehlermeldung auszugeben.

„Stats“ akzeptiert Werte zwischen days (Standardwert 30, Maximalwert 365).

Statuscodes

Code	Bedeutung
200	Erfolg
201	Erstellt
400	Fehlerhafte Anfrage oder fehlgeschlagene Validierung. Das error gibt den Feldnamen an, zum Beispiel subject: required
401	Fehlender, fehlerhafter oder widerrufener API-Schlüssel
403	Der Schlüssel ist gültig, seine Berechtigungsstufe ist jedoch für diesen Endpunkt zu niedrig.
404	Nicht gefunden oder gehört zu einem anderen Geschäft
405	Falsche Methode für diesen Pfad
409	Ablehnung, da der Datensatz noch verwendet wird (Dateilöschung) oder keine Verbindung zu GitHub besteht (GitHub-Versionen)
429	Ratenbegrenzung - siehe unten
502	Die Anfrage wurde ausgeführt, doch das Ziel des Drittanbieters schlug fehl

Ein Datensatz, der zu einem anderen Geschäft gehört, liefert den Status 404 statt 403, sodass die API niemals bestätigt, dass eine ID an anderer Stelle existiert.

Ratenbegrenzungen

Zwei unabhängige Budgets, jeweils pro Schlüssel:

• 300 Anfragen pro 60 Sekunden über alle Endpunkte hinweg.
• Darüber hinaus werden 60 Einsätze pro Stunde durchgeführt, die das Gebiet POST /api/v1/http-requests/:id/test abdecken.

Wird einer dieser Werte überschritten, wird der Fehlercode 429 mit der Erläuterung error zurückgegeben. Das Ausführungsbudget ist bewusst knapp bemessen: Eine außer Kontrolle geratene Schleife, die in Echtzeit Anfragen an einen Zahlungsanbieter sendet, stellt einen weitaus schwerwiegenderen Fehler dar als ein langsames Skript.

Die Budgets gelten pro Schlüssel und nicht pro Shop, sodass eine Integration das Kontingent eines anderen Shops nicht aufbrauchen kann.