API, MCP & Webhooks

Verbinden Sie Claude oder ChatGPT über MCP, oder integrieren Sie SchlüsselBot über die Business-API. Nachrichten lassen sich sicher versenden, ihr Status kann geprüft und eine offene Sendung zurückgezogen werden. Webhooks melden wichtige Zustandsänderungen zuverlässig an Ihre Software.

Schnellstart

Erzeugen Sie im Konto unter Schnittstelle & Webhooks einen Schlüssel. Er wird genau einmal vollständig angezeigt. SchlüsselBot speichert nur seine Prüfsumme.

curl -X POST https://schluesselbot.de/v1/messages \
  -H "Authorization: Bearer sb_live_XXXXXXXX_…" \
  -H "Idempotency-Key: auftrag-4711-versand-1" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": "empfaenger@firma.de",
    "message": "Zugang: kunde42 / T7!kq2wZ",
    "ttl_hours": 48,
    "sender_name": "Kanzlei Weber"
  }'

Für Server-zu-Server-Aufrufe genügt der Bearer-Schlüssel. Externe Browser-Anwendungen brauchen zusätzlich einen beim Schlüssel freigegebenen Origin, zum Beispiel https://portal.firma.de.

MCP für Claude und ChatGPT

SchlüsselBot stellt einen Remote-MCP-Server über Streamable HTTP bereit. Im Konto unter KI-Verbindungen, API & Webhooks erzeugen Sie dafür einen eigenen, jederzeit widerrufbaren MCP-Zugang. Die einfachste Einrichtung besteht aus genau einem Link, den Sie in Claude, ChatGPT oder einem anderen kompatiblen MCP-Client als benutzerdefinierten Server eintragen:

https://schluesselbot.de/mcp/sb_mcp_EXAMPLE_<secret>

Das Beispiel ist absichtlich kein gültiger Zugang. Verwenden Sie ausschließlich den im Konto einmalig angezeigten vollständigen Link.

Alternative mit Authorization-Header

Wenn Ihr Client eigene Header unterstützt, können Sie Server-Adresse und Geheimnis getrennt hinterlegen. Der MCP-Schlüssel gehört in jeder Anfrage in den Bearer-Header, niemals in eine Abfragezeichenkette wie ?token=….

Server:        https://schluesselbot.de/mcp
Transport:     Streamable HTTP
Authorization: Bearer sb_mcp_EXAMPLE_<secret>

MCP kann keine Postfachinhalte oder empfangenen Nachrichten lesen, keine Kontakte verändern und keine Dateien anhängen. Auch gesendete Nachrichteninhalte lassen sich später nicht über MCP abrufen. Der Verbindungslink ist ein Zugangsschlüssel: Tragen Sie ihn direkt in der Connector-Konfiguration ein, senden Sie ihn nicht als Chatnachricht und widerrufen Sie ihn im Konto sofort, falls er offengelegt wurde. SchlüsselBot speichert nur eine Prüfsumme des Geheimnisses und maskiert MCP-Zugänge in seinen Webserver-Protokollen.

Berechtigungen

Nachrichten

/v1/send bleibt als kompatibler Alias bestehen. Verwenden Sie bei automatischen Wiederholungen immer einen eindeutigen Idempotency-Key. Derselbe Schlüssel mit demselben Inhalt liefert 24 Stunden die identische Antwort; anderer Inhalt ergibt HTTP 409.

{
  "id": "8f3c…",
  "link": "https://schluesselbot.de/r/8f3c…#kQ2…",
  "expires_at": "2026-08-20T09:00:00+00:00",
  "modus": "vom Server verschlüsselt",
  "delivery": "automatic",
  "mail_sent": true,
  "has_attachment": false
}

Liefert ready, consumed, withdrawn, expired oder bei einem vorübergehend nicht prüfbaren Tresor unknown. Ein Ausfall wird nie fälschlich als Abruf gemeldet.

Sperrt den Vorgang zuerst dauerhaft und entfernt ihn anschließend aus dem Tresor. Scheitert die physische Löschung vorübergehend, bleibt die Sendung trotzdem unöffnungsbar und die Bereinigung wird automatisch wiederholt.

Kontakte

Kontaktnamen und E-Mail-Adressen liegen in der Datenbank AES-256-GCM-verschlüsselt. API-Antworten werden nicht zwischengespeichert.

Webhooks

Wählbare Ereignisse: created, consumed, withdrawn, expired und delivery_failed. SchlüsselBot speichert jedes Ereignis vor dem ersten Zustellversuch dauerhaft. Erwartet wird HTTP 2xx innerhalb von fünf Sekunden. Bei Fehlern folgen bis zu acht Versuche über ungefähr drei Tage: nach 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde und danach in größeren Abständen.

{
  "api_version": "v1",
  "event_id": "consumed:8f3c…",
  "event": "consumed",
  "zeit": "2026-08-19T10:12:33+00:00",
  "daten": {"id": "8f3c…", "mit_anhang": false}
}

X-SchluesselBot-Event: consumed
X-SchluesselBot-Event-Id: consumed:8f3c…
X-SchluesselBot-Delivery: wd_…
X-SchluesselBot-Signature: sha256=<HMAC-SHA256 des unveränderten Roh-Rumpfs>

Prüfen Sie die Signatur über den unveränderten Request-Body und behandeln Sie event_id idempotent. Das Geheimnis wird beim Anlegen einmal angezeigt und bei SchlüsselBot separat AES-256-GCM-verschlüsselt gespeichert.

// PHP
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SCHLUESSELBOT_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}

Webhook-Ziele müssen öffentlich erreichbar, HTTPS und ohne Umleitung erreichbar sein. Private, Loopback-, Link-Local-, Dokumentations- und Tailscale/CGNAT-Netze sind gesperrt; die aufgelöste öffentliche IP wird für den tatsächlichen Verbindungsaufbau fest angeheftet.

Fehler und Grenzen

• 400 ungültige Angaben · 401 Schlüssel ungültig · 403 Scope, Tarif oder Origin nicht erlaubt · 409 Dublette/Idempotenzkonflikt · 413 zu groß · 429 Versandgrenze · 502/503 vorübergehender Betriebsfehler.
• Maximal 10 aktive API-Schlüssel, 10 Browser-Origins je Schlüssel und 5 Webhooks pro Business-Konto.
• Maximal 5 gleichzeitig gültige MCP-Verbindungen pro Business-Konto; jede Verbindung läuft nach 30, 90 oder 365 Tagen automatisch ab und kann jederzeit vorher widerrufen werden.
• Die API listet oder liest keine Nachrichteninhalte. Sie sind nur für den Empfänger und nur einmal lesbar.
• Bei 429, 502 oder 503 Retry-After beachten und denselben Idempotency-Key wiederverwenden.