Sendmux

SDKs de Sendmux

Espacio de trabajo oficial de SDK, CLI y MCP para Sendmux.

• Documentación del producto: sendmux.ai/docs
• Referencia de la API de gestió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
• Guía de MCP: sendmux.ai/docs/ai-integrations/mcp

Paquetes

Ecosistema	Paquete	Superficie	Autenticación por clave API / alojada	Instalación	Fuente
npm	@sendmux/core	Helpers compartidos de TypeScript	n/a	npm install @sendmux/core	packages/ts/core
npm	@sendmux/sending	API de envío	smx_mbx_* o smx_agent_* aprobado por el propietario	npm install @sendmux/sending	packages/ts/sending
npm	@sendmux/mailbox	API de buzón	smx_mbx_* o smx_agent_*	npm install @sendmux/mailbox	packages/ts/mailbox
npm	@sendmux/management	API de gestión	smx_root_*	npm install @sendmux/management	packages/ts/management
npm	@sendmux/sdk	Paquete general de TypeScript	específico de la superficie	npm install @sendmux/sdk	packages/ts/sdk
npm	@sendmux/cli	CLI de sendmux	específico del comando/perfil	npm install -g @sendmux/cli	packages/ts/cli
npm	@sendmux/ai-sdk	Herramientas del SDK de Vercel AI (buzón de agente + envío)	envío y recepción smx_mbx_* o smx_agent_*	npm install @sendmux/ai-sdk	packages/ts/ai-sdk
Homebrew	sendmux	CLI de sendmux	específico del comando/perfil	brew install sendmux/tap/sendmux	Sendmux/homebrew-tap
PyPI	sendmux-core	Helpers compartidos de Python	n/a	pip install sendmux-core	packages/python/core
PyPI	sendmux-sending	API de envío	smx_mbx_* o smx_agent_* aprobado por el propietario	pip install sendmux-sending	packages/python/sending
PyPI	sendmux-mailbox	API de buzón	smx_mbx_* o smx_agent_*	pip install sendmux-mailbox	packages/python/mailbox
PyPI	sendmux-management	API de gestión	smx_root_*	pip install sendmux-management	packages/python/management
PyPI	sendmux-sdk	Paquete general de Python	específico de la superficie	pip install sendmux-sdk	packages/python/sdk
PyPI	sendmux-mcp	MCP local más servidores MCP alojados y A2A	OAuth para alojado; claves específicas de la superficie para local	pip install sendmux-mcp	packages/python/mcp
PyPI	langchain-sendmux	Kit de herramientas de LangChain (buzón de agente + envío)	OAuth REST o envío y recepción smx_mbx_* / smx_agent_*	pip install langchain-sendmux	packages/python/langchain
Go	sendmux.ai/go/v3/core	Helpers compartidos de Go	n/a	go get sendmux.ai/go/v3@v3.0.0	go/core
Go	sendmux.ai/go/v3/sending	API de envío	smx_mbx_* o smx_agent_* aprobado por el propietario	go get sendmux.ai/go/v3@v3.0.0	go/sending
Go	sendmux.ai/go/v3/mailbox	API de buzón	smx_mbx_* o smx_agent_*	go get sendmux.ai/go/v3@v3.0.0	go/mailbox
Go	sendmux.ai/go/v3/management	API de gestión	smx_root_*	go get sendmux.ai/go/v3@v3.0.0	go/management
Go	sendmux.ai/go/v3/sdk	Paquete general de Go	específico de la superficie	go get sendmux.ai/go/v3@v3.0.0	go/sdk
crates.io	sendmux	Caja general de Rust	específico de la superficie	cargo add sendmux	rust
Packagist	sendmux/core	Helpers compartidos de PHP	n/a	composer require sendmux/core:^2.1	packages/php/core
Packagist	sendmux/sending	API de envío	smx_mbx_* o smx_agent_* aprobado por el propietario	composer require sendmux/sending:^2.1	packages/php/sending
Packagist	sendmux/mailbox	API de buzón	smx_mbx_* o smx_agent_*	composer require sendmux/mailbox:^2.1	packages/php/mailbox
Packagist	sendmux/management	API de gestión	smx_root_*	composer require sendmux/management:^2.1	packages/php/management
Packagist	sendmux/sdk	Paquete general de PHP	específico de la superficie	composer require sendmux/sdk:^2.1	packages/php/sdk
RubyGems	sendmux-core	Helpers compartidos de Ruby	n/a	gem install sendmux-core	packages/ruby/core
RubyGems	sendmux-sending	API de envío	smx_mbx_* o smx_agent_* aprobado por el propietario	gem install sendmux-sending	packages/ruby/sending
RubyGems	sendmux-mailbox	API de buzón	smx_mbx_* o smx_agent_*	gem install sendmux-mailbox	packages/ruby/mailbox
RubyGems	sendmux-management	API de gestión	smx_root_*	gem install sendmux-management	packages/ruby/management
RubyGems	sendmux-sdk	Paquete general de Ruby	específico de la superficie	gem install sendmux-sdk	packages/ruby/sdk

Inicio rápido

Instale solo el paquete para la superficie que necesite.

npm install @sendmux/sending
pip install sendmux-sending
go get sendmux.ai/go/v3@v3.0.0
cargo add sendmux
composer require sendmux/sending:^2.1
gem install sendmux-sending

Use claves smx_mbx_* capaces de enviar o tokens smx_agent_* de recursos de envío aprobados por el propietario para clientes de envío. Use claves smx_mbx_* o tokens smx_agent_* con ámbito para clientes de buzón. Use claves smx_root_* raíz para clientes de gestión. Los tokens de agente permanecen limitados por los ámbitos del lado del servidor; los tokens de agente auto-registrados previamente reclamados no incluyen email.send.

Autenticación OAuth

Los clientes de superficie de TypeScript, Python, Go, PHP, Ruby y Rust aceptan un token de acceso OAuth REST simple o un proveedor que lo resuelva antes de cada solicitud. Use la API de token explícita a continuación; la configuración de clave API continúa validando los prefijos de clave.

Cliente	Configuración del token de acceso
TypeScript	accessToken: token o accessToken: () => token; se admiten proveedores asíncronos.
SDK de Vercel AI	sendmux({ accessToken: token }) o un proveedor de token asíncrono; conceda mailbox.read y email.send para un buzón.
Python	access_token=token o un invocable.
LangChain	SendmuxToolkit(access_token=token) o un invocable; conceda mailbox.read y email.send para un buzón.
Go	NewWithAccessToken(token) o NewWithTokenProvider(provider); los proveedores reciben el contexto de la solicitud.
PHP	ClientFactory::createMetaApiWithAccessToken($token) o un invocable; cada fábrica de API tiene una variante WithAccessToken.
Ruby	access_token: token o un invocable.
Rust	new_with_access_token(token) o new_with_token_provider(provider); los proveedores devuelven un futuro.

Elija una única fuente de credenciales. Su aplicación es responsable del almacenamiento seguro y la coordinación de la renovación. Solicite resource=https://sendmux.ai/api; cada API aún verifica sus ámbitos requeridos y la superficie concedida. El CLI gestiona el inicio de sesión del navegador y la renovación del token con sendmux auth:login; use sendmux auth:logout para revocar su conexión.

Configuración y ciclo de vida de OAuth.

Acceso por línea de comandos

Para acceso por línea de comandos, instale el CLI:

brew install sendmux/tap/sendmux
npm install -g @sendmux/cli
sendmux agent:register my-agent --mailbox-local-part my-agent --default --json

El registro de agente no requiere una cuenta existente ni una clave API. Crea un perfil local con una credencial duradera y revocable para leer y recibir correo. Para enviar, invite al propietario con sendmux agent:invite-owner owner@example.com --profile my-agent; después de que el propietario acepte y apruebe el envío, los comandos de la API de envío intercambian y almacenan en caché automáticamente un token delegado de una hora.

Para clientes MCP, instale sendmux-mcp o conéctese al endpoint MCP alojado:

pip install sendmux-mcp
sendmux-mcp-mailbox --help

El endpoint MCP alojado es https://mcp.sendmux.ai/mcp. Los comandos MCP locales admiten transportes stdio y HTTP; el MCP alojado usa OAuth y no requiere claves API manuales ni endpoints OAuth personalizados.

Para clientes A2A 1.0, descubra el servicio HTTP+JSON alojado desde https://a2a.sendmux.ai/.well-known/agent-card.json. Expone las mismas operaciones seleccionadas de buzón, gestión y envío con una concesión OAuth vinculada específicamente a https://a2a.sendmux.ai/a2a/v1.

Para marcos de agentes de IA, hay disponibles envoltorios de herramientas de primera parte:

npm install @sendmux/ai-sdk ai zod   # Vercel AI SDK: sendmux({ apiKey }) returns a ToolSet
pip install langchain-sendmux        # LangChain: SendmuxToolkit(api_key=...).get_tools()

Ambos envuelven los clientes generados de envío y buzón, por lo que la especificación OpenAPI sigue siendo la única fuente de verdad.

Comprobaciones de conexión

Las comprobaciones de conexión autenticadas para las tres superficies de API devuelven el equipo actual, la identidad de la credencial, la etiqueta de conexión, los permisos y los buzones autorizados. Las comprobaciones de buzón no necesitan selector de buzón ni almacenamiento aprovisionado; las comprobaciones de envío requieren email.send sin enviar un correo ni verificar la preparación de entrega. El comportamiento existente de mailboxGetMe no cambia.

Use TypeScript Sending 1.4.0, Mailbox 1.5.0 y Management 1.3.0 (o SDK general 1.4.2), CLI 1.5.0, MCP 1.7.0, Ruby SDK 1.2.0, Rust 0.3.0, Go 1.5.0, PHP 2.0.0, o Python Sending 1.4.0, Mailbox 1.4.0 y Management 1.3.0 (o SDK general 1.1.1).

Superficie	Operación de TypeScript	Comando CLI	Herramienta MCP
Gestión	managementGetConnection	management:get-connection	management_get_connection
Buzón	mailboxGetConnection	mailbox:get-connection	mailbox_get_connection
Envío	sendingGetConnection	sending:get-connection	sending_get_connection

Use la fábrica de clientes y la credencial correspondientes. Por ejemplo, con SENDMUX_API_KEY configurado con una clave de gestión:

import { createManagementClient, managementGetConnection } from "@sendmux/sdk";

const client = createManagementClient({ apiKey: process.env.SENDMUX_API_KEY! });
const response = await managementGetConnection({ client });
console.log(response.data?.data.label);

sendmux management:get-connection --json

Cada cliente de Rust expone get_connection(), que devuelve Response<Connection>. Las referencias generadas de Go, Python, PHP y Ruby incluyen la operación GetConnection correspondiente para cada superficie. Use las versiones de paquetes publicadas listadas anteriormente; el código fuente de versiones pendientes aún no está disponible a través de los registros de paquetes.

Archivos adjuntos y eventos de buzón en vivo

Los metadatos de archivos adjuntos del buzón ahora incluyen un download_url de corta duración. Obtenga esa URL rápidamente con un cliente HTTP simple; no requiere un encabezado Authorization, pero caduca después de un TTL corto. Si una URL de descarga caduca, vuelva a obtener los metadatos del mensaje o del archivo adjunto para recibir una URL nueva.

Para archivos salientes, evite colocar manualmente base64 en indicaciones o cadenas de origen. Use la ruta de contexto cero para su carril:

• CLI: sendmux mailbox:send-message --attach ./report.pdf o sendmux sending:send --attach ./report.pdf.
• TypeScript: use @sendmux/mailbox/node sendMailboxMessageWithFiles(...) o @sendmux/sending/node sendEmailWithFiles(...).
• Python: use sendmux_mailbox.send_mailbox_message_with_files(...) o sendmux_sending.send_email_with_files(...).
• MCP: los agentes pueden generar una URL de carga prefirmada, PUT bytes sin clave API y luego enviar con el blob_id devuelto.

Las cargas directas al buzón, las cargas prefirmadas, el --attach del CLI y los helpers de archivos del SDK de buzón comparten el límite de archivos adjuntos del buzón: actualmente 7,500,000 bytes por archivo adjunto. Los helpers de archivos adjuntos de la API de envío cargan bytes de archivo y envían referencias de archivos adjuntos; el límite generado de la API de envío es de máximo 10 archivos adjuntos y un cuerpo de solicitud de 25 MB.

Los archivos adjuntos generados pequeños aún pueden usar base64 en línea donde el esquema de la API lo admita. El base64 en línea de MCP está limitado a 32 KiB decodificado; use carga prefirmada, --attach del CLI o helpers de archivos del SDK para archivos reales.

Los eventos de buzón en vivo están disponibles a través de carriles idiomáticos:

• TypeScript: streamMailboxEvents(...) devuelve un iterador asíncrono sobre eventos de buzón en tiempo real tipados.
• Python: iter_mailbox_events(...) produce modelos MailboxRealtimeEvent tipados del cliente de buzón generado.
• CLI: sendmux mailbox:stream-events --follow imprime un evento JSON por línea hasta que el flujo se cierre o el proceso se interrumpa.
• MCP: use mailbox_wait_for_message para esperas limitadas dentro de llamadas de herramientas de agente, luego mailbox_get_attachment para renovar los metadatos de archivos adjuntos y obtener download_url.

Estructura del repositorio

Mantenedores: use la matriz E2E en vivo protegida para planificación sin credenciales, puertas explícitas de identidad/envío, evidencia de limpieza y reglas de auditoría de ejecución reciente. La cobertura estática y los negativos esperados de la API no son certificación de capacidad en vivo. Los escenarios de bytes de archivos adjuntos requieren verificación de retención confiable antes de la ejecución en vivo.

Ruta	Propósito
packages/ts	Paquetes del SDK de TypeScript y la CLI de sendmux.
packages/python	Paquetes del SDK de Python y el paquete sendmux-mcp.
go	Módulo de Go sendmux.ai/go/v3 y subpaquetes.
rust	Crate de Rust publicado como sendmux en crates.io.
packages/php	Fuentes de paquetes de PHP utilizadas para paquetes de Packagist y repositorios divididos públicos.
packages/ruby	Fuentes de paquetes de RubyGem.
codegen	Configuración y plantillas del generador.
scripts	Scripts auxiliares de generación, verificación, publicación y lanzamiento.
docs	Artefactos de auditoría de cobertura superficial y E2E en vivo.
.github/workflows	Flujos de trabajo de CI, canary, E2E en vivo y lanzamiento.

Versionado y soporte

Mantener los contratos de paquetes

En un checkout de fuentes, los mantenedores pueden inspeccionar el contrato de paquete MCP generado para el catálogo real de herramientas, esquemas, flujos de trabajo de carga, recurso alojado y revisiones de protocolo congeladas. Describe este checkout, no la versión ya disponible en un registro de paquetes. Los hashes de fuentes y los metadatos de distribución nativa vinculan el artefacto a sus entradas; los transportes locales y los orígenes de API ascendentes son independientes del recurso OAuth alojado.

Con las dependencias del espacio de trabajo instaladas y Python 3.10 o más reciente disponible, ejecute estos comandos desde la raíz del repositorio:

pnpm generate:mcp
pnpm test:release-state
pnpm build:mcp

La generación actualiza los metadatos editables de Python antes de descubrir herramientas sin solicitudes ascendentes. La compilación verifica el contenido de la rueda y la distribución de fuentes, un consumidor de rueda instalada fuera del checkout y los requisitos de conformidad congelados. pnpm drift:check rechaza cambios generados que no se hayan preparado o confirmado. Regenera y revisa el contrato cuando un PR de lanzamiento cambie la versión nativa de MCP; no reutilices un contrato de la versión anterior.

La validación de lanzamiento nativo cubre TypeScript, Python, Rust, Ruby y la convención de componente/etiqueta de Go. Go no tiene campo de versión en el módulo. Las versiones de PHP pertenecen a etiquetas de repositorios divididos, no a composer.version ni a release-please; las identidades y dependencias de Composer se verifican sin tratar una versión de repositorio de ruta local como evidencia de publicación. Las etiquetas y versiones publicadas exactas siguen siendo puertas de lanzamiento.

Mantenedores: puertas de publicación nativa vinculan las entradas de flujo de trabajo de lanzamiento compatibles y el comando de división de PHP a candidatos inmutables y requieren paridad estricta de esquema en vivo antes de su primera escritura. Los ayudantes de bajo nivel de Ruby, npm y Homebrew no son procedimientos de lanzamiento independientes protegidos; la promoción manual de Snap sigue siendo una política aprobada por el propietario.

Verificar la compatibilidad del tiempo de ejecución desde las fuentes

Mantenedores: el flujo de trabajo de CI separa la generación/compilación estática de las verificaciones del tiempo de ejecución del lenguaje. Una celda configurada es una verificación requerida, no una afirmación de que un checkout no lanzado haya pasado de forma remota. Los pisos de compatibilidad no son recomendaciones para implementar tiempos de ejecución EOL ascendentes.

Tiempo de ejecución	Celdas de CI requeridas	Límite del paquete candidato
Node	22, 24, 26 en Ubuntu, macOS, Windows	Seis tarballs instalados explícitamente y CLI
Python	3.10–3.14 en Ubuntu	Siete ruedas con pruebas de tiempo de ejecución; siete sdists con instalación aislada
Go	1.23.4, 1.26, 1.27 en Ubuntu	Módulo externo con un reemplazo candidato explícito; sin actualización automática de toolchain
PHP	8.2–8.5 en Ubuntu	Cinco divisiones individuales y un consumidor general todo local
Ruby	3.1, 3.2, 3.3, 3.4.1, 4.0 en Ubuntu	Cinco gemas instaladas localmente; herramientas de desarrollo solo en 3.4.1
Rust	1.82.0 y estable/última en Ubuntu	Bloqueos de fuentes independientes, crate verificado, consumidor de piso bloqueado por separado

Después de la compilación de fuentes correspondiente, ejecute node scripts/ci-consumers.mjs node, python, go o ruby desde la raíz del repositorio para verificar las importaciones instaladas fuera del checkout. Las pruebas de contrato/empaquetado de MCP solo de repositorio de Python permanecen en verificaciones de fuentes; el consumidor de rueda ejecuta pruebas de tiempo de ejecución y load_contract() instalado sin inyección de ruta de fuentes. PHP usa node scripts/check-php-splits.mjs para la verificación de composición todo local; las divisiones individuales pueden resolver dependencias hermanas publicadas y no son esa prueba.

Las celdas de Node en Linux también ejecutan node scripts/ci-consumers.mjs ai para los 12 pares exactos de AI/Zod registrados en ese ayudante. El envoltorio candidato de AI requiere Zod 3.25.76 o más reciente y conserva la cobertura de AI 5/6/7, incluida la intersección histórica de AI 5.0.0/Zod 4.0.0. El envoltorio 0.4.0 publicado aún anuncia el piso de Zod más antiguo; esta corrección requiere un lanzamiento posterior.

Para Rust, ejecute las pruebas bloqueadas de todos los objetivos/todas las características y de documentación con cargo +1.82.0, luego node scripts/ci-consumers.mjs rust con estable y 1.82.0 instalados (estable necesita Clippy). Ese ayudante resuelve las dependencias más recientes en una copia temporal, prueba y verifica cargo +stable package --locked, y verifica el crate desempaquetado usando rust/ci/floor-consumer/Cargo.lock. Nunca sustituye el bloqueo integrado de la biblioteca por el bloqueo del consumidor. Cobertura superficial y decisiones de operación de Rust distinguen métodos nombrados de operaciones parciales/brutas/no compatibles.

Límites de lanzamiento de paquetes

Los paquetes de SDK siguen los contratos de API pública de Sendmux. Las versiones de parche pueden diferir entre paquetes cuando una corrección solo afecta a un ecosistema o tiempo de ejecución.

Los clientes generados se compilan a partir de instantáneas de OpenAPI confirmadas. Cualquier cambio en el contrato de API debe actualizar las instantáneas y la salida generada en el mismo cambio.

Para obtener ayuda, abra un problema de GitHub con el nombre del paquete, la versión, el comando o la ruta de importación, y el ID de solicitud de cualquier respuesta de error de API.

Contribución

Abra solicitudes de extracción contra este repositorio. Mantenga la salida generada, las instantáneas de fuentes y los artefactos de verificación juntos en el mismo cambio.

Los problemas de seguridad deben informarse a través de Avisos de seguridad de GitHub.

Licencia

Este repositorio está disponible bajo la licencia MIT.