MCP-Dokumentation
Verbinde deinen Agenten mit QMailing
QMailing liefert einen gehosteten Model Context Protocol-Server, sodass Claude, Cursor, Continue und jeder andere MCP-kompatible Agent dein Postfach lesen, Mail versenden, Postfächer verwalten und auf Ereignisse reagieren kann — über zwölf Scope-Tools. Kein npm install, kein lokaler Prozess — nur ein Bearer-Token und eine Server-URL.
https://qmailing.com/mcpWas ist QMailing MCP?
https://qmailing.com/mcp ist ein von QMailing gehosteter Streamable-HTTP-MCP-Server. Jeder MCP-kompatible Client (Claude Desktop, Claude.ai-Connectors, Cursor, Continue, eigene Agenten) kann sich verbinden, mit einem OAuth-Bearer-Token authentifizieren und zwölf Tools aufrufen, die 1:1 auf die REST-Oberfläche von QMailing gemappt sind.
Für wen: Indie-Maker, Freelancer und Agenturen, die mehrere Marken-Domains jonglieren und wollen, dass ihr KI-Assistent eingehende Mail triagiert, Antworten entwirft, Webhooks registriert und Postfächer verwaltet — ohne eine einzige Zeile Glue-Code.
Was es nicht ist: kein transaktionales Sende-API wie SendGrid. QMailing ist ein vollwertiges Inbox-SaaS — jedes Tool arbeitet auf echten Postfächern, die dir gehören. Der MCP-Server ist die agentenseitige Oberfläche; die gleichen Operationen funktionieren per REST unter /api/v1/pub/* mit demselben Token.
Mit Claude verbinden
Drei Schritte. Die Token-Ausgabe passiert im QMailing-Dashboard, die Verbindung in den Einstellungen von Claude.
- 1. Auf PLUS upgraden — Read-only-Basistools (
list_mailboxes,get_mailbox) sind auf FREE mit 25 Aufrufen pro Tag verfügbar; alles andere setzt PLUS oder höher voraus. - 2. OAuth-Token ausstellen — gehe zu Einstellungen → Entwickler → klicke auf Connect to Claude. Wähle die Scopes, die du dem Agenten geben willst (der Assistent schlägt für jeden Anwendungsfall einen sinnvollen Default vor).
- 3a. Claude Desktop / Claude.ai: öffne Einstellungen → Connectors → Add custom connector. Füge die Server-URL unten und das Token aus Schritt 2 ein.
- 3b. Cursor / Continue / eigener Client: trage einen HTTP-MCP-Server-Eintrag mit der URL unten und dem Standard-Header
Authorization: Bearer …ein. Streamable HTTP transport (nicht stdio, nicht SSE).
- Server-URL
- https://qmailing.com/mcp
- Transport
- Streamable HTTP (MCP-Protokoll-Revision 2025-06-18)
Verbindung verifizieren
Frage den Agenten: «Show me my mailboxes». Er sollte qmailing_list_mailboxes aufrufen und die Liste zurückgeben. Wenn du 401 siehst — Token falsch oder widerrufen. 402 — Tool über deinem Tarif. 403 — Token trägt den geforderten Scope nicht. Vollständige Matrix unter Fehlerbehebung.
OAuth-Scopes
Tokens werden bei Ausstellung mit Scopes versehen. Jedes Tool verlangt einen oder mehrere Scopes; der Agentenaufruf wird mit 403 abgelehnt, bevor Code ausgeführt wird, falls ein Scope fehlt. Stelle ein Read-only-Token aus, wenn du nur triagieren, nicht senden willst.
| Scope | Erlaubt | Tools |
|---|---|---|
| mailbox:read | Postfächer auflisten und einsehen | list_mailboxes, get_mailbox |
| mailbox:write | Neue Postfächer auf eigenen Domains anlegen | create_mailbox |
| domain:read | Domains auflisten und DNS-Checkliste abrufen | list_domains, get_dns_records |
| domain:write | Reserviert für zukünftige Domain-Management-Endpunkte | — |
| email:read | E-Mails lesen, Anhänge herunterladen | list_emails, get_email, get_attachment |
| email:send | Ausgehende E-Mail über eigene Postfächer senden | send_email |
| webhook:manage | Webhook-Endpunkte registrieren, auflisten und widerrufen | list_webhooks, register_webhook, delete_webhook |
Verfügbare Tools
Zwölf Tools, ein Server. Jedes Tool trägt ein JSON-Schema für seine Argumente und einen Annotations-Block (Titel, Read-only / destructive Hints), den der Agent nutzt, um zu entscheiden, ob vor dem Aufruf eine Bestätigung verlangt wird. Unten: Beispiel-Prompts gruppiert nach Nutzerintent.
Postfächer
List Mailboxes
mailbox:readqmailing_list_mailboxes
Liefert jedes Postfach, das dir gehört, mit Adressen, Status, Nachrichtenzählern und Speichernutzung.
Beispiel-Prompt: «What mailboxes do I have?»
Get Mailbox
mailbox:readqmailing_get_mailbox
Einzelnes Postfach per UUID — Weiterleitungseinstellungen, Zähler, Gruppenmitgliedschaft.
Beispiel-Prompt: «Show me the settings for sales@my-startup.com.»
Create Mailbox
mailbox:writeqmailing_create_mailbox
Neues Postfach auf einer eigenen Domain anlegen. Local-Part + optionaler Display-Name und Weiterleitung.
Beispiel-Prompt: «Create a mailbox sales@my-startup.com that forwards to me.»
Domains und DNS
List Domains
domain:readqmailing_list_domains
Deine Custom-Domain-Bindungen mit MX / SPF / DKIM / DMARC Verifizierungs- und Ownership-Status.
Beispiel-Prompt: «Which of my domains haven't verified DKIM yet?»
Get DNS Records
domain:readqmailing_get_dns_records
DNS-Checkliste für eine Custom-Domain — Host + Wert + Typ + aktueller Verifizierungsstatus pro Eintrag.
Beispiel-Prompt: «Show me the DNS records I still need to add for acme.dev.»
List Emails
email:readqmailing_list_emails
Paginierte Auflistung innerhalb eines Postfachs + Ordners (INBOX, SENT, DRAFTS, TRASH, STARRED, SPAM).
Beispiel-Prompt: «Show me unread emails from support@acme.dev.»
Get Email
email:readqmailing_get_email
Einzelne E-Mail per UUID mit vollständigen Headern, geparsten Inhalten (HTML + Text) und Anhang-Metadaten.
Beispiel-Prompt: «What did Alice say in her last reply?»
Get Attachment
email:readqmailing_get_attachment
Einzelnen Anhang per email-id + Index abrufen. Liefert filename + content-type + size + Base64-Bytes (5 MB inline cap).
Beispiel-Prompt: «Download the invoice PDF from Alice's last email.»
Send Email
email:sendqmailing_send_email
Ausgehende E-Mail aus einem deiner Postfächer senden. Plain-Text + HTML, to/cc/bcc, Reply-Threading.
Beispiel-Prompt: «Send a reply to john@example.com confirming the meeting at 3pm.»
Webhooks
List Webhooks
webhook:manageqmailing_list_webhooks
Deine registrierten Webhook-Endpunkte, aktive und widerrufene, neueste zuerst.
Beispiel-Prompt: «Show me my webhook endpoints.»
Register Webhook
webhook:manageqmailing_register_webhook
HTTP-Endpunkt zum Empfang von Event-Notifications registrieren. Das Signing-Secret wird EINMAL zurückgegeben.
Beispiel-Prompt: «Register a webhook for email.received events at https://my-server.com/qmailing.»
Delete Webhook
webhook:manageqmailing_delete_webhook
Webhook-Endpunkt widerrufen. Idempotent — bereits widerrufene Endpunkte liefern Erfolg.
Beispiel-Prompt: «Revoke the webhook from yesterday.»
Tarife und Limits
Zwölf Tools, vier Stufen. FREE genügt, um die Integration zu evaluieren; PLUS schaltet alle Read + Write Operationen außer Webhooks frei; PRO+ schaltet Webhooks für Inbound-Automatisierung frei.
| Tool | FREE | PLUS | PRO | PRO_MAX |
|---|---|---|---|---|
| list_mailboxes | ✓ | ✓ | ✓ | ✓ |
| get_mailbox | ✓ | ✓ | ✓ | ✓ |
| create_mailbox | — | ✓ | ✓ | ✓ |
| list_domains | — | ✓ | ✓ | ✓ |
| get_dns_records | — | ✓ | ✓ | ✓ |
| list_emails | — | ✓ | ✓ | ✓ |
| get_email | — | ✓ | ✓ | ✓ |
| get_attachment | — | ✓ | ✓ | ✓ |
| send_email | — | ✓ | ✓ | ✓ |
| list_webhooks | — | — | ✓ | ✓ |
| register_webhook | — | — | ✓ | ✓ |
| delete_webhook | — | — | ✓ | ✓ |
429 Too Many Requests mit Retry-After in Sekunden. PLUS und höher heben den Tageskap auf; die 300-Anfragen-pro-Minute-Drossel pro Token auf Transport-Ebene bleibt.Fehlerbehebung
Jede Fehler-Response folgt RFC-7807 problem+json — eine stabile type-URL, status, title, detail plus ein code-Feld für Branching. Der Agent zeigt das detail dem Nutzer.
| Status | Wann du es siehst | Lösung |
|---|---|---|
| 401 | Token fehlt, ist fehlerhaft, abgelaufen oder widerrufen. | Neu ausstellen unter Einstellungen → Entwickler und den Connector-Eintrag aktualisieren. |
| 402 | Tool verlangt einen höheren Tarif als der aktive. | Upgraden — die Antwort enthält upgradeUrl und den requiredPlan-Namen. |
| 403 | Token ist authentifiziert, hat aber den geforderten Scope nicht. | Neues Token mit fehlendem Scope ausstellen oder ein vorhandenes verwenden, das ihn schon trägt. |
| 429 | FREE-Tier überschritt 25 Anfragen/Tag oder ein einzelnes Token überschritt 300 Anfragen/Minute. | Warte die Retry-After-Sekunden ab. Auf PLUS upgraden hebt den Tageskap auf. |
Datenschutz und Sicherheit
OAuth-Tokens sind an ein einzelnes Konto und einen einzelnen Client gebunden (Claude, Cursor oder ein eigener). Tokens werden serverseitig als bcrypt-Hashes gespeichert — der Klartext-Wert qm_live_… wird genau einmal bei der Ausgabe gezeigt. Jederzeit im Dashboard widerrufbar; Widerruf greift bei der nächsten Anfrage, kein Cache.
Jeder Tool-Aufruf durchläuft drei unabhängige Gates, bevor Geschäftslogik startet: (a) der Tarif des Tokens muss das angeforderte Tool zulassen, (b) der Scope-Satz muss die deklarierten Anforderungen des Tools abdecken, (c) die Ressource, die das Tool anfasst, muss dem authentifizierten Nutzer gehören. Eines dieser Gates fehlgeschlagen → RFC-7807-Fehler vor Ausführung von call().
Siehe Datenschutzerklärung für Sub-Processors, OAuth-Sign-in-Details und Aufbewahrung. Der MCP-Server selbst loggt Anfrage-Metadaten (Zeitstempel, Tool-Name, Status-Code) für 30 Tage — Anfrage-Bodies und Tool-Ergebnisse werden nie protokolliert.