API почтового ящика + отправка через Sendmux

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

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

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

• Документация Sendmux: sendmux.ai/docs

• Справочник Management API: sendmux.ai/docs/api/introduction

• Справочник Mailbox API: sendmux.ai/docs/mailbox-api/introduction

• Справочник Sending API: sendmux.ai/docs/sending-api/introduction

• Исходный репозиторий: Sendmux/sendmux-sdk

Related MCP server: mcp-server-lobstermail

Требования

• Python 3.10 или новее.

• Ключ smx_mbx_* с правом отправки или одобренный владельцем токен smx_agent_* для ресурса Sending для инструментов Sending.

• Ключ smx_mbx_* с областью почтового ящика или токен smx_agent_* с областью для инструментов 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 предоставляют конечную точку 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-ответ о состоянии для выбранных поверхностей.

Размещённая конечная точка

Публичная размещённая конечная точка MCP: https://mcp.sendmux.ai/mcp.

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

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

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

Размещённая конечная точка A2A

Та же размещённая среда выполнения предоставляет детерминированный A2A 1.0 через HTTP+JSON по адресу https://a2a.sendmux.ai/a2a/v1. Обнаружить его можно по адресу https://a2a.sendmux.ai/.well-known/agent-card.json; метаданные ресурса OAuth находятся по адресу https://a2a.sendmux.ai/.well-known/oauth-protected-resource.

Отправьте ровно один JSON DataPart в операцию A2A message:send. Его данные выбирают курируемую операцию Sendmux и предоставляют входные данные этой операции:

{
  "operationId": "managementListDomains",
  "pathParameters": {},
  "query": { "limit": 10 },
  "headers": {},
  "body": null,
  "mailboxId": null
}

operationId использует те же курируемые идентификаторы операций, что и размещённый сервис MCP. OAuth-гранты привязаны к аудитории ресурса A2A и сохраняют свои ограничения поверхности и разрешений Sendmux. Сервис возвращает один JSON DataPart, содержащий статус вышестоящего сервиса, безопасные заголовки ответа и JSON-тело (или bodyBase64 для не-JSON ответов).

Конечная точка A2A является немедленной и без сохранения состояния: потоковая передача, push-уведомления, постоянные задачи и отмена задач не объявляются и не маршрутизируются.

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

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

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

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

• Management: 21 инструмент для доменов, почтовых ящиков, журналов, метрик, сводки расходов и вебхуков. Требуется ключ smx_root_*.

• Sending: 5 инструментов для ссылок на загрузку вложений, одиночных отправок и пакетных отправок. Требуется ключ smx_mbx_* или одобренный владельцем токен smx_agent_* для ресурса Sending.

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

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

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

Когда сообщение содержит вложения:

1. Вызовите mailbox_read_attachment с message_id и attachment_id, когда вам нужно содержимое вложения.

2. Для небольших текстовых вложений прочитайте возвращённый text.

3. Для двоичных или слишком больших вложений используйте возвращённые resource_link / download_url незамедлительно вне контекста модели.

4. Используйте mailbox_get_attachment только когда достаточно метаданных или вам нужно обновить ссылку.

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

• file_path для локального stdio MCP, когда файл находится внутри корня файловой системы, объявленного клиентом.

• presign_upload_url=true для размещённого MCP или агентов с возможностью работы с оболочкой; загрузите файл по возвращённому URL с точными заголовками и без ключа API, затем отправьте с возвращённым blob_id.

• content_base64 только для крошечных файлов, созданных агентом, с ограничением 32 КиБ в декодированном виде. Если он слишком большой, переключитесь на file_path, предварительно подписанную загрузку, CLI --attach или файловые помощники SDK.

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

Для отправки из почтового ящика mailbox_send_message принимает либо крошечные встроенные объекты вложений 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[]. Избегайте встроенного base64 в Sending, кроме крошечного сгенерированного содержимого.

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

• sendmux-mcp

• sendmux-mcp-mailbox

• sendmux-mcp-management

• sendmux-mcp-sending

• sendmux-mcp-hosted

Поддержка

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

Лицензия

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