API für handgeschriebene Briefe
Ein Brief mit echtem Stift.
Ihr CRM, Ihr Shop, Ihre eigene Software oder Ihr KI-Assistent legt Aufträge direkt bei uns an. Zum Beispiel ein Dankesbrief, sobald im CRM ein Abschluss steht. Sie prüfen den Proof im Kundenkonto, danach schreiben wir.
Für eingerichtete Kundenkonten · Testmodus inklusive · Auch mit Claude und ChatGPT
Vier Schritte bis zum ersten Brief.
Konto einrichten
Wir stimmen mit Ihnen Absender, Handschrift und Papier ab und richten Ihr Kundenkonto ein.
Schlüssel anlegen
Im Kundenkonto unter „API“. Einen Schlüssel je System, jeder lässt sich einzeln sperren.
Auftrag schicken
Ihr System sendet Empfänger und Text an /v1/orders. Mit dry_run prüfen Sie vorher, ohne etwas anzulegen.
Freigeben und verfolgen
Wir bereiten den Proof vor, Sie geben ihn im Konto frei. Den Stand jedes Stücks fragt Ihr System ab.
Ihr System legt Aufträge an. Geschrieben wird nach Ihrem Okay.
Ein Auftrag per API ist ein Entwurf. Wir bereiten den Proof vor und melden uns, wenn etwas unklar ist. Erst wenn Sie den Proof im Kundenkonto freigegeben haben, schreiben wir.
Testmodus
Mit "dry_run": true prüfen wir Ihren Auftrag vollständig und legen nichts an. So bauen Sie die Anbindung, ohne dass ein Brief entsteht.
Nichts doppelt
Schicken Sie einen Idempotency-Key mit, zum Beispiel die ID aus Ihrem CRM. Eine Wiederholung nach einem Zeitüberlauf legt dann keinen zweiten Auftrag an.
Ein Schlüssel je System
Schlüssel legen Sie im Kundenkonto an und sperren sie dort mit einem Klick. Bei uns liegt nur eine Prüfsumme, nie der Schlüssel selbst.
Daten nur so lange wie nötig
Anschrift und Text jedes Stücks löschen wir 30 Tage nach der Einlieferung, wie in unserer Datenschutzerklärung beschrieben.
Sagen Sie Ihrem Assistenten, wem Sie schreiben wollen.
Verbinden Sie Claude oder ChatGPT einmal mit Handschriftpost. Danach reicht ein Satz. Der Assistent prüft Anschriften und Text, zeigt Ihnen einen Beispielbrief und legt den Auftrag erst nach Ihrem Ja an. Geschrieben wird, wenn Sie den Proof freigegeben haben.
Schreib Frau Probe von der Muster GmbH einen Dankesbrief für den Auftrag.
Mach aus dieser Liste 40 Weihnachtsbriefe, jeder mit einem Satz zum gemeinsamen Projekt.
Welche Briefaufträge warten auf meine Freigabe?
Claude
Unter Connectors „Add custom connector“ wählen. Name: Handschriftpost. Als URL Ihren persönlichen Link aus dem Kundenkonto.
https://konto.handschriftpost.de/mcp/hpk_IHR_SCHLUESSELChatGPT
In den Einstellungen den Entwicklermodus einschalten und eine App anlegen. Ihr persönlicher Link als URL, Authentifizierung „Keine“. In Plus, Pro, Business, Enterprise und Edu.
https://konto.handschriftpost.de/mcp/hpk_IHR_SCHLUESSELClaude Code
Im Terminal, mit Ihrem Schlüssel statt des Platzhalters:
claude mcp add --transport http handschriftpost \
https://konto.handschriftpost.de/mcp \
--header "Authorization: Bearer hpk_IHR_SCHLUESSEL"Cursor und andere
Für jeden MCP-Client, der eine Adresse und eine Kopfzeile annimmt:
{
"mcpServers": {
"handschriftpost": {
"url": "https://konto.handschriftpost.de/mcp",
"headers": { "Authorization": "Bearer hpk_IHR_SCHLUESSEL" }
}
}
}Ihren persönlichen Link finden Sie im Kundenkonto unter „API“, sobald wir Ihr Konto eingerichtet haben. Noch kein Konto? Zugang anfragen
Alles für Ihre Anbindung.
Die vollständige Beschreibung im Format OpenAPI 3.1 liegt unter konto.handschriftpost.de/v1/openapi.json. Viele Werkzeuge lesen sie direkt ein.
Adresse und Anmeldung
Alle Aufrufe gehen an https://konto.handschriftpost.de/v1. Ihren Schlüssel aus dem Kundenkonto senden Sie als Kopfzeile Authorization: Bearer hpk_…. Rufen Sie die API nur von Ihrem Server aus auf, nie aus einer Webseite oder App, die Ihre Kunden laden.
Endpunkte
| Aufruf | Wofür |
|---|---|
POST /v1/orders | Auftrag anlegen, mit dry_run nur prüfen |
GET /v1/orders | Alle Aufträge, neueste zuerst |
GET /v1/orders/{id} | Ein Auftrag mit allen Stücken und ihrem Stand |
GET /v1/openapi.json | Die Beschreibung der API, ohne Schlüssel abrufbar |
Beispiel: Auftrag anlegen
Dieser Aufruf prüft einen Auftrag mit einem Stück. Ohne "dry_run": true legt er ihn an.
curl https://konto.handschriftpost.de/v1/orders \
-H "Authorization: Bearer hpk_IHR_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"title": "Dankesbrief nach Abschluss",
"reference": "CRM-4711",
"dry_run": true,
"letters": [{
"recipient": {
"company": "Muster GmbH", "salutation": "Frau",
"first_name": "Tina", "last_name": "Probe",
"street": "Allee 5", "zip": "10115", "city": "Berlin"
},
"content": {
"greeting": "Liebe Frau Probe,",
"paragraphs": ["vielen Dank für Ihr Vertrauen."],
"closing": "Herzliche Grüße",
"signer_name": "Max Muster"
}
}]
}'Die Antwort enthält den Auftrag mit allen Stücken (hier gekürzt). Unter url öffnen Sie ihn im Kundenkonto.
HTTP/1.1 201 Created
{
"order": {
"id": 128,
"title": "Dankesbrief nach Abschluss",
"reference": "CRM-4711",
"status": "received",
"status_text": "Eingegangen, wir bereiten den Proof vor",
"letters_count": 1,
"created_at": "2026-09-22T09:14:03Z",
"url": "https://konto.handschriftpost.de/konto/auftrag/128",
"letters": [{
"id": 5310,
"number": 1,
"status": "received",
"recipient": { "company": "Muster GmbH", "last_name": "Probe", "city": "Berlin" },
"written_at": null,
"posted_at": null
}]
}
}Felder eines Auftrags
| Feld | Pflicht | Bedeutung |
|---|---|---|
title | ja | Name des Auftrags, z. B. „Dankesbriefe Oktober“ |
letters | ja | 1 bis 500 Stücke, je Stück recipient und optional content |
content | Gemeinsamer Text für alle Stücke ohne eigenen content | |
reference | Ihre Referenz, z. B. Projekt oder Endkunde | |
dry_run | true: nur prüfen, nichts anlegen | |
idempotency_key | Wie die Kopfzeile Idempotency-Key: dieselbe Nummer legt nie zwei Aufträge an. Mit anderem Inhalt antwortet die API mit 409. |
Empfänger: recipient
| Feld | Pflicht | Bedeutung |
|---|---|---|
last_name | ja | Nachname |
street | ja | Straße und Hausnummer |
zip | ja | Postleitzahl |
city | ja | Ort |
first_name | Vorname | |
salutation | „Herr“ oder „Frau“ | |
title | Titel, z. B. „Dr.“ | |
company | Firma | |
country | Ländercode aus zwei Buchstaben, z. B. AT, Standard DE |
Text: content
| Feld | Pflicht | Bedeutung |
|---|---|---|
greeting | ja | Anrede im Brief, z. B. „Liebe Frau Probe,“ |
paragraphs | ja | Liste der Absätze, höchstens 12. Auf das Blatt passen 500 Zeichen je Brief (Betreff, Anrede, Absätze, Gruß, Name und Funktion zusammen) |
closing | ja | Grußformel, z. B. „Herzliche Grüße“ |
signer_name | ja | Unterzeichner |
signer_role | Funktion unter dem Namen | |
subject | Betreffzeile |
Unbekannte Felder und zu lange Werte lehnt die API mit einer Meldung ab, statt sie still abzuschneiden. So geht ein Tippfehler wie firstname nicht verloren.
Stand eines Auftrags
| status | Bedeutung |
|---|---|
received | Eingegangen, wir bereiten den Proof vor |
proof_ready | Proof wartet auf Ihre Freigabe im Kundenkonto |
in_production | In Fertigung |
on_hold | Rückfrage zu einem Stück, wir melden uns bei Ihnen |
partly_posted | Ein Teil ist eingeliefert |
posted | Alle Stücke sind bei der Deutschen Post |
cancelled | Storniert |
Jedes Stück hat zusätzlich einen eigenen status (received, proof_ready, in_production, packed, posted, returned, on_hold oder cancelled) und die Zeitpunkte written_at, packed_at und posted_at. Zeiten stehen in UTC. 30 Tage nach der Einlieferung ist recipient leer, weil wir die Anschrift dann löschen.
Fehler
Jeder Fehler hat die Form {"error": {"code": "…", "message": "…"}}. Die Meldung ist auf Deutsch und nennt bei Eingabefehlern das Stück, z. B. „Stück 2: Nachname, Straße, PLZ und Ort sind Pflicht.“
| HTTP | code | Wann |
|---|---|---|
| 400 | invalid_request | Ein Feld fehlt oder ist falsch |
| 400 | invalid_json | Der Körper ist kein gültiges JSON |
| 401 | unauthorized | Schlüssel fehlt, ist falsch oder gesperrt |
| 403 | not_ready | Das Kundenkonto ist noch nicht für Aufträge eingerichtet |
| 404 | not_found | Diesen Auftrag gibt es nicht |
| 409 | idempotency_conflict | Der Idempotency-Key gehört schon zu einem Auftrag mit anderem Inhalt |
| 413 | too_large | Der Auftrag ist zu groß (z. B. ein langer gemeinsamer Text in sehr vielen Stücken) |
| 429 | rate_limited | Zu viele Anfragen; die Kopfzeile Retry-After sagt, wie lange Sie warten |
| 503 | unavailable | Kurz nicht erreichbar, bitte später wiederholen |
KI-Assistenten (MCP)
Claude, ChatGPT, Cursor und andere Assistenten sprechen mit uns über das Model Context Protocol. Der Server liegt unter https://konto.handschriftpost.de/mcp und nutzt dieselben Schlüssel, Regeln und Grenzen wie die API. Den Schlüssel senden Sie als Kopfzeile Authorization: Bearer hpk_…. Wo ein Client keine Kopfzeile setzen kann, etwa bei Connectoren in Claude und ChatGPT, hängen Sie ihn an die Adresse an: https://konto.handschriftpost.de/mcp/hpk_…. Diesen Link behandeln Sie wie ein Passwort.
| Werkzeug | Was es tut |
|---|---|
letter_guide | Erklärt dem Assistenten Ablauf, Felder und Grenzen |
check_letters | Prüft Empfänger und Texte, legt nichts an |
create_letter_order | Legt den Auftrag als Entwurf an. Derselbe Inhalt ergibt nie zwei Aufträge. |
list_orders | Ihre Aufträge, neueste zuerst |
get_order | Ein Auftrag mit dem Stand jedes Briefs |
Der Assistent fragt Sie, bevor er einen Auftrag anlegt. Auch dann ist es ein Entwurf: Geschrieben wird erst nach Ihrer Freigabe des Proofs im Kundenkonto.
Grenzen
- Höchstens 500 Stücke je Auftrag und 500 Zeichen je Brief (Betreff, Anrede, Absätze, Gruß, Name und Funktion zusammen). Längere Briefe lehnt die Prüfung beim Anlegen ab. Größere Serien teilen Sie auf mehrere Aufträge auf.
- Per API beauftragen Sie Briefe, keine Karten oder Postkarten.
- 120 Anfragen je Minute und Schlüssel.
- 30 neue Aufträge je Stunde und Kundenkonto. Brauchen Sie mehr, sprechen Sie uns an.
Ihre Fragen. Unsere Antworten.
Wird ein Auftrag per API sofort geschrieben?
Was kostet ein Auftrag per API?
Funktioniert das mit Claude oder ChatGPT?
Welche Systeme lassen sich anbinden?
Gibt es Webhooks?
GET /v1/orders/{id} ab, zum Beispiel einmal am Tag. Brauchen Sie eine Benachrichtigung, sagen Sie uns Bescheid.Geht es auch ohne API?
Wie komme ich an einen Schlüssel?
Was möchten Sie mit Ihrer Post erreichen? Janik Deimann bespricht mit Ihnen die passende Umsetzung und die Kosten. Wenn Sie das Papier vorher kennenlernen möchten, bestellen Sie ein kostenloses Muster-Kit.