API, Serienbrief & E-Mail-Versand

Verschicke Briefe direkt aus deiner Software – per REST-API, als Serienbrief oder einfach per E-Mail. Dieselben Funktionen nutzt auch der Claude-Connector.

Authentifizierung

Erstelle unter Konto → API-Schlüssel einen Schlüssel und sende ihn als Bearer-Token mit. Jede Anfrage belastet nur das Guthaben dieses Kontos.

curl -H "Authorization: Bearer mbx_…" https://mcpbrief.de/api/v1/balance

OpenAPI-Beschreibung: https://mcpbrief.de/openapi.json

Endpunkte

GET	/balance	Guthaben, Preise, Absender, Tageslimit
POST	/letter/price	Anschrift prüfen, Brief setzen, Seiten und Preis + PDF-Vorschau (sendet nichts)
POST	/letter/send	Brief verschicken (Text, PDF, DOCX, Bild; Anlagen, Duplex, Kostenstelle)
GET	/letter/{id}	Status und Sendungsnummer
POST	/letter/{id}/cancel	Stornieren, solange nicht gedruckt (Erstattung)
POST	/letter/{id}/resend	Erneut senden
GET	/letters?limit=&status=&since=&cost_center=&batch_id=	Liste deiner Briefe, filterbar
POST	/letters/batch/price	Serienbrief prüfen: alle Anschriften, Platzhalter, Gesamtpreis
POST	/letters/batch/send	Serienbrief senden (max. 200 Empfänger)

Beispiel: Einschreiben mit Anlage

curl -X POST https://mcpbrief.de/api/v1/letter/send \
  -H "Authorization: Bearer mbx_…" -H "Content-Type: application/json" \
  -d '{
  "recipient": {"name": "Muster GmbH", "street": "Ringstraße 5",
                "zip": "1010", "city": "Wien", "country": "AT"},
  "subject": "Rechnung 2026-17",
  "content": "Sehr geehrte Damen und Herren,\n\nanbei …",
  "attachments": [{"file_base64": "JVBERi0…", "file_name": "rechnung.pdf"}],
  "delivery": "registered", "duplex": true, "cost_center": "VERTRIEB",
  "idempotency_key": "7d1c2f0e-…"
}'

Beispiel: Serienbrief

curl -X POST https://mcpbrief.de/api/v1/letters/batch/send \
  -H "Authorization: Bearer mbx_…" -H "Content-Type: application/json" \
  -d '{
  "recipients": [
    {"name": "Muster GmbH", "street": "Ringstraße 5", "zip": "1010",
     "city": "Wien", "country": "AT", "anrede": "Sehr geehrte Frau Huber"},
    {"name": "Beispiel AG", "street": "Hauptstraße 1", "zip": "10115",
     "city": "Berlin", "country": "DE", "anrede": "Sehr geehrte Damen und Herren"}
  ],
  "subject": "Preisanpassung 2027",
  "content": "{{anrede}},\n\nab 1. Jänner gelten neue Preise …",
  "delivery": "standard", "idempotency_key": "batch-2027-01"
}'

Briefe per E-Mail

Ohne Programmierung: Jedes Konto hat eine persönliche Auftragsadresse. PDFs, die du von deiner Konto-E-Mail an diese Adresse schickst, gehen als Brief raus.

Jedes PDF im Anhang = ein Brief, Anschrift im Sichtfenster (DIN 5008)
Betreff steuert Optionen: Einschreiben, Priority, Farbe, Duplex, KST: …, Land: …
„Anlage“ im Betreff: alle Dateien werden zu einem Brief zusammengefügt
„Test“ im Betreff: nur prüfen und Preis per E-Mail – nichts wird gesendet

Statuswerte

Den aktuellen Stand liefern der Status-Endpunkt, die Liste und die E-Mail-Benachrichtigung.

`pending`	in Warteschlange
`processing`	in Druck & Kuvertierung
`mailed`	an die Post übergeben
`failed`	nicht versendet
`cancelled`	storniert
`undeliverable`	unzustellbar
`rejected`	abgelehnt