Dokumentacja MCP
Podłącz swojego agenta do QMailing
QMailing dostarcza hostowany serwer Model Context Protocol — Claude, Cursor, Continue i dowolny inny agent zgodny z MCP może czytać twoją skrzynkę, wysyłać maile, zarządzać skrzynkami i reagować na zdarzenia przez dwanaście scope-owanych narzędzi. Bez npm install, bez procesu lokalnego — tylko token Bearer i jeden URL serwera.
https://qmailing.com/mcpCzym jest QMailing MCP?
https://qmailing.com/mcp to serwer MCP streamable-HTTP hostowany przez QMailing. Dowolny klient zgodny z MCP (Claude Desktop, konektory Claude.ai, Cursor, Continue, agenci na zamówienie) może się podłączyć, uwierzytelnić tokenem Bearer OAuth i wywołać dwanaście narzędzi mapowanych 1:1 na powierzchnię REST QMailing.
Dla kogo: indie deweloperzy, freelancerzy i agencje, którzy żonglują kilkoma domenami marek i chcą, by ich asystent AI sortował przychodzącą pocztę, redagował odpowiedzi, rejestrował webhooki i zarządzał skrzynkami — bez ani jednej linii glue code.
Czym to nie jest: nie jest API transakcyjnym do wysyłki jak SendGrid. QMailing to pełnoprawny inbox-SaaS — każde narzędzie operuje na realnych skrzynkach, które posiadasz. Serwer MCP to powierzchnia dla agentów; te same operacje działają przez REST na /api/v1/pub/* z tym samym tokenem.
Połączenie z Claude
Trzy kroki. Wydanie tokena odbywa się w dashboardzie QMailing, podłączenie w ustawieniach Claude.
- 1. Przejdź na PLUS — podstawowe narzędzia read-only (
list_mailboxes,get_mailbox) dostępne na FREE z pułapem 25 zapytań na dobę; reszta wymaga PLUS lub wyżej. - 2. Wystaw token OAuth — wejdź do Ustawienia → Programiści → kliknij Connect to Claude. Wybierz scope-y, które chcesz dać agentowi (kreator sugeruje rozsądny default per case).
- 3a. Claude Desktop / Claude.ai: otwórz Ustawienia → Connectors → Add custom connector. Wklej URL serwera poniżej i token z kroku 2.
- 3b. Cursor / Continue / własny klient: dodaj wpis HTTP MCP server wskazujący na URL poniżej ze standardowym nagłówkiem
Authorization: Bearer …. Streamable HTTP transport (nie stdio, nie SSE).
- URL serwera
- https://qmailing.com/mcp
- Transport
- Streamable HTTP (rewizja protokołu MCP 2025-06-18)
Zweryfikuj połączenie
Spytaj agenta: «Show me my mailboxes». Powinien wywołać qmailing_list_mailboxes i zwrócić listę. Jeśli widzisz 401 — token zły lub odwołany. 402 — narzędzie powyżej twojego planu. 403 — token nie niesie wymaganego scope-u. Pełna matryca w Rozwiązywanie problemów.
Scope OAuth
Tokeny otrzymują scope-y przy wystawieniu. Każde narzędzie wymaga jednego lub więcej scope-ów; wywołanie agenta jest odrzucane z 403 zanim kod się wykona, jeśli brakuje scope-a. Wystaw token read-only, jeśli chcesz tylko sortować bez wysyłania.
| Scope | Pozwala | Narzędzia |
|---|---|---|
| mailbox:read | Listować i przeglądać swoje skrzynki | list_mailboxes, get_mailbox |
| mailbox:write | Tworzyć nowe skrzynki na własnych domenach | create_mailbox |
| domain:read | Listować domeny i czytać checklistę DNS | list_domains, get_dns_records |
| domain:write | Zarezerwowane na przyszłe endpointy zarządzania domenami | — |
| email:read | Czytać maile, pobierać załączniki | list_emails, get_email, get_attachment |
| email:send | Wysyłać pocztę wychodzącą przez swoje skrzynki | send_email |
| webhook:manage | Rejestrować, listować i odwoływać endpointy webhook | list_webhooks, register_webhook, delete_webhook |
Dostępne narzędzia
Dwanaście narzędzi, jeden serwer. Każde narzędzie niesie JSON-Schema dla swoich argumentów i blok annotations (tytuł, hint-y read-only / destructive), którego agent używa do decyzji o pytaniu o potwierdzenie przed wywołaniem. Poniżej: przykładowe prompty zgrupowane według intencji użytkownika.
Skrzynki
List Mailboxes
mailbox:readqmailing_list_mailboxes
Zwraca każdą skrzynkę, którą posiadasz — adresy, status, liczniki wiadomości i wykorzystane miejsce.
Przykładowy prompt: «What mailboxes do I have?»
Get Mailbox
mailbox:readqmailing_get_mailbox
Pojedyncza skrzynka po UUID — ustawienia forwardowania, liczniki, przynależność do grup.
Przykładowy prompt: «Show me the settings for sales@my-startup.com.»
Create Mailbox
mailbox:writeqmailing_create_mailbox
Utworzyć nową skrzynkę na własnej domenie. Local-part + opcjonalny display name i forwarding.
Przykładowy prompt: «Create a mailbox sales@my-startup.com that forwards to me.»
Domeny i DNS
List Domains
domain:readqmailing_list_domains
Twoje powiązania custom-domen ze statusem weryfikacji MX / SPF / DKIM / DMARC i ownership-claim.
Przykładowy prompt: «Which of my domains haven't verified DKIM yet?»
Get DNS Records
domain:readqmailing_get_dns_records
Checklista DNS dla custom-domeny — host + wartość + typ + aktualny status weryfikacji per rekord.
Przykładowy prompt: «Show me the DNS records I still need to add for acme.dev.»
Poczta
List Emails
email:readqmailing_list_emails
Stronicowany listing w obrębie jednej skrzynki + folderu (INBOX, SENT, DRAFTS, TRASH, STARRED, SPAM).
Przykładowy prompt: «Show me unread emails from support@acme.dev.»
Get Email
email:readqmailing_get_email
Pojedynczy mail po UUID z pełnymi nagłówkami, sparsowanym ciałem (HTML + tekst) i metadanymi załączników.
Przykładowy prompt: «What did Alice say in her last reply?»
Get Attachment
email:readqmailing_get_attachment
Pobrać pojedynczy załącznik po email-id + indeksie. Zwraca filename + content-type + size + bajty Base64 (cap 5 MB inline).
Przykładowy prompt: «Download the invoice PDF from Alice's last email.»
Send Email
email:sendqmailing_send_email
Wysłać wychodzącego maila z jednej ze swoich skrzynek. Body plain-text + HTML, to/cc/bcc, reply threading.
Przykładowy prompt: «Send a reply to john@example.com confirming the meeting at 3pm.»
Webhooki
List Webhooks
webhook:manageqmailing_list_webhooks
Twoje zarejestrowane endpointy webhook, aktywne i odwołane, najnowsze pierwsze.
Przykładowy prompt: «Show me my webhook endpoints.»
Register Webhook
webhook:manageqmailing_register_webhook
Zarejestrować endpoint HTTP do odbierania powiadomień o zdarzeniach. Sekret podpisu zwracany JEDNORAZOWO.
Przykładowy prompt: «Register a webhook for email.received events at https://my-server.com/qmailing.»
Delete Webhook
webhook:manageqmailing_delete_webhook
Odwołać endpoint webhook. Idempotentne — już odwołane endpointy zwracają sukces.
Przykładowy prompt: «Revoke the webhook from yesterday.»
Plany i limity
Dwanaście narzędzi, cztery poziomy. FREE wystarczy do oceny integracji; PLUS odblokowuje wszystkie operacje read + write poza webhookami; PRO+ odblokowuje webhooki dla inbound-automation.
| Narzędzie | 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 z Retry-After w sekundach. PLUS i wyżej zdejmują dzienny pułap; per-token throttle 300 zapytań/min na warstwie transportu pozostaje.Rozwiązywanie problemów
Każda odpowiedź błędu zgodna z RFC-7807 problem+json — stabilny URL type, status, title, detail plus pole code dla branchowania. Agent pokazuje detail jako komunikat dla użytkownika.
| Status | Kiedy widzisz | Rozwiązanie |
|---|---|---|
| 401 | Token brak, zepsuty, wygasły lub odwołany. | Wystaw ponownie z Ustawienia → Programiści i zaktualizuj wpis connectora. |
| 402 | Narzędzie wymaga wyższego planu niż aktualny. | Upgrade — odpowiedź niesie upgradeUrl i nazwę requiredPlan. |
| 403 | Token uwierzytelniony, ale bez wymaganego scope-u. | Wystaw ponownie token z brakującym scope-em, lub przełącz na taki, który go już ma. |
| 429 | FREE przekroczył 25 zapytań/dobę lub pojedynczy token przekroczył 300 zapytań/min. | Poczekaj wskazane Retry-After sekundy. Upgrade na PLUS zdejmuje dzienny pułap. |
Prywatność i bezpieczeństwo
Tokeny OAuth są związane z jednym kontem i jednym klientem (Claude, Cursor lub własny). Tokeny są przechowywane na serwerze jako hashe bcrypt — plaintext qm_live_… jest pokazywany dokładnie raz podczas wystawienia. Odwoływalne w każdej chwili z dashboardu; odwołanie obowiązuje od następnego zapytania, bez cache.
Każde wywołanie narzędzia przechodzi trzy niezależne bramki przed logiką biznesową: (a) plan tokena musi pozwalać na żądane narzędzie, (b) set scope-ów tokena musi pokrywać zadeklarowane wymagania, (c) zasób, którego narzędzie dotyka, musi należeć do uwierzytelnionego użytkownika. Niepowodzenie którejkolwiek → błąd RFC-7807 przed wywołaniem call().
Zobacz politykę prywatności dla sub-processorów, szczegółów OAuth sign-in i retencji. Sam serwer MCP loguje metadane zapytania (timestamp, nazwa narzędzia, kod statusu) przez 30 dni — body zapytań i wyniki narzędzi nigdy nie są zapisywane w logach.