Email Inbox API + отправка через Sendmux

API почтового ящика, входящая почта и исходящая отправка MCP-серверов для AI-агентов, с входящей почтой, корректной обработкой JSON, вебхуками и маршрутизацией через Sendmux.

Этот пакет — Sendmux MCP. Держите его отдельно от MCP, используемого инструментами документации.

Документация

Документация Sendmux: Документация Sendmux
Обзор Management API: Обзор Management API
Обзор Mailbox API: Обзор Mailbox API
Обзор Sending API: Обзор Sending API
Исходный репозиторий: Sendmux/sendmux-sdk

Требования

Python 3.10 или новее.
Ключ smx_mbx_*, обеспечивающий отправку, или токен Sending-resource smx_agent_*, одобренный владельцем, для инструментов Sending.
Ключ smx_mbx_* с областью Mailbox или токен smx_agent_* с областью Mailbox для инструментов Mailbox.
Ключ smx_root_* для инструментов Management.

Установка

pip install sendmux-mcp

Использование

Запустите единый локальный сервер с командами для конкретной поверхности.

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox
SENDMUX_API_KEY=smx_root_... sendmux-mcp-management
SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-sending

Запустите объединённый локальный сервер с sendmux-mcp.

SENDMUX_MCP_SURFACES=mailbox,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

Запустите все три локальные поверхности при наличии обоих типов ключей.

SENDMUX_MCP_SURFACES=mailbox,management,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_MANAGEMENT_API_KEY=smx_root_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

Универсальная команда sendmux-mcp также принимает --surface или --surfaces. Обёрточные команды выбирают ровно одну поверхность.

Транспорт

stdio — стандартный транспорт для локальных клиентов-агентов.

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox --transport stdio

http и streamable-http expose MCP-эндпойнт через HTTP. Режим HTTP по умолчанию использует 127.0.0.1:8765/mcp и требует отдельный MCP bearer-токен, если явно не указан отказ.

SENDMUX_API_KEY=smx_mbx_... \
SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765 --path /mcp

/health возвращает небольшой JSON-ответ состояния для выбранных поверхностей.

Размещённый endpoint

Публичный размещённый MCP-эндпойнт — https://mcp.sendmux.ai/mcp.

Для размещённых клиентов используйте HTTP-транспорт с OAuth. Не добавляйте вручную заголовки Authorization, API-ключи, кастомные OAuth-концевые точки или кастомные области, если это не требуется клиенту.

Поддерживаются размещённые OAuth-клиенты, которые пропускают запрашиваемые области при регистрации или авторизации; сервер публикует набор размещённых областей через discovery и bearer-челленджи.

Упакованный запуск sendmux-mcp-hosted запускает окружение размещённого сервера. Локальные и приватные развёртывания следует использовать вышеупомянутые локальные команды, если вы не работаете с совместимой OAuth-обоснованной размещённой средой.

Конфигурация

Настройка	Окружение	По умолчанию
Поверхности инструментов	SENDMUX_MCP_SURFACES	требуется для sendmux-mcp; обёрточные команды выбирают одну поверхность
Резервный ключ API	SENDMUX_API_KEY	принимается для совместимых конфигураций с одним ключом
Ключ Mailbox API	SENDMUX_MAILBOX_API_KEY	требуется при выборе mailbox, если не предоставлен совместимый запасной вариант
Ключ Management API	SENDMUX_MANAGEMENT_API_KEY	требуется при выборе management, если не предоставлен совместимый запасной вариант
Ключ Sending API	SENDMUX_SENDING_API_KEY	требуется при выборе sending, если запасной ключ не является ключом send-capable smx_mbx_* или владельцем одобренный Sending-resource smx_agent_* токен
Базовый URL API приложения	SENDMUX_APP_BASE_URL	https://app.sendmux.ai/api/v1
Базовый URL Sending API	SENDMUX_SENDING_BASE_URL	https://smtp.sendmux.ai/api/v1
Транспорт	SENDMUX_MCP_TRANSPORT	stdio
HTTP-хост	SENDMUX_MCP_HOST	127.0.0.1
HTTP-порт	SENDMUX_MCP_PORT	8765
HTTP-путь	SENDMUX_MCP_PATH	/mcp
HTTP bearer-токен	SENDMUX_MCP_HTTP_BEARER_TOKEN	требуется для HTTP, если не включён отказ
Разрешить неаутентифицированный HTTP	SENDMUX_MCP_ALLOW_UNAUTHENTICATED_HTTP	false
Разрешённые источники браузера	SENDMUX_MCP_ALLOWED_ORIGINS	нет разрешённых origins
Переопределение каталога снимков	SENDMUX_MCP_OPENAPI_INPUT_DIR or OPENAPI_INPUT_DIR	упакованные снимки OpenAPI
Переопределение снимка приложения	SENDMUX_MCP_APP_OPENAPI	упакованный снимок приложения
Переопределение снимка Sending	SENDMUX_MCP_SENDING_OPENAPI	упакованный снимок Sending
Тайм-аут запроса	SENDMUX_MCP_TIMEOUT_SECONDS	30
Максимальное число повторных попыток	SENDMUX_MCP_RETRY_MAX_ATTEMPTS	3

Упакованные снимки OpenAPI являются значением по умолчанию, чтобы названия инструментов, схемы и описания оставались стабильными. Путь, директорию и URL-override доступны для разработки, canary и отладки.

Поверхности инструментов

Mailbox: 25 инструментов для управляемых почтовых ящиков, обнаружения профиля/сессии, сообщений, вложений, ограниченных ожиданий сообщений, тредов, папок, поиска, подсчётов и отправок из Mailbox. Требуется ключ smx_mbx_* или токен smx_agent_* с областью. Агентские токены ограничены ограничениями сервера; предрегистрация агентов не включает email.send.
Management: 21 инструмент для доменов, почтовых ящиков, логов, метрик, сводки расходов и вебхуков. Требуется ключ smx_root_*.
Sending: 5 инструментов для ссылок на загрузку вложений, одиночной отправки и пакетной отправки. Требуется ключ smx_mbx_* или владелец-одобренный токен Sending-resource smx_agent_*.

Сервер отклоняет ключи с неверным префиксом до запуска.

Рабочий процесс вложений для агентов

Используйте mailbox_wait_for_message, когда пользователь просит агента дождаться новой почты. Инструмент ограничен; если он возвращает matched=false, вызывайте его снова, а не держите вызов MCP открытым бесконечно.

Когда у письма есть вложения:

Вызовите mailbox_read_attachment с message_id и attachment_id, когда нужно содержимое вложения.
Для небольших текстоподобных вложений прочитайте возвращённый text.
Для двоичных или крупных вложений используйте возвращённые resource_link / download_url сразу вне контекста модели.
Используйте mailbox_get_attachment только когда метаданные достаточны или нужно обновить ссылку.

Используйте mailbox_upload_attachment для исходящих вложений через MCP. Он принимает ровно один режим ввода:

file_path для локального stdio MCP, если файл внутри клиентского корневого файлового пути.
presign_upload_url=true для размещённого MCP или агентов с оболочкой; загрузите файл по возвращённому URL с точными заголовками и без API-key, затем отправьте с возвращённым blob_id.
content_base64 только для крошечных файлов, созданных агентом, ограниченных 32 KiB после декодирования. Если размер слишком велик, переключитесь на file_path, предвариальную загрузку, CLI --attach или помощники SDK.

Режимы file_path и предвариваемой загрузки используют лимит вложений Mailbox, в данный момент 7 500 000 байт на вложение. Предвариваемые загрузки также фиксируют точную объявленную длину байтов и тип контента.

Для отправок Mailbox mailbox_send_message принимает либо компактные вложения inline base64 (content, filename, content_type), либо ссылки на вложения (blob_id, filename, content_type).

Для отправок Sending API вызовите sending_upload_attachment с file_path на локальном stdio MCP, или вызовите sending_create_attachment_upload и PUT байтов вне контекста модели для размещённых/оболочечных агентов. Затем передайте {"attachment_id": "att_..."} в sending_send_email.attachments[]. Избегайте inline base64 отправки, за исключением небольшого сгенерированного контента.

Консольные скрипты

sendmux-mcp
sendmux-mcp-mailbox
sendmux-mcp-management
sendmux-mcp-sending
sendmux-mcp-hosted

Поддержка

Откройте issue в Sendmux/sendmux-sdk с названием пакета, версией, командой, транспортом и ID запроса из любой ошибки API.

Лицензия

MIT. См. файл лицензии: licence file.