Email Inbox API + Sending By Sendmux

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/ai-integrations/mcp

Packages

Quick start

Install only the package for the surface you need.

npm install @sendmux/sending
pip install sendmux-sending
go get sendmux.ai/go/[email protected]
cargo add sendmux
composer require sendmux/sending:^2.1
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.

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 [email protected] --profile my-agent; after the owner accepts and approves sending, Sending API commands exchange and cache a one-hour delegated token automatically.

For stdio MCP clients, run the hosted OAuth bridge with Node.js 22 or later:

npx -y sendmux-mcp

Complete the browser sign-in on first connection. The npm bridge configuration forwards the hosted tools without a Python installation.

For local MCP with API keys, install the Python package:

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

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: 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 upload file bytes and send attachment references; 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; use presigned upload, CLI --attach, or SDK file helpers for real files.

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

Maintainers: use the protected live E2E matrix for credential-free planning, explicit identity/send gates, cleanup evidence, and fresh-run audit rules. Static coverage and expected API negatives are not live capability certification. Attachment byte scenarios require trusted retention verification before live execution.

Versioning and support

Maintain package contracts

In a source checkout, maintainers can inspect the generated MCP package contract for the actual tool catalogue, schemas, upload workflows, hosted resource, and frozen protocol revisions. It describes this checkout, not the version already available from a package registry. Source hashes and native distribution metadata bind the artifact to its inputs; local transports and upstream API origins are separate from the hosted OAuth resource.

With the workspace dependencies installed and Python 3.10 or newer available, run these commands from the repository root:

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

Generation refreshes editable Python metadata before discovering tools without upstream requests. The build checks wheel and source-distribution contents, an installed-wheel consumer outside the checkout, and the frozen conformance requirements. pnpm drift:check rejects generated changes that have not been staged or committed. Regenerate and review the contract when a release PR changes MCP's native version; do not reuse a contract from the previous version.

Native release validation covers TypeScript, Python, Rust, Ruby, and Go's component/tag convention. Go has no in-module version field. PHP versions belong to split-repository tags, not composer.version or release-please; Composer identities and dependencies are checked without treating a local path-repository version as publication evidence. Exact published tags and versions remain release gates.

Maintainers: native publication gates bind the supported release-workflow entries and PHP split command to immutable candidates and require fresh, strict live-schema parity before their first write. Low-level Ruby, npm, and Homebrew helpers are not guarded standalone release procedures; manual Snap promotion remains owner-approved policy.

Verify runtime compatibility from source

Maintainers: the CI workflow separates the generation/static build from language runtime checks. A configured cell is a required check, not a claim that an unreleased checkout has passed remotely. Compatibility floors aren't recommendations to deploy upstream-EOL runtimes.

After the corresponding source build, run node scripts/ci-consumers.mjs node, python, go, or ruby from the repository root to verify installed imports outside the checkout. Python's repository-only MCP contract/packaging tests remain in source checks; the wheel consumer runs runtime tests and installed load_contract() without source-path injection. PHP uses node scripts/check-php-splits.mjs for the all-local composition check; individual splits can resolve published sibling dependencies and aren't that proof.

Linux Node cells additionally run node scripts/ci-consumers.mjs ai for the 12 exact AI/Zod pairs recorded in that helper. The candidate AI wrapper requires Zod 3.25.76 or newer and retains AI 5/6/7 coverage, including the historical AI 5.0.0/Zod 4.0.0 intersection. The published 0.4.0 wrapper still advertises the older Zod floor; this correction requires a later release.

For Rust, run the locked all-target/all-feature and doc tests with cargo +1.82.0, then node scripts/ci-consumers.mjs rust with stable and 1.82.0 installed (stable needs Clippy). That helper resolves latest dependencies in a temporary copy, tests and verifies cargo +stable package --locked, and checks the unpacked crate using rust/ci/floor-consumer/Cargo.lock. It never substitutes the library's embedded lock for the consumer lock. Surface coverage and Rust operation decisions distinguish named methods from partial/raw/unsupported operations.

Package release boundaries

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.