TypeScript SDK

Use the TypeScript SDK when your application needs package-managed clients for one or more Sendmux API surfaces.

Sending clients accept a send-capable smx_mbx_ key or owner-approved Sending-resource smx_agent_ token. Mailbox clients accept smx_mbx_ keys or scoped smx_agent_ tokens. Management clients require team-scoped smx_root_ keys.

Requirements

A Sendmux API key for the surface you are calling.
An application that can install packages from npm.

Install

Install the umbrella package when one application needs more than one API surface.

npm install @sendmux/sdk

npm install @sendmux/sending

npm install @sendmux/mailbox

npm install @sendmux/management

Create a client

The umbrella package exports sending, mailbox, and management namespaces. Each namespace exposes the same factory as its surface package.

import { sending } from "@sendmux/sdk";

const client = sending.createSendingClient({
  apiKey: process.env.SENDMUX_MAILBOX_API_KEY!,
});

import { mailbox } from "@sendmux/sdk";

const client = mailbox.createMailboxClient({
  apiKey: process.env.SENDMUX_MAILBOX_API_KEY!,
});

import { management } from "@sendmux/sdk";

const client = management.createManagementClient({
  apiKey: process.env.SENDMUX_ROOT_API_KEY!,
});

Surface packages expose createSendingClient, createMailboxClient, and createManagementClient directly.

Choose a surface

Surface	Package	Factory	API key
Sending	`@sendmux/sending`	`createSendingClient`	`smx_mbx_` or owner-approved `smx_agent_` with `email.send`
Mailbox	`@sendmux/mailbox`	`createMailboxClient`	`smx_mbx_` or scoped `smx_agent_`
Management	`@sendmux/management`	`createManagementClient`	`smx_root_`

Pre-claim smx_agent_ tokens are mailbox-compatible only. Owner-approved Sending-resource smx_agent_ tokens can send. Pre-claim self-registered agent tokens include mailbox.read and email.receive, not email.send.

Sending uses https://smtp.sendmux.ai/api/v1 by default. Mailbox and Management use https://app.sendmux.ai/api/v1.

Shared API behaviour

The SDK configures bearer authentication, retries, and error mapping when you create a surface client.

Pagination

List responses use cursor pagination with pagination.has_more and pagination.next_cursor. The core package exports paginate() for cursor iteration when you wrap a page-fetching function.

Retries and rate limits

The default retry client retries safe methods and retry-safe POST requests that include Idempotency-Key. It honours Retry-After and X-RateLimit-Reset response headers. Pass retry into a client factory to change maxAttempts, delay, replay body size, or jitter.

Idempotency and ETags

Use core header helpers when a generated operation accepts custom headers.

import { core } from "@sendmux/sdk";

const retryHeaders = core.idempotencyHeaders("order-123");
const updateHeaders = core.conditionalHeaders({ ifMatch: etag });
const cacheHeaders = core.conditionalHeaders({ ifNoneMatch: etag });

Use Idempotency-Key for retry-safe mutating requests. Use If-Match and If-None-Match with single-resource endpoints that support ETags.

Errors

Generated client errors are mapped to SendmuxApiError. The error exposes the API error code, retryability, request ID, response status, headers, and raw body when available. Use error.retryable and error.requestId when deciding whether to retry or contact support.

Next steps

SDK overview

Choose the right package family and API surface.

Versioning and support

Check compatibility, support, and upgrade guidance.

Sending API

Review the Sending API contract used by @sendmux/sending.

API keys

Create and scope the credentials used by SDK clients.

Getting started

SDKs and CLI

Use cases

Integrations

AI integrations

Teams and access

Sending

Receiving

Monitoring

Webhooks

Requirements

Install

Create a client

Choose a surface

Shared API behaviour

Retries and rate limits

Idempotency and ETags

Errors

Next steps

SDK overview

Versioning and support

Sending API

API keys

​Requirements

​Install

​Create a client

​Choose a surface

​Shared API behaviour

​Pagination

​Retries and rate limits

​Idempotency and ETags

​Errors

​Next steps

SDK overview

Versioning and support

Sending API

API keys

Requirements

Install

Create a client

Choose a surface

Shared API behaviour

Pagination

Retries and rate limits

Idempotency and ETags

Errors

Next steps