Documentazione MCP
Collega il tuo agente a QMailing
QMailing fornisce un server Model Context Protocol hostato — Claude, Cursor, Continue e qualunque altro agente compatibile MCP possono leggere la tua casella, inviare posta, gestire caselle e reagire ad eventi tramite dodici strumenti con scope. Niente npm install, niente processo locale — solo un token Bearer e un URL del server.
https://qmailing.com/mcpCos'è QMailing MCP?
https://qmailing.com/mcp è un server MCP streamable-HTTP hostato da QMailing. Qualunque client compatibile MCP (Claude Desktop, connettori Claude.ai, Cursor, Continue, agenti personalizzati) può connettersi, autenticarsi con un token Bearer OAuth e chiamare dodici strumenti mappati 1:1 sulla superficie REST di QMailing.
Per chi: indie maker, freelance e agenzie che gestiscono più domini brand e vogliono che il loro assistente AI smisti la posta in arrivo, scriva risposte, registri webhook e gestisca caselle — senza una sola riga di glue code.
Cosa non è: una API di invio transazionale come SendGrid. QMailing è un SaaS inbox completo — ogni strumento opera su caselle reali che possiedi. Il server MCP è la superficie per gli agenti; le stesse operazioni funzionano via REST puro su /api/v1/pub/* con lo stesso token.
Collegamento a Claude
Tre passi. L'emissione del token avviene nella dashboard QMailing, il collegamento nelle impostazioni di Claude.
- 1. Passa a PLUS — gli strumenti read-only di base (
list_mailboxes,get_mailbox) sono disponibili su FREE con un tetto di 25 richieste al giorno; tutto il resto richiede PLUS o superiore. - 2. Emetti un token OAuth — vai in Impostazioni → Sviluppatori → clicca su Connect to Claude. Scegli gli scope da dare all'agente (l'assistente propone un default sensato per ogni caso d'uso).
- 3a. Claude Desktop / Claude.ai: apri Impostazioni → Connectors → Add custom connector. Incolla l'URL del server sotto e il token dal passo 2.
- 3b. Cursor / Continue / client personalizzato: aggiungi una voce HTTP MCP server che punti all'URL sotto con l'header standard
Authorization: Bearer …. Streamable HTTP transport (non stdio, non SSE).
- URL del server
- https://qmailing.com/mcp
- Transport
- Streamable HTTP (revisione protocollo MCP 2025-06-18)
Verifica la connessione
Chiedi all'agente: «Show me my mailboxes». Dovrebbe chiamare qmailing_list_mailboxes e restituire la lista. Se vedi 401 — token errato o revocato. 402 — strumento sopra il tuo piano. 403 — il token non porta lo scope richiesto. Matrice completa in Risoluzione problemi.
Scope OAuth
I token ricevono gli scope all'emissione. Ogni strumento richiede uno o più scope; la chiamata dell'agente viene rifiutata con 403 prima dell'esecuzione del codice se manca uno scope. Emetti un token read-only se vuoi solo smistare senza inviare.
| Scope | Permette | Strumenti |
|---|---|---|
| mailbox:read | Elencare e ispezionare le tue caselle | list_mailboxes, get_mailbox |
| mailbox:write | Creare nuove caselle sui domini che possiedi | create_mailbox |
| domain:read | Elencare i domini e leggere la checklist DNS | list_domains, get_dns_records |
| domain:write | Riservato per futuri endpoint di gestione domini | — |
| email:read | Leggere email, scaricare allegati | list_emails, get_email, get_attachment |
| email:send | Inviare posta in uscita attraverso le tue caselle | send_email |
| webhook:manage | Registrare, elencare e revocare endpoint webhook | list_webhooks, register_webhook, delete_webhook |
Strumenti disponibili
Dodici strumenti, un server. Ogni strumento porta uno JSON-Schema per i suoi argomenti e un blocco annotations (titolo, hint read-only / destructive) che l'agente usa per decidere se chiedere conferma prima della chiamata. Sotto: prompt di esempio raggruppati per intento utente.
Caselle
List Mailboxes
mailbox:readqmailing_list_mailboxes
Restituisce ogni casella che possiedi con indirizzi, stato, contatori messaggi e utilizzo storage.
Prompt di esempio: «What mailboxes do I have?»
Get Mailbox
mailbox:readqmailing_get_mailbox
Una singola casella per UUID — impostazioni di inoltro, contatori, appartenenza ai gruppi.
Prompt di esempio: «Show me the settings for sales@my-startup.com.»
Create Mailbox
mailbox:writeqmailing_create_mailbox
Provisionare una nuova casella su un dominio che possiedi. Local-part + display name e inoltro opzionali.
Prompt di esempio: «Create a mailbox sales@my-startup.com that forwards to me.»
Domini e DNS
List Domains
domain:readqmailing_list_domains
I tuoi collegamenti di dominio personalizzato con stato di verifica MX / SPF / DKIM / DMARC e ownership-claim.
Prompt di esempio: «Which of my domains haven't verified DKIM yet?»
Get DNS Records
domain:readqmailing_get_dns_records
Checklist DNS per un dominio personalizzato — host + valore + tipo + stato di verifica attuale per record.
Prompt di esempio: «Show me the DNS records I still need to add for acme.dev.»
List Emails
email:readqmailing_list_emails
Listing paginato in una singola casella + cartella (INBOX, SENT, DRAFTS, TRASH, STARRED, SPAM).
Prompt di esempio: «Show me unread emails from support@acme.dev.»
Get Email
email:readqmailing_get_email
Una singola email per UUID con header completi, body parsato (HTML + testo) e metadati allegati.
Prompt di esempio: «What did Alice say in her last reply?»
Get Attachment
email:readqmailing_get_attachment
Recuperare un singolo allegato per email-id + indice. Restituisce filename + content-type + size + byte Base64 (cap 5 MB inline).
Prompt di esempio: «Download the invoice PDF from Alice's last email.»
Send Email
email:sendqmailing_send_email
Inviare una email in uscita da una delle tue caselle. Body plain-text + HTML, to/cc/bcc, reply threading.
Prompt di esempio: «Send a reply to john@example.com confirming the meeting at 3pm.»
Webhook
List Webhooks
webhook:manageqmailing_list_webhooks
I tuoi endpoint webhook registrati, attivi e revocati, i più recenti per primi.
Prompt di esempio: «Show me my webhook endpoints.»
Register Webhook
webhook:manageqmailing_register_webhook
Registrare un endpoint HTTP per ricevere notifiche eventi. Il secret di firma viene restituito UNA SOLA VOLTA.
Prompt di esempio: «Register a webhook for email.received events at https://my-server.com/qmailing.»
Delete Webhook
webhook:manageqmailing_delete_webhook
Revocare un endpoint webhook. Idempotente — endpoint già revocati restituiscono successo.
Prompt di esempio: «Revoke the webhook from yesterday.»
Piani e limiti
Dodici strumenti, quattro livelli. FREE basta a valutare l'integrazione; PLUS sblocca tutte le operazioni read + write tranne i webhook; PRO+ sblocca i webhook per automation inbound.
| Strumento | 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 con Retry-After in secondi. PLUS e superiori sollevano il tetto giornaliero; il throttle per-token di 300 richieste/min sul layer transport resta.Risoluzione problemi
Ogni risposta di errore segue RFC-7807 problem+json — una URL type stabile, status, title, detail più un campo code per il branching. L'agente mostra detail come messaggio utente.
| Stato | Quando lo vedi | Soluzione |
|---|---|---|
| 401 | Token mancante, malformato, scaduto o revocato. | Riemetti da Impostazioni → Sviluppatori e aggiorna il connector. |
| 402 | Lo strumento richiede un piano superiore a quello attuale. | Upgrade — la risposta porta upgradeUrl e il nome requiredPlan. |
| 403 | Token autenticato ma senza lo scope richiesto. | Riemetti un token con lo scope mancante, o usa uno che lo porta già. |
| 429 | FREE ha superato 25 richieste/giorno o un singolo token ha superato 300 richieste/minuto. | Aspetta i secondi Retry-After. Upgrade a PLUS solleva il tetto giornaliero. |
Privacy e sicurezza
I token OAuth sono legati a un singolo account e a un singolo client (Claude, Cursor o personalizzato). I token sono memorizzati lato server come hash bcrypt — il valore in chiaro qm_live_… viene mostrato esattamente una volta alla emissione. Revocabili in qualunque momento dalla dashboard; la revoca è onorata alla richiesta successiva, senza cache.
Ogni chiamata a strumento attraversa tre cancelli indipendenti prima della logica di business: (a) il piano del token deve consentire lo strumento richiesto, (b) il set di scope del token deve coprire i requisiti dichiarati, (c) la risorsa toccata deve appartenere all'utente autenticato. Fallimento di uno qualsiasi → errore RFC-7807 prima dell'esecuzione di call().
Vedi la privacy policy per sub-processor, dettagli OAuth sign-in e ritenzione. Il server MCP logga metadati di richiesta (timestamp, nome strumento, codice di stato) per 30 giorni — i body di richiesta e i risultati degli strumenti non vengono mai persistiti nei log.