API-Flow
Ein API-Flow ist die automatisierte Versand-Engine von PostPal: Du lieferst Empfänger programmatisch über die API ein, PostPal sammelt sie und bildet in einem wiederkehrenden (wöchentlichen) Trigger-Fenster einen Batch, der als Postkarten-Aussendung verschickt wird. Abgerechnet wird nach der tatsächlich versendeten Batch-Größe. Jeder Flow benötigt ein hinterlegtes Postkarten-Design. Designs können Markdown-Flächen definieren, deren Inhalt pro API-Request individuell über `content` geliefert wird. QR-Codes müssen im Studio als API-QRs angelegt sein, wenn ihr Wert pro Request über `qr_codes` geliefert werden soll; diese `qr_codes`-Werte müssen vollständige scanbare HTTP(S)-URLs sein. Designs mit Markdown-Flächen sind API-Flow-Designs und werden in normalen Kampagnen nicht angeboten.
Ein API-Flow ist die automatisierte Versand-Engine von PostPal für programmatisch eingelieferte Empfänger. Statt eine fertige Audience zu versenden, nimmt ein Flow laufend einzelne Einträge über die PostPal-API entgegen und bündelt sie automatisch zu wiederkehrenden Aussendungen.
So funktioniert ein Flow:
- Du lieferst Empfänger über die API ein; sie werden als Einträge im Flow
gesammelt (Zustände:
pending,batched,skipped,failed). - Optional lieferst du pro Empfänger individuelle Markdown-Inhalte über
content, wenn das hinterlegte Design Markdown-Flächen definiert. - Optional lieferst du pro Empfänger individuelle QR-Werte über
qr_codes, wenn das hinterlegte Design QR-Codes mit API-Feldnamen definiert. - In einem wöchentlichen Trigger-Fenster bildet PostPal aus den fälligen Einträgen einen Batch und erzeugt daraus eine Postkarten-Aussendung.
- Abgerechnet wird nach der tatsächlichen Batch-Größe.
Ein Flow ist entweder aktiv oder pausiert und benötigt ein hinterlegtes Postkarten-Design. Reicht das Guthaben für einen Batch nicht, bleibt der Flow konfiguriert und die offenen Einträge werden im nächsten Lauf erneut versucht. Designs mit Markdown-Flächen sind für API-Flows reserviert und stehen in normalen Kampagnen nicht zur Auswahl.
Markdown-Inhalte sind an die im Design definierten API-Feldnamen gebunden. Alle Markdown-Flächen sind in v1 Pflichtfelder; unbekannte Schlüssel werden abgelehnt. PostPal akzeptiert nur die unterstützte Markdown-Teilmenge und prüft vor dem Speichern des Eintrags, ob der Text in die definierte Fläche passt.
Der Beispielinhalt, den du im Studio für eine Markdown-Fläche hinterlegst, ist
nur eine Design-Vorschau. Er wird bei API-Flows nicht als Fallback gedruckt.
Wenn das Design eine Markdown-Fläche mit dem API-Feldnamen personal_note
enthält, muss der API-Request content.personal_note liefern. Zeilenumbrüche
werden im Editor normal geschrieben, müssen im JSON-String der API aber als
\n übertragen werden.
QR-Werte sind ebenfalls an die im Design definierten API-Feldnamen gebunden. Ein
QR-Code gehört nur dann zum API-Vertrag, wenn er im Studio als API-QR angelegt
ist. URL-QRs speichern ihre Ziel-URL im Design und werden nicht über
qr_codes beliefert. Alle API-QR-Felder sind in v1 Pflichtfelder; unbekannte
Schlüssel werden abgelehnt. Der Wert unter qr_codes.<feldname> ist die vollständige
QR-Ziel-URL. PostPal prüft vor dem Speichern des Eintrags, ob diese URL eine
gültige HTTP(S)-URL ist und ob sie in einen QR-Code passt. Wenn das Design einen
API-QR mit dem API-Feldnamen voucher_url_1 enthält, muss der API-Request
qr_codes.voucher_url_1 als komplette scanbare URL liefern.
Die technische API-Referenz findest du auf der Entwicklerseite unter
https://app.getpostpal.com/developers/api; die maschinenlesbare
OpenAPI-Spezifikation liegt unter
https://app.getpostpal.com/developers/api/openapi.json.
Häufige Fragen
Wie unterscheidet sich ein API-Flow von einer normalen Kampagne?
Eine Kampagne richtet sich an eine bestehende Audience. Ein PostPal-API-Flow nimmt laufend einzelne Empfänger über die API entgegen und bündelt sie automatisch zu wiederkehrenden Aussendungen — ideal für ereignisgesteuerte Postkarten.
Wie wird ein API-Flow abgerechnet?
PostPal rechnet einen API-Flow nach der tatsächlichen Batch-Größe ab, nicht nach einer Mindestmenge. Die Trigger-Schwelle steuert nur, wann ein wöchentlicher Batch gebildet wird.
Was passiert, wenn mein Guthaben für einen Batch nicht reicht?
Der Flow bleibt konfiguriert und pausiert nicht dauerhaft. Die offenen Einträge werden im nächsten wöchentlichen Lauf erneut verarbeitet, und du wirst über das fehlende Guthaben benachrichtigt.
Brauche ich ein Design für einen API-Flow?
Ja. Jeder API-Flow benötigt ein hinterlegtes Postkarten-Design, bevor er Aussendungen erzeugen kann.
Kann ein API-Flow pro Empfänger längere individuelle Texte drucken?
Ja, wenn das Design Markdown-Flächen enthält. Dann muss der API-Request die passenden content-Schlüssel senden. PostPal prüft Syntax und Platzbedarf synchron, bevor ein Flow-Eintrag entsteht.
Kann ein API-Flow pro Request individuelle QR-Links drucken?
Ja, wenn das Design API-QRs mit API-Feldnamen enthält. Dann muss der API-Request die passenden qr_codes-Schlüssel als vollständige HTTP(S)-URLs senden. URL-QRs sind im Design konfiguriert und gehören nicht zum API-Vertrag. Unbekannte, fehlende, leere oder nicht passende QR-Werte werden mit 422 abgelehnt.
Wo finde ich die technische API-Dokumentation?
Die Entwicklerseite liegt unter https://app.getpostpal.com/developers/api. Die maschinenlesbare OpenAPI-Spezifikation findest du unter https://app.getpostpal.com/developers/api/openapi.json.