REST-Endpunkte v1
Die PostPal REST-API v1 stellt produktive Endpunkte für programmatische Kampagnen und Postkarten bereit. Aktuell sind vor allem POST /api/v1/campaigns, GET /api/v1/flows und POST /api/v1/postcards relevant. Jeder Request braucht einen gültigen Account-API-Token und wird in den API-Logs protokolliert. Postkarten-Requests für API-Flows können zusätzlich designgebundene Markdown-Inhalte und API-QR-Werte und API-Bilder enthalten. Pro Account-API-Token sind bis zu 600 Postkarten- und 60 Kampagnen-Requests pro Minute erlaubt; überschrittene Limits werden mit Status 429 beantwortet. Die offizielle API-Dokumentation, die OpenAPI-Datei und die Postman-Collection stehen bereit.
Die REST-API v1 ist die programmatische Schnittstelle für technische Integrationen.
Wichtige Endpunkte:
POST /api/v1/campaigns- Kampagnen programmatisch anlegen.GET /api/v1/flows- aktive und pausierte API-Flows mitid(dieflow_id), Zielland (country) und den erwarteten Schlüsseln (fields) abrufen, dazu gesammelte Postkarten (entries) und Läufe (processing). Entwürfe kommen mitstatus=draft; eine Seite enthält bis zu 250 Flows (page,links.next).POST /api/v1/postcards- Postkarten-Requests einliefern.
Jeder Request braucht einen Account-API-Token. Prüfe Payload-Struktur und Pflichtfelder in diesen Ressourcen:
Wenn das verknüpfte API-Flow-Design Markdown-Flächen enthält, erwartet
POST /api/v1/postcards zusätzlich ein content-Objekt. Die Schlüssel müssen
exakt zu den im Design definierten Markdown-API-Feldnamen passen. Unterstützt
werden Absätze, Zeilenumbrüche, Fett, Kursiv, Aufzählungen und nummerierte
Listen.
Nicht unterstützte Syntax, fehlende oder unbekannte Schlüssel und Inhalte, die
nicht in die Fläche passen, werden mit 422 abgelehnt; Fit-Fehler enthalten
zusätzliche Hinweise in meta.markdown_fit_errors.
Beispieltexte aus dem Design Editor sind keine API-Fallbacks. API-Clients müssen den
Markdown-Inhalt immer im content-Objekt senden. Normale Zeilenumbrüche aus dem
Editor werden im JSON-Payload als \n übertragen, zum Beispiel
"Hallo **Max**,\n\n- Persönlicher Vorteil".
Zielland: Der Empfänger in to.country muss das Zielland des API-Flows sein.
Für einen Flow mit Zielland Österreich lautet der Wert AT; Österreich oder Austria gehen auch
und werden als AT gespeichert. Andere Länder werden
mit 422 abgelehnt. Der Absender in from.country ist davon nicht betroffen.
{
"flow_id": "FLOW_ID",
"to": {
"first_name": "Max",
"address_line1": "Musterstraße 42",
"zip": "1010",
"city": "Wien",
"country": "AT"
}
}
Emojis sind in content-Feldern und in Empfängerdaten wie to.first_name
erlaubt und werden als farbige Google-Noto-Grafiken gedruckt. Der Emoji-Bestand
ist fest in PostPal hinterlegt und kann sehr neue Zeichen noch nicht enthalten.
Ein solches Zeichen führt nicht zu einem 422 beim Request: Es fällt erst
beim Rendern auf. Die Vorschau des Eintrags weist dann darauf hin, und beim Druck
wird nur der betroffene Empfänger übersprungen und gemeldet.
Wenn das verknüpfte API-Flow-Design API-QRs mit API-Feldnamen enthält,
erwartet POST /api/v1/postcards zusätzlich ein qr_codes-Objekt. Die Schlüssel
müssen exakt zu den im Design definierten QR-API-Feldnamen passen. Jeder Wert
muss ein nicht leerer String mit höchstens 2048 Zeichen sein und bereits die
vollständige scanbare HTTP(S)-URL enthalten. Fehlende, unbekannte, leere oder
nicht passende QR-Werte werden mit 422 abgelehnt; Fit-Fehler enthalten
zusätzliche Hinweise in meta.qr_fit_errors. URL-QRs speichern ihre Ziel-URL
im Design und werden nicht im qr_codes-Objekt gesendet.
Ein einfacher qr_codes-Ausschnitt sieht zum Beispiel so aus:
{
"qr_codes": {
"voucher_url_1": "https://example.com/voucher/1",
"voucher_url_2": "https://example.com/voucher/2"
}
}
Wenn das Plus-Design API-Bilder enthält, ist zusätzlich ein images-Objekt
erforderlich. Es muss genau alle Bild-Feldnamen aller versendbaren Varianten
enthalten; ohne API-Bilder ist das Objekt nicht erlaubt. Der erste automatisch
vergebene Name ist üblicherweise image_url_1:
{
"images": {
"image_url_1": "https://example.com/image/1"
}
}
Jeder Wert ist eine nicht leere, höchstens 2048 Zeichen lange öffentliche
HTTPS-URL ohne Weiterleitung oder Zugangsdaten. PostPal lädt das Bild vor dem
Anlegen des Eintrags herunter und prüft, dass es sich vollständig als PNG, JPEG
oder WebP dekodieren lässt. Die Grenzen liegen bei 20 MB, 16 Megapixeln
und mindestens 300 dpi in jedem vom Feld verwendeten Druckrahmen. Alle
Bilder einer Anfrage zusammen dürfen höchstens 50 MB groß sein.
Unbekannte oder fehlende Schlüssel, unzulässige URLs, ungültige Bilder und zu
geringe Auflösung führen zu 422; Auflösungsfehler stehen zusätzlich in
meta.image_resolution_errors. Das Bild wird vollständig und proportional
zentriert im rechteckigen Rahmen dargestellt (Fit/contain). Freie Ränder
bleiben leer; das Bild wird weder beschnitten noch gestreckt. Das hochgeladene
Beispiel aus dem Design Editor dient ausschließlich der Vorschau.
Rate-Limit: Jeder Account-API-Token darf POST /api/v1/postcards bis zu
600 Mal pro Minute, POST /api/v1/campaigns und GET /api/v1/flows je bis zu
60 Mal pro Minute aufrufen. Wird das Limit überschritten, antwortet die API mit Status 429 und
den Headern X-RateLimit-Limit, X-RateLimit-Remaining und Retry-After, der
angibt, nach wie vielen Sekunden ein erneuter Versuch sinnvoll ist. Den Verlauf
und die genaue Fehlermeldung findest du in den API-Logs.
Häufige Fragen
Welche REST-Endpunkte gibt es?
Die v1-API bietet Endpunkte für Kampagnen, API-Flows und Postkarten: POST /api/v1/campaigns, GET /api/v1/flows und POST /api/v1/postcards.
Wie finde ich die flow_id für POST /api/v1/postcards?
Mit GET /api/v1/flows. Ohne Parameter liefert der Endpunkt die aktiven und pausierten API-Flows deines Accounts. Pro Flow enthält er id (die flow_id), name, status, country (das einzige Empfängerland) und fields: die Schlüssel, die das Design unter content, qr_codes und images erwartet. Live- und Test-Token funktionieren; erlaubt sind 60 Requests pro Minute.
Wie rufe ich Entwürfe und weitere Seiten von GET /api/v1/flows ab?
Entwürfe kommen nur mit dem Parameter status, zum Beispiel status=draft oder status=draft,active,paused; sie haben accepts_postcards false, weil sie noch keine Postkarten annehmen. Eine Seite enthält bis zu 250 Flows. Weitere Seiten liest du mit page oder indem du links.next folgst, bis der Wert null ist. Ein unbekannter Status oder eine ungültige Seite führt zu 422.
Sehe ich per API, wie viele Postkarten ein Flow gesammelt hat und wann er läuft?
Ja. GET /api/v1/flows liefert pro Flow unter entries die Zahl der gesammelten (pending), verarbeiteten (batched) und fehlgeschlagenen (failed) Postkarten und unter processing die Mindestmenge (trigger_threshold), den nächsten Lauf (next_processing_at) und den letzten Lauf (last_processed_at). Ein Lauf erzeugt nur ein Mailing, wenn die gesammelten Postkarten die Mindestmenge erreichen. Mit einem Test-Token beziehen sich diese Werte auf Test-Postkarten. Unter meta stehen die Zahl aller Flows je Status (status_counts) und der früheste nächste Lauf der aktiven Flows.
Wie authentifiziere ich API-Requests?
Du verwendest einen Account-API-Token aus den PostPal API-Einstellungen.
Gibt es maschinenlesbare Dokumentation?
Ja. Die offizielle API-Dokumentation, die OpenAPI-Datei und die Postman-Collection stehen bereit.
Kann POST /api/v1/postcards individuelle längere Texte enthalten?
Ja, wenn das verknüpfte API-Flow-Design Markdown-Flächen definiert. Dann müssen die passenden content-Schlüssel mitgeliefert werden; nicht passende, fehlende oder überlaufende Inhalte werden mit 422 abgelehnt.
In welches Land darf POST /api/v1/postcards senden?
Nur in das Zielland des API-Flows. Mögliche Zielländer sind Deutschland (DE), Österreich (AT), die Niederlande (NL), die Schweiz (CH), Italien (IT) und Frankreich (FR). Der Empfänger im Feld to.country muss das Zielland des Flows haben, als Ländercode (DE) oder als gängiger Name (Deutschland, Germany); andere Länder werden mit 422 abgelehnt. Der Absender (from) ist davon nicht betroffen.
Kann POST /api/v1/postcards individuelle QR-Ziele enthalten?
Ja, wenn das verknüpfte API-Flow-Design API-QRs mit API-Feldnamen definiert. Dann müssen die passenden qr_codes-Schlüssel als vollständige HTTP(S)-URLs mitgeliefert werden. URL-QRs sind im Design konfiguriert und werden nicht im qr_codes-Objekt gesendet.
Kann POST /api/v1/postcards individuelle Bilder enthalten?
Ja, wenn das Plus-Design API-Bilder definiert. Sende im images-Objekt genau die Bild-Feldnamen aller versendbaren Varianten, zum Beispiel image_url_1. Jeder Wert muss eine öffentlich erreichbare HTTPS-URL ohne Weiterleitung sein. PNG, JPEG und WebP werden vor Annahme vollständig dekodiert; erlaubt sind höchstens 20 MB, 16 Megapixel und mindestens 300 dpi bei der gedruckten Größe; alle Bilder einer Anfrage zusammen höchstens 50 MB. Fehlende oder unbekannte Schlüssel, ungültige Dateien und zu geringe Auflösung führen zu 422. Das Bild wird vollständig als Fit in seinen Rahmen eingepasst; das Beispiel aus dem Design Editor wird nie als Ersatz gedruckt.
Kann ich Emojis in content-Feldern und Empfängerdaten senden?
Ja. Gängige Unicode-Emojis werden als farbige Google-Noto-Grafiken gedruckt und nie als Fragezeichen. Der Emoji-Bestand ist fest in PostPal hinterlegt und kann sehr neue Zeichen noch nicht enthalten; ein solcher Wert wird beim Request nicht abgelehnt, die Vorschau des Eintrags weist aber darauf hin, und beim Druck wird nur dieser eine Empfänger übersprungen und gemeldet.
In welcher Sprache antwortet die API bei Fehlern?
Auf Englisch, wie die API-Dokumentation. Das gilt für alle Endpunkte der v1-API und für die Hinweise in meta, zum Beispiel suggested_action. Namen aus der PostPal-Oberfläche wie „Flow erstellen“ stehen in der Meldung so, wie du sie in der App siehst. Die Meldungen findest du auch in den API-Logs.
Gibt es ein Rate-Limit für die REST-API?
Ja. POST /api/v1/postcards erlaubt bis zu 600 Requests pro Minute pro Account-API-Token, POST /api/v1/campaigns und GET /api/v1/flows je bis zu 60 Requests pro Minute. Wird das Limit überschritten, antwortet die API mit Status 429 und den Headern X-RateLimit-Limit, X-RateLimit-Remaining sowie Retry-After.