Skip to main content
Use the TypeScript SDK when your application needs package-managed clients for one or more Sendmux API surfaces.
Sending and Mailbox clients require mailbox-scoped smx_mbx_ keys. 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

​
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!,
});
Surface packages expose createSendingClient, createMailboxClient, and createManagementClient directly.

​
Choose a surface

SurfacePackageFactoryAPI key
Sending@sendmux/sendingcreateSendingClientsmx_mbx_
Mailbox@sendmux/mailboxcreateMailboxClientsmx_mbx_
Management@sendmux/managementcreateManagementClientsmx_root_
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.