Sendmux

SDKs do Sendmux

Espaço de trabalho oficial de SDK, CLI e MCP para o Sendmux.

• Documentação do produto: sendmux.ai/docs
• Referência da API de gerenciamento: sendmux.ai/docs/api/introduction
• Referência da API de caixa de entrada: sendmux.ai/docs/mailbox-api/introduction
• Referência da API de envio: sendmux.ai/docs/sending-api/introduction
• Guia de MCP: sendmux.ai/docs/ai-integrations/mcp

Pacotes

Ecossistema	Pacote	Superfície	Autenticação por API-key / hospedada	Instalação	Código-fonte
npm	@sendmux/core	Auxiliares TypeScript compartilhados	n/d	npm install @sendmux/core	packages/ts/core
npm	@sendmux/sending	API de envio	smx_mbx_* ou smx_agent_* aprovado pelo proprietário	npm install @sendmux/sending	packages/ts/sending
npm	@sendmux/mailbox	API de caixa de entrada	smx_mbx_* ou smx_agent_*	npm install @sendmux/mailbox	packages/ts/mailbox
npm	@sendmux/management	API de gerenciamento	smx_root_*	npm install @sendmux/management	packages/ts/management
npm	@sendmux/sdk	Pacote abrangente TypeScript	específico da superfície	npm install @sendmux/sdk	packages/ts/sdk
npm	@sendmux/cli	CLI sendmux	específico de comando/perfil	npm install -g @sendmux/cli	packages/ts/cli
npm	@sendmux/ai-sdk	Ferramentas do Vercel AI SDK (caixa de entrada do agente + envio)	envio + recebimento smx_mbx_* ou smx_agent_*	npm install @sendmux/ai-sdk	packages/ts/ai-sdk
Homebrew	sendmux	CLI sendmux	específico de comando/perfil	brew install sendmux/tap/sendmux	Sendmux/homebrew-tap
PyPI	sendmux-core	Auxiliares Python compartilhados	n/d	pip install sendmux-core	packages/python/core
PyPI	sendmux-sending	API de envio	smx_mbx_* ou smx_agent_* aprovado pelo proprietário	pip install sendmux-sending	packages/python/sending
PyPI	sendmux-mailbox	API de caixa de entrada	smx_mbx_* ou smx_agent_*	pip install sendmux-mailbox	packages/python/mailbox
PyPI	sendmux-management	API de gerenciamento	smx_root_*	pip install sendmux-management	packages/python/management
PyPI	sendmux-sdk	Pacote abrangente Python	específico da superfície	pip install sendmux-sdk	packages/python/sdk
PyPI	sendmux-mcp	MCP local mais servidores MCP hospedados e A2A	OAuth para hospedado; chaves específicas da superfície para local	pip install sendmux-mcp	packages/python/mcp
PyPI	langchain-sendmux	Kit de ferramentas LangChain (caixa de entrada do agente + envio)	OAuth REST ou envio + recebimento smx_mbx_* / smx_agent_*	pip install langchain-sendmux	packages/python/langchain
Go	sendmux.ai/go/v3/core	Auxiliares Go compartilhados	n/d	go get sendmux.ai/go/v3@v3.0.0	go/core
Go	sendmux.ai/go/v3/sending	API de envio	smx_mbx_* ou smx_agent_* aprovado pelo proprietário	go get sendmux.ai/go/v3@v3.0.0	go/sending
Go	sendmux.ai/go/v3/mailbox	API de caixa de entrada	smx_mbx_* ou smx_agent_*	go get sendmux.ai/go/v3@v3.0.0	go/mailbox
Go	sendmux.ai/go/v3/management	API de gerenciamento	smx_root_*	go get sendmux.ai/go/v3@v3.0.0	go/management
Go	sendmux.ai/go/v3/sdk	Pacote abrangente Go	específico da superfície	go get sendmux.ai/go/v3@v3.0.0	go/sdk
crates.io	sendmux	Crate abrangente Rust	específico da superfície	cargo add sendmux	rust
Packagist	sendmux/core	Auxiliares PHP compartilhados	n/d	composer require sendmux/core:^2.1	packages/php/core
Packagist	sendmux/sending	API de envio	smx_mbx_* ou smx_agent_* aprovado pelo proprietário	composer require sendmux/sending:^2.1	packages/php/sending
Packagist	sendmux/mailbox	API de caixa de entrada	smx_mbx_* ou smx_agent_*	composer require sendmux/mailbox:^2.1	packages/php/mailbox
Packagist	sendmux/management	API de gerenciamento	smx_root_*	composer require sendmux/management:^2.1	packages/php/management
Packagist	sendmux/sdk	Pacote abrangente PHP	específico da superfície	composer require sendmux/sdk:^2.1	packages/php/sdk
RubyGems	sendmux-core	Auxiliares Ruby compartilhados	n/d	gem install sendmux-core	packages/ruby/core
RubyGems	sendmux-sending	API de envio	smx_mbx_* ou smx_agent_* aprovado pelo proprietário	gem install sendmux-sending	packages/ruby/sending
RubyGems	sendmux-mailbox	API de caixa de entrada	smx_mbx_* ou smx_agent_*	gem install sendmux-mailbox	packages/ruby/mailbox
RubyGems	sendmux-management	API de gerenciamento	smx_root_*	gem install sendmux-management	packages/ruby/management
RubyGems	sendmux-sdk	Pacote abrangente Ruby	específico da superfície	gem install sendmux-sdk	packages/ruby/sdk

Início rápido

Instale apenas o pacote para a superfície que você precisa.

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 chaves smx_mbx_* com capacidade de envio ou tokens smx_agent_* de recurso de envio aprovados pelo proprietário para clientes de envio. Use chaves smx_mbx_* ou tokens smx_agent_* com escopo para clientes de caixa de entrada. Use chaves smx_root_* raiz para clientes de gerenciamento. Tokens de agente permanecem limitados por escopos no lado do servidor; tokens de agente auto-registrados pré-reivindicados não incluem email.send.

Autenticação OAuth

Clientes de superfície em TypeScript, Python, Go, PHP, Ruby e Rust aceitam um token de acesso OAuth REST simples ou um provedor que resolve um antes de cada requisição. Use a API de token explícita abaixo; a configuração por API-key continua validando prefixos de chave.

Cliente	Configuração de token de acesso
TypeScript	accessToken: token ou accessToken: () => token; provedores assíncronos são suportados.
Vercel AI SDK	sendmux({ accessToken: token }) ou um provedor de token assíncrono; conceda mailbox.read e email.send para uma caixa de entrada.
Python	access_token=token ou um callable.
LangChain	SendmuxToolkit(access_token=token) ou um callable; conceda mailbox.read e email.send para uma caixa de entrada.
Go	NewWithAccessToken(token) ou NewWithTokenProvider(provider); provedores recebem o contexto da requisição.
PHP	ClientFactory::createMetaApiWithAccessToken($token) ou um callable; cada fábrica de API tem uma variante WithAccessToken.
Ruby	access_token: token ou um callable.
Rust	new_with_access_token(token) ou new_with_token_provider(provider); provedores retornam um future.

Escolha uma única fonte de credencial. Sua aplicação é responsável pelo armazenamento seguro e coordenação de renovação. Solicite resource=https://sendmux.ai/api; cada API ainda verifica seus escopos obrigatórios e a superfície concedida. O CLI gerencia login no navegador e renovação de token com sendmux auth:login; use sendmux auth:logout para revogar sua conexão.

Configuração e ciclo de vida do OAuth.

Acesso por linha de comando

Para acesso por linha de comando, instale o CLI:

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

O registro de agente não exige conta existente ou API-key. Ele cria um perfil local com uma credencial durável e revogável para ler e receber e-mails. Para enviar, convide o proprietário com sendmux agent:invite-owner owner@example.com --profile my-agent; após o proprietário aceitar e aprovar o envio, os comandos da API de envio trocam e armazenam em cache automaticamente um token delegado de uma hora.

Para clientes MCP, instale sendmux-mcp ou conecte-se ao endpoint MCP hospedado:

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

O endpoint MCP hospedado é https://mcp.sendmux.ai/mcp. Os comandos MCP locais suportam transportes stdio e HTTP; o MCP hospedado usa OAuth e não exige API-keys manuais ou endpoints OAuth personalizados.

Para clientes A2A 1.0, descubra o serviço HTTP+JSON hospedado em https://a2a.sendmux.ai/.well-known/agent-card.json. Ele expõe as mesmas operações selecionadas de caixa de entrada, gerenciamento e envio com uma concessão OAuth vinculada especificamente a https://a2a.sendmux.ai/a2a/v1.

Para frameworks de agentes de IA, wrappers de ferramentas de primeira parte estão disponíveis:

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 encapsulam os clientes gerados de Envio e Caixa de entrada, então a especificação OpenAPI permanece a única fonte de verdade.

Verificações de conexão

Verificações de conexão autenticadas para todas as três superfícies de API retornam a equipe atual, identidade da credencial, rótulo da conexão, permissões e caixas de entrada autorizadas. Verificações de caixa de entrada não precisam de seletor de caixa de entrada ou armazenamento provisionado; verificações de envio exigem email.send sem enviar um e-mail ou verificar prontidão de entrega. O comportamento existente de mailboxGetMe permanece inalterado.

Use TypeScript Sending 1.4.0, Mailbox 1.5.0 e Management 1.3.0 (ou umbrella SDK 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, ou Python Sending 1.4.0, Mailbox 1.4.0 e Management 1.3.0 (ou umbrella SDK 1.1.1).

Superfície	Operação TypeScript	Comando CLI	Ferramenta MCP
Gerenciamento	managementGetConnection	management:get-connection	management_get_connection
Caixa de entrada	mailboxGetConnection	mailbox:get-connection	mailbox_get_connection
Envio	sendingGetConnection	sending:get-connection	sending_get_connection

Use a fábrica de cliente e a credencial correspondentes. Por exemplo, com SENDMUX_API_KEY definido como uma chave de gerenciamento:

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 Rust expõe get_connection(), retornando Response<Connection>. As referências geradas em Go, Python, PHP e Ruby incluem a operação GetConnection correspondente para cada superfície. Use as versões de pacote lançadas listadas acima; o código-fonte de versões pendentes ainda não está disponível nos registros de pacotes.

Anexos e eventos ao vivo da caixa de entrada

Os metadados de anexos da caixa de entrada agora incluem um download_url de curta duração. Busque essa URL prontamente com um cliente HTTP simples; ela não exige cabeçalho Authorization, mas expira após um TTL curto. Se uma URL de download expirar, busque novamente os metadados da mensagem ou do anexo para receber uma URL nova.

Para arquivos de saída, evite colocar base64 manualmente em prompts ou strings de origem. Use o caminho de contexto zero para sua via:

• CLI: sendmux mailbox:send-message --attach ./report.pdf ou sendmux sending:send --attach ./report.pdf.
• TypeScript: use @sendmux/mailbox/node sendMailboxMessageWithFiles(...) ou @sendmux/sending/node sendEmailWithFiles(...).
• Python: use sendmux_mailbox.send_mailbox_message_with_files(...) ou sendmux_sending.send_email_with_files(...).
• MCP: agentes podem gerar uma URL de upload pré-assinada, enviar PUT bytes para ela sem API-key e depois enviar com o blob_id retornado.

Uploads diretos da caixa de entrada, uploads pré-assinados, --attach do CLI e auxiliares de arquivo do SDK da caixa de entrada compartilham o limite de anexos da caixa de entrada: atualmente 7,500,000 bytes por anexo. Os auxiliares de anexo da API de envio enviam bytes de arquivo e referências de anexo; o limite da API de envio gerada é de no máximo 10 anexos e um corpo de requisição de 25 MB.

Anexos gerados pequenos ainda podem usar base64 inline onde o esquema da API suporta. O base64 inline do MCP é limitado a 32 KiB decodificados; use upload pré-assinado, --attach do CLI ou auxiliares de arquivo do SDK para arquivos reais.

Eventos ao vivo da caixa de entrada estão disponíveis por vias idiomáticas:

• TypeScript: streamMailboxEvents(...) retorna um iterador assíncrono sobre eventos de caixa de entrada em tempo real tipados.
• Python: iter_mailbox_events(...) produz modelos MailboxRealtimeEvent tipados do cliente de caixa de entrada gerado.
• CLI: sendmux mailbox:stream-events --follow imprime um evento JSON por linha até o stream fechar ou o processo ser interrompido.
• MCP: use mailbox_wait_for_message para esperas limitadas dentro de chamadas de ferramenta do agente e depois mailbox_get_attachment para renovar metadados de anexo e buscar download_url.

Estrutura do repositório

Mantenedores: use a matriz E2E ao vivo protegida para planejamento sem credenciais, portões explícitos de identidade/envio, evidência de limpeza e regras de auditoria de execução recente. Cobertura estática e negativos esperados de API não são certificação de capacidade ao vivo. Cenários de bytes de anexo exigem verificação confiável de retenção antes da execução ao vivo.

Caminho	Finalidade
packages/ts	Pacotes do SDK TypeScript e a CLI sendmux.
packages/python	Pacotes do SDK Python e o pacote sendmux-mcp.
go	Módulo Go sendmux.ai/go/v3 e subpacotes.
rust	Crate Rust publicado como sendmux no crates.io.
packages/php	Fontes do pacote PHP usadas para pacotes Packagist e repositórios públicos divididos.
packages/ruby	Fontes do pacote RubyGem.
codegen	Configuração do gerador e modelos.
scripts	Scripts auxiliares de geração, verificação, publicação e lançamento.
docs	Artefatos de auditoria de cobertura de superfície e E2E ao vivo.
.github/workflows	Workflows de CI, canário, E2E ao vivo e lançamento.

Versionamento e suporte

Manter contratos de pacotes

Em um checkout de fonte, os mantenedores podem inspecionar o contrato de pacote MCP gerado para o catálogo real de ferramentas, esquemas, fluxos de upload, recurso hospedado e revisões de protocolo congeladas. Ele descreve este checkout, não a versão já disponível em um registro de pacotes. Hashes de fonte e metadados de distribuição nativa vinculam o artefato às suas entradas; transportes locais e origens de API upstream são separados do recurso OAuth hospedado.

Com as dependências do workspace instaladas e Python 3.10 ou mais recente disponível, execute estes comandos a partir da raiz do repositório:

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

A geração atualiza os metadados Python editáveis antes de descobrir ferramentas sem solicitações upstream. A compilação verifica o conteúdo da wheel e da distribuição de fonte, um consumidor de wheel instalado fora do checkout e os requisitos de conformidade congelados. pnpm drift:check rejeita alterações geradas que não foram preparadas ou confirmadas. Regere e revise o contrato quando um PR de lançamento alterar a versão nativa do MCP; não reutilize um contrato da versão anterior.

A validação de lançamento nativo cobre TypeScript, Python, Rust, Ruby e a convenção de componente/tag do Go. Go não tem campo de versão no módulo. As versões PHP pertencem a tags de repositórios divididos, não a composer.version ou release-please; identidades e dependências do Composer são verificadas sem tratar uma versão de repositório de caminho local como evidência de publicação. Tags e versões publicadas exatas permanecem como portões de lançamento.

Mantenedores: portões de publicação nativa vinculam as entradas de fluxo de trabalho de lançamento suportadas e o comando de divisão PHP a candidatos imutáveis e exigem paridade de esquema ao vivo estrita e recente antes da primeira gravação. Auxiliares Ruby, npm e Homebrew de baixo nível não são procedimentos de lançamento independentes protegidos; a promoção manual do Snap permanece como política aprovada pelo proprietário.

Verificar compatibilidade de runtime a partir da fonte

Mantenedores: o workflow de CI separa a geração/compilação estática das verificações de runtime de linguagem. Uma célula configurada é uma verificação obrigatória, não uma afirmação de que um checkout não lançado passou remotamente. Pisos de compatibilidade não são recomendações para implantar runtimes EOL upstream.

Runtime	Células de CI obrigatórias	Limite de pacote candidato
Node	22, 24, 26 no Ubuntu, macOS, Windows	Seis tarballs instalados explicitamente e CLI
Python	3.10–3.14 no Ubuntu	Sete wheels com testes de runtime; sete sdists com instalação isolada
Go	1.23.4, 1.26, 1.27 no Ubuntu	Módulo externo com substituição candidata explícita; sem atualização automática de toolchain
PHP	8.2–8.5 no Ubuntu	Cinco divisões individuais e um consumidor guarda-chuva totalmente local
Ruby	3.1, 3.2, 3.3, 3.4.1, 4.0 no Ubuntu	Cinco gems instaladas localmente; ferramentas de desenvolvimento apenas em 3.4.1
Rust	1.82.0 e stable/latest no Ubuntu	Locks de fonte independentes, crate verificado, consumidor de piso separadamente bloqueado

Após a compilação de fonte correspondente, execute node scripts/ci-consumers.mjs node, python, go ou ruby a partir da raiz do repositório para verificar importações instaladas fora do checkout. Os testes de contrato/empacotamento MCP apenas do repositório Python permanecem em verificações de fonte; o consumidor de wheel executa testes de runtime e load_contract() instalado sem injeção de caminho de fonte. PHP usa node scripts/check-php-splits.mjs para a verificação de composição totalmente local; divisões individuais podem resolver dependências irmãs publicadas e não são essa prova.

Células Node Linux também executam node scripts/ci-consumers.mjs ai para os 12 pares exatos AI/Zod registrados nesse auxiliar. O wrapper AI candidato requer Zod 3.25.76 ou mais recente e mantém cobertura AI 5/6/7, incluindo a interseção histórica AI 5.0.0/Zod 4.0.0. O wrapper 0.4.0 publicado ainda anuncia o piso Zod mais antigo; esta correção requer um lançamento posterior.

Para Rust, execute os testes de todos os alvos/todos os recursos e de documentação bloqueados com cargo +1.82.0, depois node scripts/ci-consumers.mjs rust com stable e 1.82.0 instalados (stable precisa de Clippy). Esse auxiliar resolve dependências mais recentes em uma cópia temporária, testa e verifica cargo +stable package --locked e verifica o crate descompactado usando rust/ci/floor-consumer/Cargo.lock. Ele nunca substitui o lock embutido da biblioteca pelo lock do consumidor. Cobertura de superfície e decisões de operação Rust distinguem métodos nomeados de operações parciais/brutas/não suportadas.

Limites de lançamento de pacotes

Os pacotes SDK acompanham os contratos da API pública do Sendmux. Versões de patch podem diferir entre pacotes quando uma correção afeta apenas um ecossistema ou runtime.

Clientes gerados são construídos a partir de snapshots OpenAPI confirmados. Qualquer alteração de contrato de API deve atualizar os snapshots e a saída gerada na mesma alteração.

Para ajuda, abra uma issue no GitHub com o nome do pacote, versão, comando ou caminho de importação e o ID da solicitação de qualquer resposta de erro de API.

Contribuindo

Abra pull requests contra este repositório. Mantenha a saída gerada, snapshots de fonte e artefatos de verificação juntos na mesma alteração.

Problemas de segurança devem ser relatados por meio de GitHub Security Advisories.

Licença

Este repositório está disponível sob a licença MIT.