MCP Documentation
Connect your agent to QMailing
QMailing ships a hosted Model Context Protocol server so Claude, Cursor, Continue, and any other MCP-compatible agent can read your inbox, send mail, manage mailboxes, and react to events through twelve scoped tools. No npm install, no local process — just a Bearer token and one server URL.
https://qmailing.com/mcpWhat is QMailing MCP?
https://qmailing.com/mcp is a streamable-HTTP MCP server hosted by QMailing. Any MCP-compatible client (Claude Desktop, Claude.ai connectors, Cursor, Continue, custom agents) can connect, authenticate with an OAuth Bearer token, and call twelve tools mapped 1:1 to the QMailing REST surface.
Who it's for: indie makers, freelancers, and agencies juggling multiple brand domains who want their AI assistant to triage inbound mail, draft replies, register webhooks, and manage mailboxes — without writing a single line of glue code.
What it isn't: a transactional sending API like SendGrid. QMailing is a full inbox SaaS — every tool resolves against real mailboxes you own. The MCP server is the agent-facing surface; the same operations work over plain REST at /api/v1/pub/* with the same token.
Connect to Claude
Three steps. The token issuing happens in the QMailing dashboard, the connection happens in Claude's settings.
- 1. Upgrade to PLUS — basic read-only tools (
list_mailboxes,get_mailbox) are available on FREE with a 25-request daily cap; everything else requires PLUS or higher. - 2. Issue an OAuth token — go to Settings → Developers → click Connect to Claude. Pick the scopes you want the agent to have (the wizard recommends a sensible default per use case).
- 3a. Claude Desktop / Claude.ai: open Settings → Connectors → Add custom connector. Paste the server URL below and the token from step 2.
- 3b. Cursor / Continue / custom: add an HTTP MCP server entry pointing at the URL below with the standard
Authorization: Bearer …header. Streamable HTTP transport (not stdio, not SSE).
- Server URL
- https://qmailing.com/mcp
- Transport
- Streamable HTTP (MCP 2025-06-18 protocol revision)
Verify the connection
Ask the agent: «Show me my mailboxes». It should call qmailing_list_mailboxes and return the list. If you see a 401 — the token is wrong or revoked. 402 — the requested tool is above your plan. 403 — the token doesn't carry the scope. See Troubleshooting below for the full matrix.
OAuth scopes
Tokens are scoped on issue. Each tool requires one or more scopes; the agent's call is rejected with 403 before any code runs if a scope is missing. Issue a read-only token if you only want triage, not send.
| Scope | Allows | Tools |
|---|---|---|
| mailbox:read | List and inspect your mailboxes | list_mailboxes, get_mailbox |
| mailbox:write | Create new mailboxes on domains you own | create_mailbox |
| domain:read | List domains and read DNS-records checklist | list_domains, get_dns_records |
| domain:write | Reserved for future domain-management endpoints | — |
| email:read | Read emails, download attachments | list_emails, get_email, get_attachment |
| email:send | Send outbound email through your mailboxes | send_email |
| webhook:manage | Register, list, and revoke webhook endpoints | list_webhooks, register_webhook, delete_webhook |
Available tools
Twelve tools, one server. Every tool carries a JSON-Schema for its arguments and a per-tool annotations block (title, read-only / destructive hints) the agent uses to decide whether to ask for confirmation before calling. Below: example prompts grouped by what the user is trying to do.
Mailboxes
List Mailboxes
mailbox:readqmailing_list_mailboxes
Returns every mailbox you own with addresses, status, message counts, and storage usage.
Example prompt: «What mailboxes do I have?»
Get Mailbox
mailbox:readqmailing_get_mailbox
Single mailbox by UUID — forwarding settings, counters, group memberships.
Example prompt: «Show me the settings for sales@my-startup.com.»
Create Mailbox
mailbox:writeqmailing_create_mailbox
Provision a new mailbox on a domain you own. Local part + optional display name and forwarding.
Example prompt: «Create a mailbox sales@my-startup.com that forwards to me.»
Domains & DNS
List Domains
domain:readqmailing_list_domains
Your custom-domain bindings with MX / SPF / DKIM / DMARC verification state and ownership claim status.
Example prompt: «Which of my domains haven't verified DKIM yet?»
Get DNS Records
domain:readqmailing_get_dns_records
The DNS checklist for a custom domain — each record's host + value + type + current verification status.
Example prompt: «Show me the DNS records I still need to add for acme.dev.»
List Emails
email:readqmailing_list_emails
Paginated listing inside one mailbox + folder (INBOX, SENT, DRAFTS, TRASH, STARRED, SPAM).
Example prompt: «Show me unread emails from support@acme.dev.»
Get Email
email:readqmailing_get_email
Single email by UUID with full headers, parsed body (HTML + text), and attachment metadata.
Example prompt: «What did Alice say in her last reply?»
Get Attachment
email:readqmailing_get_attachment
Fetch a single attachment by email-id + index. Returns filename + content-type + size + Base64 bytes (5 MB inline cap).
Example prompt: «Download the invoice PDF from Alice's last email.»
Send Email
email:sendqmailing_send_email
Send an outbound email from one of your mailboxes. Plain-text + HTML bodies, to/cc/bcc, reply threading.
Example prompt: «Send a reply to john@example.com confirming the meeting at 3pm.»
Webhooks
List Webhooks
webhook:manageqmailing_list_webhooks
Your registered webhook endpoints, both active and revoked, newest first.
Example prompt: «Show me my webhook endpoints.»
Register Webhook
webhook:manageqmailing_register_webhook
Register an HTTP endpoint to receive event notifications. The signing secret returns ONCE.
Example prompt: «Register a webhook for email.received events at https://my-server.com/qmailing.»
Delete Webhook
webhook:manageqmailing_delete_webhook
Revoke a webhook endpoint. Idempotent — already-revoked endpoints return success.
Example prompt: «Revoke the webhook from yesterday.»
Plans & limits
Twelve tools, four tiers. FREE is enough to evaluate the integration; PLUS unlocks every read + write operation except webhooks; PRO+ unlocks webhooks for inbound automation.
| 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 with Retry-After in seconds. PLUS and above lift the daily cap; the 300-requests-per-minute per-token throttle still applies on the transport layer.Troubleshooting
Every error response follows RFC-7807 problem+json — a stable type URL, status, title, detail, plus a code field for branching. The agent surfaces the detail as the user-facing message.
| Status | When you see it | Fix |
|---|---|---|
| 401 | Token missing, malformed, expired, or revoked. | Re-issue from Settings → Developers and update the connector entry. |
| 402 | Tool requires a higher plan than your account is on. | Upgrade — the response carries an upgradeUrl and the requiredPlan name. |
| 403 | Token authenticated but missing the required scope. | Re-issue a token with the missing scope checked, or switch to a token that already has it. |
| 429 | FREE tier ran past 25 requests/day or a single token exceeded 300 requests/minute. | Wait the Retry-After seconds. Upgrade to PLUS to lift the daily cap. |
Privacy & security
OAuth tokens are bound to a single account and a single client (Claude, Cursor, or your custom one). Tokens are stored as bcrypt hashes server-side — the plaintext qm_live_… value shows once on issue. Revoke any time from the dashboard; revocation is honoured on the next request, not cached.
Every tool call enforces three independent gates before any business logic runs: (a) the token's plan tier must allow the requested tool, (b) the token's scope set must cover the tool's declared requirements, (c) the resource the tool touches must belong to the authenticated user. Failing any of these returns an RFC-7807 error before the tool's call() executes.
See the privacy policy for sub-processors, OAuth sign-in details, and data retention. The MCP server itself logs request metadata (timestamp, tool name, status code) for 30 days — request bodies and tool results are never persisted to logs.