Testmodus: Zahlung und Versand werden nur simuliert. Es wird kein Geld abgebucht und kein Brief verschickt.

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
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"
  }'
TypeScript: Beispiel für einen Mahnlauf
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

201 Created
{
  "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, empfaengername, zusatz (optional), strasse, plz (5 Ziffern), ort (nur Deutschland)
betreffBetreffzeile, 3 bis 110 Zeichen
textMit Anrede, ohne Grußformel. Absätze durch Leerzeile trennen.
briefartz. B. mahnung_oder_zahlungserinnerung, reklamation, sonstiges. Steuert die Formprüfung
einschreibennein (2,49 €) oder einwurf (4,99 €)
referenzenoptional, bis 4 Einträge rechts oben, z. B. Kundennummer

5. Antworten und Fehler

201Brief erstellt
200Gleicher Idempotency-Key schon benutzt. Du bekommst den bestehenden Brief, es wird nichts doppelt verschickt
400Eingabe ungültig. fehler.felder listet jedes Feld
401 / 403Schlüssel fehlt oder ist unbekannt
422schriftform_erforderlich: Der Brief braucht eine eigenhändige Unterschrift (z. B. Kündigung einer Mietwohnung) und wird nicht verschickt.
429Tageslimit 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.

Prompt
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_…).

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.