Sendmux SDKs

Official SDK, CLI, and MCP workspace for Sendmux.

• Product documentation: sendmux.ai/docs
• Management API reference: sendmux.ai/docs/api/introduction
• Mailbox API reference: sendmux.ai/docs/mailbox-api/introduction
• Sending API reference: sendmux.ai/docs/sending-api/introduction
• MCP guide: sendmux.ai/docs/guides/mcp

Packages

Ecosystem	Package	Surface	API-key / hosted auth	Install	Source
npm	@sendmux/core	Shared TypeScript helpers	n/a	npm install @sendmux/core	packages/ts/core
npm	@sendmux/sending	Sending API	smx_mbx_* or owner-approved smx_agent_*	npm install @sendmux/sending	packages/ts/sending
npm	@sendmux/mailbox	Mailbox API	smx_mbx_* or smx_agent_*	npm install @sendmux/mailbox	packages/ts/mailbox
npm	@sendmux/management	Management API	smx_root_*	npm install @sendmux/management	packages/ts/management
npm	@sendmux/sdk	TypeScript umbrella package	surface-specific	npm install @sendmux/sdk	packages/ts/sdk
npm	@sendmux/cli	sendmux CLI	command/profile-specific	npm install -g @sendmux/cli	packages/ts/cli
npm	@sendmux/ai-sdk	Vercel AI SDK tools (agent inbox + sending)	send + receive smx_mbx_* or smx_agent_*	npm install @sendmux/ai-sdk	packages/ts/ai-sdk
Homebrew	sendmux	sendmux CLI	command/profile-specific	brew install sendmux/tap/sendmux	Sendmux/homebrew-tap
PyPI	sendmux-core	Shared Python helpers	n/a	pip install sendmux-core	packages/python/core
PyPI	sendmux-sending	Sending API	smx_mbx_* or owner-approved smx_agent_*	pip install sendmux-sending	packages/python/sending
PyPI	sendmux-mailbox	Mailbox API	smx_mbx_* or smx_agent_*	pip install sendmux-mailbox	packages/python/mailbox
PyPI	sendmux-management	Management API	smx_root_*	pip install sendmux-management	packages/python/management
PyPI	sendmux-sdk	Python umbrella package	surface-specific	pip install sendmux-sdk	packages/python/sdk
PyPI	sendmux-mcp	Local MCP plus hosted MCP and A2A servers	OAuth for hosted; surface-specific keys for local	pip install sendmux-mcp	packages/python/mcp
PyPI	langchain-sendmux	LangChain toolkit (agent inbox + sending)	REST OAuth or send + receive smx_mbx_* / smx_agent_*	pip install langchain-sendmux	packages/python/langchain
Go	sendmux.ai/go/core	Shared Go helpers	n/a	go get sendmux.ai/go@v1.5.0	go/core
Go	sendmux.ai/go/sending	Sending API	smx_mbx_* or owner-approved smx_agent_*	go get sendmux.ai/go@v1.5.0	go/sending
Go	sendmux.ai/go/mailbox	Mailbox API	smx_mbx_* or smx_agent_*	go get sendmux.ai/go@v1.5.0	go/mailbox
Go	sendmux.ai/go/management	Management API	smx_root_*	go get sendmux.ai/go@v1.5.0	go/management
Go	sendmux.ai/go/sdk	Go umbrella package	surface-specific	go get sendmux.ai/go@v1.5.0	go/sdk
crates.io	sendmux	Rust umbrella crate	surface-specific	cargo add sendmux	rust
Packagist	sendmux/core	Shared PHP helpers	n/a	composer require sendmux/core:^2.0	packages/php/core
Packagist	sendmux/sending	Sending API	smx_mbx_* or owner-approved smx_agent_*	composer require sendmux/sending:^2.0	packages/php/sending
Packagist	sendmux/mailbox	Mailbox API	smx_mbx_* or smx_agent_*	composer require sendmux/mailbox:^2.0	packages/php/mailbox
Packagist	sendmux/management	Management API	smx_root_*	composer require sendmux/management:^2.0	packages/php/management
Packagist	sendmux/sdk	PHP umbrella package	surface-specific	composer require sendmux/sdk:^2.0	packages/php/sdk
RubyGems	sendmux-core	Shared Ruby helpers	n/a	gem install sendmux-core	packages/ruby/core
RubyGems	sendmux-sending	Sending API	smx_mbx_* or owner-approved smx_agent_*	gem install sendmux-sending	packages/ruby/sending
RubyGems	sendmux-mailbox	Mailbox API	smx_mbx_* or smx_agent_*	gem install sendmux-mailbox	packages/ruby/mailbox
RubyGems	sendmux-management	Management API	smx_root_*	gem install sendmux-management	packages/ruby/management
RubyGems	sendmux-sdk	Ruby umbrella package	surface-specific	gem install sendmux-sdk	packages/ruby/sdk

Quick start

Install only the package for the surface you need.

npm install @sendmux/sending
pip install sendmux-sending
go get sendmux.ai/go@v1.5.0
cargo add sendmux
composer require sendmux/sending:^2.0
gem install sendmux-sending

Use send-capable smx_mbx_* keys or owner-approved Sending-resource smx_agent_* tokens for Sending clients. Use smx_mbx_* keys or scoped smx_agent_* tokens for Mailbox clients. Use root smx_root_* keys for Management clients. Agent tokens remain limited by server-side scopes; pre-claim self-registered agent tokens do not include email.send.

OAuth authentication

TypeScript, Python, Go, PHP, Ruby, and Rust surface clients accept a bare REST OAuth access token or a provider that resolves one before each request. Use the explicit token API below; API-key configuration continues to validate key prefixes.

Client	Access-token configuration
TypeScript	accessToken: token or accessToken: () => token; async providers are supported.
Vercel AI SDK	sendmux({ accessToken: token }) or an async token provider; grant mailbox.read and email.send for one mailbox.
Python	access_token=token or a callable.
LangChain	SendmuxToolkit(access_token=token) or a callable; grant mailbox.read and email.send for one mailbox.
Go	NewWithAccessToken(token) or NewWithTokenProvider(provider); providers receive the request context.
PHP	ClientFactory::createMetaApiWithAccessToken($token) or a callable; each API factory has a WithAccessToken variant.
Ruby	access_token: token or a callable.
Rust	new_with_access_token(token) or new_with_token_provider(provider); providers return a future.

Choose one credential source. Your application owns secure storage and refresh coordination. Request resource=https://sendmux.ai/api; each API still checks its required scopes and granted surface. The CLI manages browser login and token refresh with sendmux auth:login; use sendmux auth:logout to revoke its connection.

OAuth setup and lifecycle.

Command-line access

For command-line access, install the CLI:

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

Agent registration does not require an existing account or API key. It creates a local profile with a durable, revocable credential for reading and receiving mail. To send, invite the owner with sendmux agent:invite-owner owner@example.com --profile my-agent; after the owner accepts and approves sending, Sending API commands exchange and cache a one-hour delegated token automatically.

For MCP clients, install sendmux-mcp or connect to the hosted MCP endpoint:

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

The hosted MCP endpoint is https://mcp.sendmux.ai/mcp. Local MCP commands support stdio and HTTP transports; hosted MCP uses OAuth and does not require manual API keys or custom OAuth endpoints.

For A2A 1.0 clients, discover the hosted HTTP+JSON service from https://a2a.sendmux.ai/.well-known/agent-card.json. It exposes the same curated mailbox, management, and sending operations with an OAuth grant bound specifically to https://a2a.sendmux.ai/a2a/v1.

For AI-agent frameworks, first-party tool wrappers are available:

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()

Both wrap the generated Sending and Mailbox clients, so the OpenAPI spec stays the single source of truth.

Connection checks

Authenticated connection checks for all three API surfaces return the current team, credential identity, connection label, permissions and authorised mailboxes. Mailbox checks need no mailbox selector or provisioned storage; Sending checks require email.send without sending an email or checking delivery readiness. Existing mailboxGetMe behaviour is unchanged.

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

Surface	TypeScript operation	CLI command	MCP tool
Management	managementGetConnection	management:get-connection	management_get_connection
Mailbox	mailboxGetConnection	mailbox:get-connection	mailbox_get_connection
Sending	sendingGetConnection	sending:get-connection	sending_get_connection

Use the corresponding client factory and credential. For example, with SENDMUX_API_KEY set to a Management key:

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

Each Rust client exposes get_connection(), returning Response<Connection>. Generated Go, Python, PHP and Ruby references include the corresponding GetConnection operation for each surface. Use the released package versions listed above; source code for pending releases is not yet available through package registries.

Attachments And Live Mailbox Events

Mailbox attachment metadata now includes a short-lived download_url. Fetch that URL promptly with a plain HTTP client; it does not require an Authorization header, but it expires after a short TTL. If a download URL expires, re-fetch the message or attachment metadata to receive a fresh URL.

For outbound files, avoid manually placing base64 in prompts or source strings. Use the zero-context path for your lane:

• CLI: sendmux mailbox:send-message --attach ./report.pdf or sendmux sending:send --attach ./report.pdf.
• TypeScript: use @sendmux/mailbox/node sendMailboxMessageWithFiles(...) or @sendmux/sending/node sendEmailWithFiles(...).
• Python: use sendmux_mailbox.send_mailbox_message_with_files(...) or sendmux_sending.send_email_with_files(...).
• MCP: local stdio can use mailbox_upload_attachment with file_path; hosted and shell-capable agents can mint a presigned upload URL, PUT bytes to it without an API key, then send with the returned blob_id.

Mailbox direct uploads, presigned uploads, CLI --attach, and mailbox SDK file helpers share the mailbox attachment cap: currently 7,500,000 bytes per attachment. Sending API attachment helpers encode files into the send request body; the generated Sending API limit is max 10 attachments and a 25 MB request body.

Small generated attachments can still use inline base64 where the API schema supports them. MCP inline base64 is capped at 32 KiB decoded; the cheaper alternatives are file_path, presigned upload, CLI --attach, and SDK file helpers.

Live mailbox events are available through idiomatic lanes:

• TypeScript: streamMailboxEvents(...) returns an async iterator over typed mailbox realtime events.
• Python: iter_mailbox_events(...) yields typed MailboxRealtimeEvent models from the generated mailbox client.
• CLI: sendmux mailbox:stream-events --follow prints one JSON event per line until the stream closes or the process is interrupted.
• MCP: use mailbox_wait_for_message for bounded waits inside agent tool calls, then mailbox_get_attachment to renew attachment metadata and fetch download_url.

Repository structure

Path	Purpose
packages/ts	TypeScript SDK packages and the sendmux CLI.
packages/python	Python SDK packages and the sendmux-mcp package.
go	Go module sendmux.ai/go and subpackages.
rust	Rust crate published as sendmux on crates.io.
packages/php	PHP package sources used for Packagist packages and public split repositories.
packages/ruby	RubyGem package sources.
codegen	Generator configuration and templates.
scripts	Generation, verification, publishing, and release helper scripts.
docs	Surface-coverage and live E2E audit artefacts.
.github/workflows	CI, canary, live E2E, and release workflows.

Versioning and support

SDK packages track the Sendmux public API contracts. Patch versions can differ between packages when a fix only affects one ecosystem or runtime.

Generated clients are built from committed OpenAPI snapshots. Any API contract change must update the snapshots and generated output in the same change.

For help, open a GitHub issue with the package name, version, command or import path, and the request ID from any API error response.

Contributing

Open pull requests against this repository. Keep generated output, source snapshots, and verification artefacts together in the same change.

Security issues should be reported through GitHub Security Advisories.

Licence

This repository is available under the MIT licence.