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. Die offizielle Entwicklerdokumentation findest du unter `https://app.getpostpal.com/developers/api`; OpenAPI und Postman stehen unter `https://app.getpostpal.com/developers/api/openapi.json` und `https://app.getpostpal.com/developers/api/postman.json` 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. Nutze die Entwicklerseite, OpenAPI-Datei oder Postman-Datei, um Payload-Struktur und Pflichtfelder genau zu prüfen:

Entwicklerseite: https://app.getpostpal.com/developers/api
OpenAPI JSON: https://app.getpostpal.com/developers/api/openapi.json
Postman Collection: https://app.getpostpal.com/developers/api/postman.json

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

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

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 Entwicklerseite liegt unter https://app.getpostpal.com/developers/api. Die OpenAPI-Spezifikation findest du unter https://app.getpostpal.com/developers/api/openapi.json, die Postman Collection unter https://app.getpostpal.com/developers/api/postman.json.

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.