Hilfe Center
DE
Zur PostPal-App
API

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 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 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.
  • 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 Studio 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".

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"
  }
}

Rate-Limit: Jeder Account-API-Token darf POST /api/v1/postcards bis zu 600 Mal pro Minute und POST /api/v1/campaigns 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.

In PostPal öffnen

Häufige Fragen

Welche REST-Endpunkte gibt es?

Die v1-API bietet Endpunkte für Kampagnen und Postkarten: POST /api/v1/campaigns und POST /api/v1/postcards.

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.

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

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