API-Flow

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.
• Mit Plus lieferst du individuelle Bilder über images, wenn das Design API-Bilder definiert. Alle Bild-Feldnamen der versendbaren Varianten sind dann Pflicht, beginnend mit dem ersten freien Standardnamen image_url_1.
• 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.

Für API-Flow-Mailings gibt es kein Performance-Tracking. Sie erscheinen deshalb nicht in der Komponente Mailing Performance auf dem Dashboard.

Ein neuer Flow ist ein Entwurf: PostPal speichert ihn beim Einrichten automatisch, und Requests an ihn werden mit 422 abgelehnt. Mit „Flow erstellen“ wird er aktiv; danach ist er 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 oder API-Bildern in versendbaren oder für offene Einträge benötigten Varianten sind für API-Flows vorgesehen und stehen in normalen Kampagnen nicht zur Auswahl.

API-Bilder: PostPal lädt öffentliche HTTPS-Bildadressen ohne Weiterleitung vor dem Anlegen eines Eintrags herunter und prüft Datei und Druckauflösung. Das Bild wird vollständig als Fit in den rechteckigen Rahmen eingepasst; das im Design Editor hochgeladene Beispiel wird nie als Ersatz gedruckt. Auch reine API-Bilddesigns werden pro Empfänger gerendert. Formate, Grenzwerte und Fehlermeldungen stehen in der REST-API-Anleitung.

Ab dem ersten API-Eintrag ist der Bildvertrag fest, auch wenn dieser Eintrag bereits verarbeitet wurde. Neue oder entfernte API-Bilder, umbenannte Felder und Designwechsel mit einem anderen Bildvertrag werden abgelehnt. Eine 0-%-Variante ohne offene Einträge ist davon ausgenommen und darf weiter bearbeitet werden.

Nummern am Anfang einer Markdown-Zeile bleiben so erhalten, wie du sie übermittelst. Das gilt auch für Datumsangaben wie 20. Mai 2026 und 30. Mai 2026. Nummerierte Listen werden nicht automatisch neu durchnummeriert.

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 Design Editor 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 Design Editor 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.

Emojis in content-Feldern und in Empfängerdaten wie dem Vornamen werden als farbige Google-Noto-Grafiken gedruckt, in der Vorschau genauso wie im finalen Druck-PDF. Der Emoji-Bestand ist fest in PostPal hinterlegt und kann sehr neue Zeichen noch nicht enthalten. Trifft ein solches Zeichen ein, zeigt die Vorschau des Eintrags den Hinweis auf ein nicht unterstütztes Emoji — ein erneuter Versuch hilft dort nicht. Beim Druck greift dieselbe Regel wie bei anderen Einzelfehlern: Nur der betroffene Empfänger wird übersprungen und gemeldet, alle übrigen werden normal gedruckt.

Die technische API-Referenz findest du in der offiziellen API-Dokumentation, maschinenlesbar in der OpenAPI-Datei.

Die verfügbaren Designformate, Materialien, Veredelungen und Zahlungsarten im Flow-Formular richten sich nach der veröffentlichten Preisliste. Ihre Namen und Rabatte werden daraus übernommen. Du kannst nur Formate wählen, die auch der Design Editor unterstützt. Ohne veröffentlichte Preisliste kannst du einen Entwurf anfangen, aber noch keinen Flow fertig erstellen.