API de bandeja de entrada de correo + envío mediante Sendmux

API de bandeja de entrada de correo electrónico, correo entrante y servidores MCP y A2A de envío saliente para agentes de IA, con recepción de correo, análisis JSON limpio, webhooks y enrutamiento multiproveedor a través de Sendmux.

Este paquete es el MCP de Sendmux. Mantenlo separado de cualquier MCP de búsqueda de documentación utilizado por las herramientas de documentación.

Documentación

• Documentación de Sendmux: sendmux.ai/docs

• Referencia de la API de administración: sendmux.ai/docs/api/introduction

• Referencia de la API de buzón: sendmux.ai/docs/mailbox-api/introduction

• Referencia de la API de envío: sendmux.ai/docs/sending-api/introduction

• Repositorio de código: Sendmux/sendmux-sdk

Related MCP server: mcp-server-lobstermail

Requisitos

• Python 3.10 o superior.

• Una clave smx_mbx_* con capacidad de envío o un token smx_agent_* de recurso de envío aprobado por el propietario para las herramientas de envío.

• Una clave smx_mbx_* limitada al buzón o un token smx_agent_* con ámbito limitado para las herramientas de buzón.

• Una clave smx_root_* para las herramientas de administración.

Instalación

pip install sendmux-mcp

Uso

Ejecuta un único servidor local con los comandos específicos por superficie.

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

Ejecuta un servidor local combinado con sendmux-mcp.

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

Ejecuta las tres superficies locales cuando dispongas de ambos tipos de clave.

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

El comando genérico sendmux-mcp también acepta --surface o --surfaces. Los comandos envoltorios seleccionan exactamente una superficie.

Transportes

stdio es el transporte predeterminado para clientes MCP locales.

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

http y streamable-http exponen el endpoint MCP a través de HTTP. El modo HTTP usa por defecto 127.0.0.1:8765/mcp y requiere un token de portador MCP separado, salvo que se desactive explícitamente.

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 devuelve una pequeña respuesta JSON de estado para las superficies seleccionadas.

Endpoint alojado

El endpoint MCP público y alojado es https://mcp.sendmux.ai/mcp.

Para clientes alojados, usa el transporte HTTP con OAuth. No añadas cabeceras Authorization manuales, claves API, endpoints OAuth personalizados ni ámbitos personalizados salvo que tu cliente los requiera explícitamente.

Se admiten clientes OAuth alojados que omitan los ámbitos solicitados durante el registro o la autorización; el servidor anuncia el conjunto de ámbitos alojados mediante descubrimiento y desafíos de portador.

El comando empaquetado sendmux-mcp-hosted ejecuta el runtime de servidor alojado. Los despliegues locales y privados deben usar los comandos locales anteriores, a menos que operes un entorno compatible, alojado y basado en OAuth.

Endpoint A2A alojado

El mismo runtime alojado expone A2A 1.0 determinista sobre HTTP+JSON en https://a2a.sendmux.ai/a2a/v1. Descúbrelo desde https://a2a.sendmux.ai/.well-known/agent-card.json; los metadatos de recurso OAuth están en https://a2a.sendmux.ai/.well-known/oauth-protected-resource.

Envía exactamente un DataPart JSON a la operación message:send del A2A. Sus datos seleccionan una operación curada de Sendmux y proporcionan las entradas de esa operación:

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

operationId utiliza los mismos identificadores de operación curados que el servicio MCP alojado. Las concesiones OAuth están vinculadas a la audiencia del recurso A2A y conservan sus límites de superficie y permisos de Sendmux. El servicio devuelve un DataPart JSON que contiene el estado ascendente, las cabeceras de respuesta seguras y el cuerpo JSON (o bodyBase64 para respuestas que no son JSON).

El endpoint A2A es inmediato y sin estado: no se anuncia ni se enruta streaming, notificaciones push, tareas persistentes ni cancelación de tareas.

Configuración

Las instantáneas OpenAPI incluidas en el paquete son las predeterminadas para mantener estables los nombres de herramienta, los esquemas y las descripciones publicados. Se dispone de anulaciones por ruta, archivo directorio y URL para ejecuciones de desarrollo, canning y depuración.

Superficies de herramientas

• Buzón: 25 herramientas para buzones concedidos, descubrimiento de perfiles/sesiones, mensajes, adjuntos, esperas acotadas de mensajes, hilos, carpetas, búsqueda, recuentos y envíos desde buzón. Requiere una clave smx_mbx_* o un token smx_agent_* con ámbito. Los tokens de agente siguen limitados por los ámbitos del servidor; los tokens de agente autorregistrados y no reclamados no incluyen email.send.

• Administración: 21 herramientas para dominios, buzones, registros, métricas, resumen de gastos y webhooks. Requiere una clave smx_root_*.

• Envío: 5 herramientas para referencias de carga de adjuntos, envíos individuales y envíos por lotes. Requiere una clave smx_mbx_* habilitada para envío o un token smx_agent_* de recurso de envío aprobado por el propietario.

El servidor rechaza las claves con el prefijo incorrecto antes de iniciarse.

Flujo de trabajo de adjuntos para agentes

Usa mailbox_wait_for_message cuando un usuario le pida a un agente que espere correo nuevo. La herramienta es acotada; si devuelve matched=false, vuelve a llamarla en lugar de mantener una llamada de herramienta MCP abierta indefinidamente.

Cuando un mensaje tenga adjuntos:

1. Llama a mailbox_read_attachment con message_id y attachment_id cuando necesites el contenido del adjunto.

2. Para adjuntos pequeños de texto, lee el campo text devuelto.

3. Para adjuntos binarios o demasiado grandes, usa el resource_link / download_url devuelto inmediatamente fuera del contexto del modelo.

4. Usa mailbox_get_attachment solo cuando los metadatos sean suficientes o necesites actualizar el enlace.

Usa mailbox_upload_attachment para adjuntos salientes a través de MCP. Acepta exactamente un modo de entrada:

• file_path para MCP stdio local cuando el archivo esté dentro de una raíz de archivos declarada por el cliente.

• presign_upload_url=true para MCP alojado o agentes con shell; sube el archivo a la URL devuelta con las cabeceras exactas y sin clave API, y luego envíal. con el blob_id devuelto.

• content_base64 solo para archivos peque generados por el agente, con un máximo de 32 KiB descodificados. Si es demasiado grande, cambia a file_path, subida prefirmada, el --attach de CLI o los asistentes de archivos del SDK.

Los modos file_path y de subida prefirmada usan el límite de adjuntos del buzón, actualmente de 7,500,000 bytes por archivo. Las subidas prefirmadas también fijan la longitud de bytes exacta y el tipo de contenido declarado.

Para los envíos del buzón, mailbox_send_message acepta objetos de adjunto en línea en base64 (content, filename, content_type) o referencias a archivos subidos (blob_id, filename, content_type).

Para los envíos de la API de envío, llama sending_upload_attachment con file_path en MCP stdio local, o llama sending_create_attachment_upload y haz un PUT de los bytes fuera del contexto del modelo para agentes alojados o con shell. Luego pasa {"attachment_id": "att_..."} en sending_send_email.attachments[]. Evita el base64 en línea en Sending excepto para contenido generado muy pequeño.

Scripts de consola

• sendmux-mcp

• sendmux-mcp-mailbox

• sendmux-mcp-management

• sendmux-mcp-sending

• sendmux-mcp-hosted

Soporte

Abre una incidencia en Sendmux/sendmux-sdk con el nombre del paquete, la versión, el comando, el transporte y el ID de solicitud de cualquier error de API.

Licencia

MIT. Consulta el archivo de licencia.