Versendo für Entwickler
Echte Briefe aus deiner Automation: Mahnläufe, Fristsetzungen, Mieterpost. Du schickst Daten, wir setzen das DIN-5008-PDF und übergeben an die Post. Kein PDF-Gebastel, kein Adressfenster-Ausmessen.
1. Test-Schlüssel holen
Ohne Konto, sofort. Test-Schlüssel verschicken nie echte Briefe. Alles läuft durch, nur gedruckt wird nichts.
2. Ersten Brief schicken
curl -X POST https://versendo.de/v1/briefe \
-H "Authorization: Bearer vs_test_DEIN_SCHLUESSEL" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: mahnung-2026-114-stufe-2" \
-d '{
"absender": { "name": "Studio Mustermann", "strasse": "Lindenstraße 12", "plz": "80331", "ort": "München" },
"empfaenger": { "name": "Müller GmbH", "zusatz": "Buchhaltung", "strasse": "Hauptstraße 5", "plz": "10115", "ort": "Berlin" },
"betreff": "2. Mahnung zur Rechnung 2026-114",
"text": "Sehr geehrte Damen und Herren,\n\nleider ist die Rechnung 2026-114 über 840,00 EUR weiterhin offen. Bitte überweisen Sie den Betrag bis zum 15.12.2026.",
"briefart": "mahnung_oder_zahlungserinnerung",
"einschreiben": "einwurf"
}'const antwort = await fetch("https://versendo.de/v1/briefe", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.VERSENDO_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `mahnung-${rechnung.nr}-stufe-${stufe}`, // kein Doppelversand bei Wiederholung
},
body: JSON.stringify({
absender,
empfaenger: { name: kunde.name, strasse: kunde.strasse, plz: kunde.plz, ort: kunde.ort },
betreff: `${stufe}. Mahnung zur Rechnung ${rechnung.nr}`,
text: mahntext,
briefart: "mahnung_oder_zahlungserinnerung",
einschreiben: stufe >= 2 ? "einwurf" : "nein",
}),
});
const brief = await antwort.json(); // { id, status, pdf_url, preis_cent, … }3. Antwort
{
"id": "6f1c2e0a-…",
"status": "versendet",
"modus": "test",
"seiten": 1,
"preis_cent": 499,
"einschreiben": "einwurf",
"pdf_url": "https://versendo.de/brief/6f1c2e0a-…/pdf",
"versand_referenz": "SIM-6f1c2e0a",
"hinweise": []
}Status später abfragen: GET /v1/briefe/{id} mit demselben Schlüssel. Fremde Briefe sind für deinen Schlüssel unsichtbar.
4. Felder
absender, empfaenger | name, zusatz (optional), strasse, plz (5 Ziffern), ort (nur Deutschland) |
betreff | Betreffzeile, 3 bis 110 Zeichen |
text | Mit Anrede, ohne Grußformel. Absätze durch Leerzeile trennen. |
briefart | z. B. mahnung_oder_zahlungserinnerung, reklamation, sonstiges. Steuert die Formprüfung |
einschreiben | nein (2,49 €) oder einwurf (4,99 €) |
referenzen | optional, bis 4 Einträge rechts oben, z. B. Kundennummer |
5. Antworten und Fehler
201 | Brief erstellt |
200 | Gleicher Idempotency-Key schon benutzt. Du bekommst den bestehenden Brief, es wird nichts doppelt verschickt |
400 | Eingabe ungültig. fehler.felder listet jedes Feld |
401 / 403 | Schlüssel fehlt oder ist unbekannt |
422 | schriftform_erforderlich: Der Brief braucht eine eigenhändige Unterschrift (z. B. Kündigung einer Mietwohnung) und wird nicht verschickt. |
429 | Tageslimit für Test-Briefe erreicht |
6. Für deinen KI-Agenten
Kopier diesen Prompt in Claude Code, Codex oder Cursor. Der Agent liest die Doku selbst und baut die Anbindung.
Binde Versendo in dieses Projekt ein, um echte Briefe per Post zu verschicken.
Lies zuerst https://versendo.de/llms.txt (Kurzdoku) und bei Bedarf https://versendo.de/openapi.json.
- Lies den API-Schlüssel aus der Umgebungsvariable VERSENDO_KEY (niemals in den Code schreiben).
- Nutze POST /v1/briefe mit einem Idempotency-Key pro fachlichem Vorgang (z. B. Rechnung + Mahnstufe).
- Behandle 422 "schriftform_erforderlich" (Brief braucht Originalunterschrift) und 429 (Tageslimit).
- Speichere die zurückgegebene Brief-ID und frag den Status über GET /v1/briefe/{id} ab.
- Teste ausschließlich mit Test-Schlüsseln (vs_test_…).- Kurzdoku für Agenten: /llms.txt
- OpenAPI-Beschreibung: /openapi.json
- MCP-Server für Chats:
https://versendo.de/api/mcp
7. Testmodus und Live
Test-Schlüssel: kostenlos, bis zu 200 Briefe pro Tag, nichts wird gedruckt. Live-Schlüssel bekommst du mit einem Guthaben-Konto: Jeder Brief wird vom Guthaben abgebucht und wirklich verschickt. Reicht das Guthaben nicht, antwortet die API mit 402 guthaben_reicht_nicht; nach dem Aufladen holt derselbe Idempotency-Key den Versand nach, ohne doppelt zu buchen.