Documentation MCP
Connectez votre agent à QMailing
QMailing fournit un serveur Model Context Protocol hébergé — Claude, Cursor, Continue et tout autre agent compatible MCP peuvent lire votre boîte, envoyer du courrier, gérer les boîtes mail et réagir aux événements via douze outils à scope. Pas de npm install, pas de processus local — juste un token Bearer et une URL de serveur.
https://qmailing.com/mcpQu'est-ce que QMailing MCP ?
https://qmailing.com/mcp est un serveur MCP streamable-HTTP hébergé par QMailing. Tout client compatible MCP (Claude Desktop, connecteurs Claude.ai, Cursor, Continue, agents personnalisés) peut se connecter, s'authentifier avec un token OAuth Bearer et appeler douze outils mappés 1:1 sur la surface REST de QMailing.
Pour qui : les indie makers, freelances et agences qui jonglent avec plusieurs domaines de marque et veulent que leur assistant IA trie le courrier entrant, rédige les réponses, enregistre des webhooks et gère les boîtes — sans une seule ligne de glue code.
Ce que ce n'est pas : une API d'envoi transactionnelle comme SendGrid. QMailing est un SaaS de boîte mail complet — chaque outil opère sur de vraies boîtes que vous possédez. Le serveur MCP est la surface pour les agents ; les mêmes opérations marchent en REST simple sur /api/v1/pub/* avec le même token.
Connexion à Claude
Trois étapes. L'émission du token se fait dans le dashboard QMailing, la connexion dans les paramètres de Claude.
- 1. Passez sur PLUS — les outils en lecture seule basiques (
list_mailboxes,get_mailbox) sont disponibles sur FREE avec un plafond de 25 requêtes par jour ; tout le reste nécessite PLUS ou plus. - 2. Émettez un token OAuth — allez dans Paramètres → Développeurs → cliquez sur Connect to Claude. Choisissez les scopes à donner à l'agent (l'assistant propose un défaut sensé par cas d'usage).
- 3a. Claude Desktop / Claude.ai : ouvrez Paramètres → Connectors → Add custom connector. Collez l'URL du serveur ci-dessous et le token de l'étape 2.
- 3b. Cursor / Continue / client personnalisé : ajoutez une entrée HTTP MCP server pointant sur l'URL ci-dessous avec l'en-tête standard
Authorization: Bearer …. Streamable HTTP transport (pas stdio, pas SSE).
- URL du serveur
- https://qmailing.com/mcp
- Transport
- Streamable HTTP (révision de protocole MCP 2025-06-18)
Vérifier la connexion
Demandez à l'agent : «Show me my mailboxes». Il devrait appeler qmailing_list_mailboxes et retourner la liste. Si vous voyez 401 — token incorrect ou révoqué. 402 — outil au-dessus de votre forfait. 403 — le token ne porte pas le scope requis. Matrice complète sous Dépannage.
Scopes OAuth
Les tokens reçoivent leurs scopes à l'émission. Chaque outil exige un ou plusieurs scopes ; l'appel de l'agent est rejeté avec 403 avant l'exécution du code si un scope manque. Émettez un token en lecture seule si vous voulez uniquement trier sans envoyer.
| Scope | Permet | Outils |
|---|---|---|
| mailbox:read | Lister et consulter vos boîtes | list_mailboxes, get_mailbox |
| mailbox:write | Créer de nouvelles boîtes sur les domaines que vous possédez | create_mailbox |
| domain:read | Lister les domaines et lire la checklist DNS | list_domains, get_dns_records |
| domain:write | Réservé pour de futurs endpoints de gestion de domaines | — |
| email:read | Lire les e-mails, télécharger les pièces jointes | list_emails, get_email, get_attachment |
| email:send | Envoyer du courrier sortant via vos boîtes | send_email |
| webhook:manage | Enregistrer, lister et révoquer les endpoints webhook | list_webhooks, register_webhook, delete_webhook |
Outils disponibles
Douze outils, un serveur. Chaque outil porte un JSON-Schema pour ses arguments et un bloc d'annotations (titre, hints read-only / destructive) que l'agent utilise pour décider de demander confirmation avant l'appel. Ci-dessous : prompts d'exemple groupés par intention utilisateur.
Boîtes
List Mailboxes
mailbox:readqmailing_list_mailboxes
Renvoie chaque boîte que vous possédez avec adresses, statut, compteurs de messages et utilisation du stockage.
Prompt d'exemple: «What mailboxes do I have?»
Get Mailbox
mailbox:readqmailing_get_mailbox
Une seule boîte par UUID — paramètres de redirection, compteurs, appartenance aux groupes.
Prompt d'exemple: «Show me the settings for sales@my-startup.com.»
Create Mailbox
mailbox:writeqmailing_create_mailbox
Provisionner une nouvelle boîte sur un domaine que vous possédez. Local-part + display name et redirection optionnels.
Prompt d'exemple: «Create a mailbox sales@my-startup.com that forwards to me.»
Domaines et DNS
List Domains
domain:readqmailing_list_domains
Vos liaisons de domaines personnalisés avec statut de vérification MX / SPF / DKIM / DMARC et ownership-claim.
Prompt d'exemple: «Which of my domains haven't verified DKIM yet?»
Get DNS Records
domain:readqmailing_get_dns_records
Checklist DNS pour un domaine personnalisé — host + valeur + type + statut de vérification actuel par enregistrement.
Prompt d'exemple: «Show me the DNS records I still need to add for acme.dev.»
List Emails
email:readqmailing_list_emails
Listing paginé dans une seule boîte + dossier (INBOX, SENT, DRAFTS, TRASH, STARRED, SPAM).
Prompt d'exemple: «Show me unread emails from support@acme.dev.»
Get Email
email:readqmailing_get_email
Un seul e-mail par UUID avec en-têtes complets, corps parsé (HTML + texte) et métadonnées des pièces jointes.
Prompt d'exemple: «What did Alice say in her last reply?»
Get Attachment
email:readqmailing_get_attachment
Récupérer une pièce jointe par email-id + index. Renvoie filename + content-type + size + octets Base64 (cap 5 MB inline).
Prompt d'exemple: «Download the invoice PDF from Alice's last email.»
Send Email
email:sendqmailing_send_email
Envoyer un e-mail sortant depuis l'une de vos boîtes. Corps plain-text + HTML, to/cc/bcc, reply threading.
Prompt d'exemple: «Send a reply to john@example.com confirming the meeting at 3pm.»
Webhooks
List Webhooks
webhook:manageqmailing_list_webhooks
Vos endpoints webhook enregistrés, actifs et révoqués, les plus récents en premier.
Prompt d'exemple: «Show me my webhook endpoints.»
Register Webhook
webhook:manageqmailing_register_webhook
Enregistrer un endpoint HTTP pour recevoir les notifications d'événements. Le secret de signature est retourné UNE FOIS.
Prompt d'exemple: «Register a webhook for email.received events at https://my-server.com/qmailing.»
Delete Webhook
webhook:manageqmailing_delete_webhook
Révoquer un endpoint webhook. Idempotent — les endpoints déjà révoqués retournent succès.
Prompt d'exemple: «Revoke the webhook from yesterday.»
Forfaits et limites
Douze outils, quatre paliers. FREE suffit pour évaluer l'intégration ; PLUS débloque toutes les opérations read + write sauf les webhooks ; PRO+ débloque les webhooks pour l'automation inbound.
| Outil | 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 avec Retry-After en secondes. PLUS et plus lèvent le plafond journalier ; la limitation par-token 300 req/min sur la couche transport reste.Dépannage
Chaque réponse d'erreur suit RFC-7807 problem+json — une URL type stable, status, title, detail plus un champ code pour le branching. L'agent affiche detail comme message utilisateur.
| Statut | Quand vous le voyez | Solution |
|---|---|---|
| 401 | Token absent, malformé, expiré ou révoqué. | Ré-émettez depuis Paramètres → Développeurs et mettez à jour le connecteur. |
| 402 | Outil exige un forfait supérieur à celui du compte. | Upgradez — la réponse contient upgradeUrl et le nom requiredPlan. |
| 403 | Token authentifié mais sans le scope requis. | Ré-émettez un token avec le scope manquant coché, ou utilisez-en un qui le porte déjà. |
| 429 | FREE a dépassé 25 requêtes/jour ou un token unique a dépassé 300 requêtes/minute. | Attendez les secondes Retry-After. Upgradez sur PLUS pour lever le plafond. |
Confidentialité et sécurité
Les tokens OAuth sont liés à un seul compte et à un seul client (Claude, Cursor ou personnalisé). Les tokens sont stockés côté serveur en hash bcrypt — la valeur claire qm_live_… est affichée exactement une fois à l'émission. Révocables à tout moment depuis le dashboard ; la révocation est honorée à la requête suivante, sans cache.
Chaque appel d'outil passe trois portes indépendantes avant l'exécution de la logique métier : (a) le forfait du token doit autoriser l'outil demandé, (b) le set de scopes du token doit couvrir les exigences déclarées par l'outil, (c) la ressource touchée doit appartenir à l'utilisateur authentifié. Échec de l'un → erreur RFC-7807 avant l'exécution de call().
Voir la politique de confidentialité pour les sub-processors, détails OAuth sign-in et rétention. Le serveur MCP logue les métadonnées de requête (timestamp, nom d'outil, code de statut) pendant 30 jours — les bodies de requête et les résultats d'outils ne sont jamais persistés en logs.