Документація MCP
Підключи свого агента до QMailing
QMailing постачає хостед Model Context Protocol сервер — Claude, Cursor, Continue і будь-який інший MCP-сумісний агент може читати вашу пошту, надсилати листи, керувати скриньками та реагувати на події через дванадцять scope-ованих інструментів. Без npm install і локального процесу — тільки Bearer-токен і один URL сервера.
https://qmailing.com/mcpЩо таке QMailing MCP?
https://qmailing.com/mcp — це streamable-HTTP MCP-сервер, який хостить QMailing. Будь-який MCP-сумісний клієнт (Claude Desktop, конектори Claude.ai, Cursor, Continue, кастомні агенти) може під'єднатися, авторизуватися Bearer-токеном і викликати дванадцять інструментів, які 1:1 мапляться на REST-поверхню QMailing.
Для кого: для indie-розробників, фрилансерів і агенцій, які жонглюють кількома brand-доменами і хочуть, щоб AI-асистент тріажив вхідну пошту, складав відповіді, реєстрував webhook-и та керував скриньками — без жодного рядка glue-коду.
Чим це НЕ є: це не транзакційне API для надсилання як SendGrid. QMailing — це повноцінний inbox-SaaS; кожен інструмент працює з реальними скриньками, якими ти володієш. MCP-сервер — це поверхня для агентів; ті ж операції доступні через звичайний REST на /api/v1/pub/* з тим самим токеном.
Підключення до Claude
Три кроки. Видача токена відбувається у дашборді QMailing, підключення — у налаштуваннях Claude.
- 1. Перейти на PLUS — базові read-only інструменти (
list_mailboxes,get_mailbox) доступні на FREE з лімітом 25 запитів на добу; решта вимагає PLUS або вище. - 2. Випустити OAuth-токен — заходь у Налаштування → Розробники → натискай Connect to Claude. Обери scope-и, які хочеш дати агенту (майстер пропонує розумний дефолт під кожен сценарій).
- 3a. Claude Desktop / Claude.ai: відкрий Settings → Connectors → Add custom connector. Встав URL сервера нижче і токен з кроку 2.
- 3b. Cursor / Continue / кастомний клієнт: додай запис HTTP MCP-сервера з URL нижче і стандартним заголовком
Authorization: Bearer …. Streamable HTTP transport (не stdio, не SSE).
- URL сервера
- https://qmailing.com/mcp
- Transport
- Streamable HTTP (ревізія протоколу MCP 2025-06-18)
Перевірити з'єднання
Спитай агента: «Show me my mailboxes». Він має викликати qmailing_list_mailboxes і повернути список. Якщо побачив 401 — токен неправильний або відкликаний. 402 — інструмент вище твого тарифу. 403 — токен не несе потрібного scope-у. Повна матриця в Усуненні проблем нижче.
OAuth scope-и
Токени отримують scope-и при випуску. Кожен інструмент вимагає один або кілька scope-ів; виклик агента відхиляється з 403 ще до запуску коду, якщо scope-у бракує. Випусти read-only токен, якщо хочеш тільки тріаж без надсилання.
| Scope | Дозволяє | Інструменти |
|---|---|---|
| mailbox:read | Бачити список скриньок і їхні параметри | list_mailboxes, get_mailbox |
| mailbox:write | Створювати нові скриньки на доменах, якими ти володієш | create_mailbox |
| domain:read | Бачити список доменів і чекліст DNS-записів | list_domains, get_dns_records |
| domain:write | Зарезервовано для майбутніх endpoint-ів керування доменами | — |
| email:read | Читати листи, завантажувати вкладення | list_emails, get_email, get_attachment |
| email:send | Надсилати вихідні листи через свої скриньки | send_email |
| webhook:manage | Реєструвати, переглядати та відкликати webhook-endpoint-и | list_webhooks, register_webhook, delete_webhook |
Доступні інструменти
Дванадцять інструментів, один сервер. Кожен інструмент несе JSON-Schema для своїх аргументів і блок анотацій (title, read-only / destructive hints), який агент використовує, щоб вирішити, чи питати підтвердження перед викликом. Нижче — приклади промптів, згруповані за тим, що користувач намагається зробити.
Скриньки
List Mailboxes
mailbox:readqmailing_list_mailboxes
Повертає всі скриньки, якими ти володієш — адреси, статус, кількість листів і використане сховище.
Приклад промпта: «What mailboxes do I have?»
Get Mailbox
mailbox:readqmailing_get_mailbox
Окрема скринька за UUID — налаштування форвардингу, лічильники, належність до груп.
Приклад промпта: «Show me the settings for sales@my-startup.com.»
Create Mailbox
mailbox:writeqmailing_create_mailbox
Створити нову скриньку на домені, яким ти володієш. Локальна частина + опціональні display name та форвардинг.
Приклад промпта: «Create a mailbox sales@my-startup.com that forwards to me.»
Домени і DNS
List Domains
domain:readqmailing_list_domains
Твої прив'язки custom-доменів зі статусом верифікації MX / SPF / DKIM / DMARC і ownership-claim.
Приклад промпта: «Which of my domains haven't verified DKIM yet?»
Get DNS Records
domain:readqmailing_get_dns_records
DNS-чекліст для custom-домену — host + значення + тип + поточний статус верифікації кожного запису.
Приклад промпта: «Show me the DNS records I still need to add for acme.dev.»
Пошта
List Emails
email:readqmailing_list_emails
Пагінований лістинг у межах однієї скриньки + папки (INBOX, SENT, DRAFTS, TRASH, STARRED, SPAM).
Приклад промпта: «Show me unread emails from support@acme.dev.»
Get Email
email:readqmailing_get_email
Окремий лист за UUID із повними заголовками, парсингом тіла (HTML + текст) і метаданими вкладень.
Приклад промпта: «What did Alice say in her last reply?»
Get Attachment
email:readqmailing_get_attachment
Завантажити окреме вкладення за email-id + індексом. Повертає filename + content-type + size + Base64-байти (cap 5 МБ inline).
Приклад промпта: «Download the invoice PDF from Alice's last email.»
Send Email
email:sendqmailing_send_email
Надіслати вихідний лист з однієї зі своїх скриньок. Plain-text + HTML тіла, to/cc/bcc, reply-thread-инг.
Приклад промпта: «Send a reply to john@example.com confirming the meeting at 3pm.»
Webhook-и
List Webhooks
webhook:manageqmailing_list_webhooks
Твої зареєстровані webhook-endpoint-и, активні й відкликані, найновіші першими.
Приклад промпта: «Show me my webhook endpoints.»
Register Webhook
webhook:manageqmailing_register_webhook
Зареєструвати HTTP-endpoint для отримання повідомлень про події. Підписний secret повертається ОДИН РАЗ.
Приклад промпта: «Register a webhook for email.received events at https://my-server.com/qmailing.»
Delete Webhook
webhook:manageqmailing_delete_webhook
Відкликати webhook-endpoint. Idempotent — уже відкликані endpoint-и повертають успіх.
Приклад промпта: «Revoke the webhook from yesterday.»
Тарифи й ліміти
Дванадцять інструментів, чотири тарифи. FREE достатньо для оцінки інтеграції; PLUS відкриває всі read + write операції крім webhook-ів; PRO+ відкриває webhook-и для inbound-автоматизації.
| Інструмент | 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 з Retry-After у секундах. PLUS і вище знімають денний кеп; per-token throttle 300 запитів/хв на транспортному шарі залишається.Усунення проблем
Кожна помилка йде у форматі RFC-7807 problem+json — стабільний type URL, status, title, detail плюс поле code для розгалуження логіки. Агент показує detail як повідомлення для користувача.
| Статус | Коли побачив | Що зробити |
|---|---|---|
| 401 | Токен відсутній, зіпсований, прострочений або відкликаний. | Перевипусти у Налаштування → Розробники і онови запис конектора. |
| 402 | Інструмент потребує вищого тарифу, ніж активний на акаунті. | Підвищ тариф — відповідь несе upgradeUrl і назву requiredPlan. |
| 403 | Токен автентифікований, але без потрібного scope-у. | Перевипусти токен з потрібним scope-ом або переключися на той, що його вже має. |
| 429 | FREE-тариф перетнув 25 запитів/добу або окремий токен перевищив 300 запитів/хв. | Зачекай вказані у Retry-After секунди. Перейди на PLUS, щоб зняти денний кеп. |
Приватність і безпека
OAuth-токени прив'язані до одного акаунта і одного клієнта (Claude, Cursor чи кастомний). Токени зберігаються як bcrypt-хеші на сервері — plaintext qm_live_… показується один раз під час випуску. Відклич у дашборді коли завгодно; відкликання чинне на наступному запиті, не кешується.
Кожен виклик інструмента проходить три незалежні гейти ще до запуску бізнес-логіки: (а) тариф токена має дозволяти запитаний інструмент, (б) scope-set токена має покривати декларовані вимоги інструмента, (в) ресурс, до якого тулиться інструмент, має належати автентифікованому користувачу. Падіння будь-якого з них повертає RFC-7807-помилку до запуску call().
Дивись політику приватності — sub-processors, деталі OAuth-входу, ретеншн. Сам MCP-сервер логує метадані запитів (timestamp, ім'я інструмента, статус-код) 30 днів — тіла запитів і результати інструментів у логах не зберігаються.