# Sendmux/sendmux-sdk [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/Sendmux/sendmux-sdk/tree/main/packages/python/mcp  
**GitHub Stars:** 73  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sendmux-sendmux-sdk

## Description
Email inbox API MCP server for AI agents to receive, search, and send mail through hosted or local Sendmux Product MCP.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "sendmux-sdk": {
    "command": "uvx",
    "args": ["sendmux-core"],
    "env": {
      "SENDMUX_OAUTH_CLIENT_ID": "",
      "SENDMUX_OAUTH_CLIENT_SECRET": "",
      "SENDMUX_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `SENDMUX_OAUTH_CLIENT_ID`, `SENDMUX_OAUTH_CLIENT_SECRET`, `SENDMUX_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# Sendmux SDKs

[![npm version](https://img.shields.io/npm/v/@sendmux/sdk?label=npm)](https://www.npmjs.com/package/@sendmux/sdk)
[![PyPI version](https://img.shields.io/pypi/v/sendmux-sdk?label=pypi)](https://pypi.org/project/sendmux-sdk/)
[![Go Reference](https://pkg.go.dev/badge/sendmux.ai/go.svg)](https://pkg.go.dev/sendmux.ai/go)
[![crates.io version](https://img.shields.io/crates/v/sendmux?label=crates.io)](https://crates.io/crates/sendmux)
[![CI](https://github.com/Sendmux/sendmux-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Sendmux/sendmux-sdk/actions/workflows/ci.yml)
[![npm downloads](https://img.shields.io/npm/dm/@sendmux/sdk?label=npm%20downloads)](https://www.npmjs.com/package/@sendmux/sdk)
[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)

Official SDK, CLI, and MCP workspace for Sendmux.

- Product documentation: [sendmux.ai/docs](https://sendmux.ai/docs)
- Management API reference: [sendmux.ai/docs/api/introduction](https://sendmux.ai/docs/api/introduction)
- Mailbox API reference: [sendmux.ai/docs/mailbox-api/introduction](https://sendmux.ai/docs/mailbox-api/introduction)
- Sending API reference: [sendmux.ai/docs/sending-api/introduction](https://sendmux.ai/docs/sending-api/introduction)
- MCP guide: [sendmux.ai/docs/ai-integrations/mcp](https://sendmux.ai/docs/ai-integrations/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`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ts/core) |
| npm | `@sendmux/sending` | Sending API | `smx_mbx_*` or owner-approved `smx_agent_*` | `npm install @sendmux/sending` | [`packages/ts/sending`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ts/sending) |
| npm | `@sendmux/mailbox` | Mailbox API | `smx_mbx_*` or `smx_agent_*` | `npm install @sendmux/mailbox` | [`packages/ts/mailbox`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ts/mailbox) |
| npm | `@sendmux/management` | Management API | `smx_root_*` | `npm install @sendmux/management` | [`packages/ts/management`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ts/management) |
| npm | `@sendmux/sdk` | TypeScript umbrella package | surface-specific | `npm install @sendmux/sdk` | [`packages/ts/sdk`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ts/sdk) |
| npm | `@sendmux/cli` | `sendmux` CLI | command/profile-specific | `npm install -g @sendmux/cli` | [`packages/ts/cli`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/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`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ts/ai-sdk) |
| Homebrew | `sendmux` | `sendmux` CLI | command/profile-specific | `brew install sendmux/tap/sendmux` | [`Sendmux/homebrew-tap`](https://github.com/Sendmux/homebrew-tap) |
| PyPI | `sendmux-core` | Shared Python helpers | n/a | `pip install sendmux-core` | [`packages/python/core`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/python/core) |
| PyPI | `sendmux-sending` | Sending API | `smx_mbx_*` or owner-approved `smx_agent_*` | `pip install sendmux-sending` | [`packages/python/sending`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/python/sending) |
| PyPI | `sendmux-mailbox` | Mailbox API | `smx_mbx_*` or `smx_agent_*` | `pip install sendmux-mailbox` | [`packages/python/mailbox`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/python/mailbox) |
| PyPI | `sendmux-management` | Management API | `smx_root_*` | `pip install sendmux-management` | [`packages/python/management`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/python/management) |
| PyPI | `sendmux-sdk` | Python umbrella package | surface-specific | `pip install sendmux-sdk` | [`packages/python/sdk`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/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`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/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`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/python/langchain) |
| Go | `sendmux.ai/go/core` | Shared Go helpers | n/a | `go get sendmux.ai/go@v1.6.0` | [`go/core`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/go/core) |
| Go | `sendmux.ai/go/sending` | Sending API | `smx_mbx_*` or owner-approved `smx_agent_*` | `go get sendmux.ai/go@v1.6.0` | [`go/sending`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/go/sending) |
| Go | `sendmux.ai/go/mailbox` | Mailbox API | `smx_mbx_*` or `smx_agent_*` | `go get sendmux.ai/go@v1.6.0` | [`go/mailbox`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/go/mailbox) |
| Go | `sendmux.ai/go/management` | Management API | `smx_root_*` | `go get sendmux.ai/go@v1.6.0` | [`go/management`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/go/management) |
| Go | `sendmux.ai/go/sdk` | Go umbrella package | surface-specific | `go get sendmux.ai/go@v1.6.0` | [`go/sdk`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/go/sdk) |
| crates.io | `sendmux` | Rust umbrella crate | surface-specific | `cargo add sendmux` | [`rust`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/rust) |
| Packagist | `sendmux/core` | Shared PHP helpers | n/a | `composer require sendmux/core:^2.1` | [`packages/php/core`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/php/core) |
| Packagist | `sendmux/sending` | Sending API | `smx_mbx_*` or owner-approved `smx_agent_*` | `composer require sendmux/sending:^2.1` | [`packages/php/sending`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/php/sending) |
| Packagist | `sendmux/mailbox` | Mailbox API | `smx_mbx_*` or `smx_agent_*` | `composer require sendmux/mailbox:^2.1` | [`packages/php/mailbox`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/php/mailbox) |
| Packagist | `sendmux/management` | Management API | `smx_root_*` | `composer require sendmux/management:^2.1` | [`packages/php/management`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/php/management) |
| Packagist | `sendmux/sdk` | PHP umbrella package | surface-specific | `composer require sendmux/sdk:^2.1` | [`packages/php/sdk`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/php/sdk) |
| RubyGems | `sendmux-core` | Shared Ruby helpers | n/a | `gem install sendmux-core` | [`packages/ruby/core`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ruby/core) |
| RubyGems | `sendmux-sending` | Sending API | `smx_mbx_*` or owner-approved `smx_agent_*` | `gem install sendmux-sending` | [`packages/ruby/sending`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ruby/sending) |
| RubyGems | `sendmux-mailbox` | Mailbox API | `smx_mbx_*` or `smx_agent_*` | `gem install sendmux-mailbox` | [`packages/ruby/mailbox`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ruby/mailbox) |
| RubyGems | `sendmux-management` | Management API | `smx_root_*` | `gem install sendmux-management` | [`packages/ruby/management`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ruby/management) |
| RubyGems | `sendmux-sdk` | Ruby umbrella package | surface-specific | `gem install sendmux-sdk` | [`packages/ruby/sdk`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ruby/sdk) |

## Quick start

Install only the package for the surface you need.

```sh
npm install @sendmux/sending
pip install sendmux-sending
go get sendmux.ai/go@v1.6.0
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.

| 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](https://sendmux.ai/docs/developer-tools/oauth).

## Command-line access

For command-line access, install the CLI:

```sh
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:

```sh
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:

```sh
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:

```ts
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);
```

```sh
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`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ts) | TypeScript SDK packages and the `sendmux` CLI. |
| [`packages/python`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/python) | Python SDK packages and the `sendmux-mcp` package. |
| [`go`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/go) | Go module `sendmux.ai/go` and subpackages. |
| [`rust`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/rust) | Rust crate published as `sendmux` on crates.io. |
| [`packages/php`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/php) | PHP package sources used for Packagist packages and public split repositories. |
| [`packages/ruby`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/packages/ruby) | RubyGem package sources. |
| [`codegen`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/codegen) | Generator configuration and templates. |
| [`scripts`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/scripts) | Generation, verification, publishing, and release helper scripts. |
| [`docs`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/docs) | Surface-coverage and live E2E audit artefacts. |
| [`.github/workflows`](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/.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](https://github.com/Sendmux/sendmux-sdk/issues) 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](https://github.com/Sendmux/sendmux-sdk/security/advisories).

## Licence

This repository is available under the [MIT licence](https://github.com/Sendmux/sendmux-sdk/blob/HEAD/LICENSE).