Postkarten API: echte Karten aus deinem System

Zwei Wege, eine Karte zu schicken

Wir haben uns für zwei klare API-Pfade entschieden, statt fünf halbgare anzubieten. Welcher zu dir passt, hängt davon ab, wer im Team Layout und Text pflegt.

Lieber per Workflow-Tool als im eigenen Repo?

Funktioniert genauso. Unsere REST-API ist eine ganz normale HTTPS-Schnittstelle – n8n, Zapier oder Make rufen sie über deren generische HTTP-Schritte auf. Ein Make-Szenario, das täglich Bestellungen ausliest und pro Treffer einen Request gegen api.echtpost.de/v2/cards/from_template schickt, ist in einer halben Stunde gebaut. Code im klassischen Sinn schreibst du dafür keinen, ein bisschen JSON und ein paar Variablen aber schon.

Du arbeitest mit Claude, Cursor oder ChatGPT? Dann kannst du unseren MCP-Server einbinden und Postkarten direkt aus dem Chat verschicken. Mehr dazu auf Postkarten MCP – die Seite kommt mit eigenem Brief, hier nehmen wir's nur als Teaser.

Häufige Fragen

Wie schnell komme ich an einen API-Key?

Sofort. Account anlegen dauert eine Minute, der Key liegt direkt im Konto-Bereich. Kein Freischaltungs-Termin, kein Sales-Anruf vorab. Wer MCP nutzen will, kann den Server an derselben Stelle aktivieren.

Wie viele Zeichen passen auf eine Postkarte?

Eine feste Zahl gibt es nicht – wir zählen keine Zeichen, wir messen Zeilen. Für den Text ist auf der Rückseite ein Feld von 72 × 91 mm reserviert. Was da reinpasst, hängt an drei Dingen: Schriftart, Schriftgröße und deiner Formatierung. Vor allem an den Absätzen: Eine Leerzeile kostet zwei Zeilen, und jeder Absatz endet mit einer angebrochenen. Derselbe Text mit vier Absätzen braucht deutlich mehr Platz als am Stück – und ohne Absätze willst du keine Postkarte verschicken, das liest niemand gern.

Zur Orientierung, gemessen mit deutschem Fließtext:

„Am Stück“ ist ein Block ohne eigene Absätze, nur mit automatischem Umbruch. Die letzte Spalte ist die realistische: Anrede, Leerzeile, zwei Absätze, Leerzeile, Grußformel. Wenn du einem LLM ein Zeichen-Budget vorgeben willst, nimm diese Spalte – bei den Standardeinstellungen also rund 240 Zeichen.

Ein Detail, das leicht untergeht: {anrede} wird erst beim Druck durch die echte Anrede des Empfängers ersetzt. „Hallo Max“ sind neun Zeichen, „Sehr geehrte Frau Müller-Lüdenscheidt“ 37. Bei einem Mailing an viele Empfänger entscheidet die längste Anrede im Request darüber, ob der Text passt.

Wie prüfe ich vorab, ob mein Text passt?

Mit POST /v2/cards/preview_fit. Du schickst Text und Schrifteinstellungen hin und bekommst zurück, ob es passt (fits), wie viele Zeilen belegt sind (lines_used von max_lines) und, falls nicht, ab welcher Zeile es überläuft plus eine suggested_font_size, mit der es passen würde. Beginnt dein Text mit {anrede}, gib zusätzlich ein sample_greeting mit – sonst rechnen wir mit einer langen Beispielanrede.

Kommt der Text aus einem LLM, ist das der Weg: generieren, gegen preview_fit halten, bei fits: false einmal kürzen lassen. Das Modell braucht dafür kein Zeichen-Gefühl, es braucht nur die Antwort des Endpunkts.

Falls du die Prüfung überspringst, prüft POST /v2/cards selbst: Wir messen den Text gegen jeden Empfänger im Request – mit dessen echter Anrede – und antworten mit 422 und dem Slug text-does-not-fit, wenn er bei einem davon nicht passt. Dazu die betroffene contact_id und dieselbe suggested_font_size. Eine abgeschnittene Karte kann dir auf diesem Weg also nicht passieren.

Bei cards/from_template messen wir nicht nach: Dort hast du Motiv, Text und Umbrüche im Editor schon gesehen. Genau deshalb ist die Vorlage der ruhigere Weg, wenn der Text gleich bleibt und nur die Anrede wechselt. Wenn du darin {anrede} nutzt, lass im Editor Platz für eine lange Anrede.

Gibt es Limits für die anderen Textfelder?

Zwei feste. Das content_ps – das P.S. – wird als einzelne Fußzeile gedruckt und ist deshalb auf 40 Zeichen begrenzt; darüber kommt ein 422. Legst du einen QR-Code auf die Karte, hat der Begleittext (qr_code_message) maximal 70 Zeichen. Emojis nehmen wir in keinem Textfeld an – die Kartenschriften enthalten sie nicht, im Druck bliebe eine Lücke.

Brauche ich Programmierkenntnisse, um EchtPost zu nutzen?

Nicht zwingend. Über generische Workflow-Tools wie n8n, Zapier oder Make kannst du unsere API in ein paar Klicks anbinden. Wer mit Claude oder ChatGPT arbeitet, hängt unseren MCP-Server dran. Wer es lieber selbst baut, findet eine vollständige REST-API.

Funktioniert das mit meinem CRM (HubSpot, Salesforce, Pipedrive …)?

Ja – entweder über die genannten Workflow-Tools, die alle gängigen CRMs anbinden, oder direkt über die API. Falls ein Datenfeld bei dir anders heißt als bei uns: melde dich, wir gehen das Feld-Mapping gemeinsam durch.

Was ist MCP – und brauche ich das?

MCP (Model Context Protocol) ist ein offener Standard, mit dem AI-Tools wie Claude oder ChatGPT auf externe Systeme zugreifen. Unser MCP-Server macht die EchtPost-API direkt im Chat nutzbar: „Schick Anna eine Geburtstagskarte“ – und es passiert. Wer keine KI-Agenten einsetzt, braucht MCP nicht.

Auf welcher Sprache ist die Doku?

Die API-Doku ist Englisch. Dieses Marketing, der Support und der Vertrag sind Deutsch. Wenn dir das Englisch im Weg steht, melde dich – wir helfen weiter.

Was kostet eine Karte?

Stückpreis je nach Volumen und Format, ab kleinen einstelligen Euro-Beträgen. Keine Setup-Gebühr, keine Mindestabnahme. Die genaue Staffel findest du auf der Preisseite.

Wie schnell ist eine Karte beim Empfänger?

Werktäglich produzieren wir die Karten, am Folgetag übergeben wir sie an die Post. Innerhalb Deutschlands rechnest du danach mit den üblichen 1–3 Werktagen – mehr versprechen können wir nicht, weil ab Versand die Post übernimmt.

Gibt es einen Sandbox-Modus zum Testen?

Ja. Beim Anlegen eines API-Schlüssels wählst du zwischen Live und Sandbox; der Sandbox-Schlüssel trägt das Präfix ep_test_. Alles, was du damit erzeugst – Karten, Kontakte, Gruppen – liegt getrennt von deinen Live-Daten: nichts wird abgerechnet, nichts geht in den Druck. Ein Live-Schlüssel sieht die Testdaten nicht und umgekehrt. Wenn du fertig bist, löschst du die Sandbox-Daten des Kontos mit einem Klick in den Einstellungen.

Der Modus steckt fest im Präfix und lässt sich später nicht umstellen – für den Produktivbetrieb legst du also einen zweiten, echten Schlüssel an. Wenn du zusätzlich das Verhalten bei leerem Guthaben testen willst, kannst du es in der Sandbox gezielt auslösen; wie das geht, steht in der API-Doku.