> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Install and configure the Qubrics TypeScript SDK packages.

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

> [!NOTE]
>
> For API-key authentication, 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 API-key clients require
> team-scoped `smx_root_` keys.

## Requirements

* An API key or [REST OAuth grant](https://sendmux.ai/docs/developer-tools/oauth.md) 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.

```bash Umbrella theme={null}
npm install @qubrics/sdk
```

```bash Sending theme={null}
npm install @qubrics/sending
```

```bash Mailbox theme={null}
npm install @qubrics/mailbox
```

```bash Management theme={null}
npm install @qubrics/management
```

## OAuth access tokens

Set `accessToken` to a bare token string or a synchronous or asynchronous provider. Do not also set `apiKey`.

```typescript theme={null}
import { createMailboxClient } from "@qubrics/mailbox";

const client = createMailboxClient({
  accessToken: () => process.env.QUBRICS_ACCESS_TOKEN!,
});
```

The provider runs before each request. Your application owns secure token storage, expiry checks, and refresh coordination; see [OAuth for REST APIs](https://sendmux.ai/docs/developer-tools/oauth.md#refresh-and-disconnect). The same token option is available for Sending and Management clients.

The `@qubrics/ai-sdk` wrapper accepts the same `accessToken` option in `sendmux(...)`. To use all three tools, request `mailbox.read` and `email.send` and select one mailbox at consent; the tools do not supply a mailbox selector.

## Create a client

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

```typescript Sending theme={null}
import { sending } from "@qubrics/sdk";

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

```typescript Mailbox theme={null}
import { mailbox } from "@qubrics/sdk";

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

```typescript Management theme={null}
import { management } from "@qubrics/sdk";

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

Surface packages expose `createSendingClient`, `createMailboxClient`, and `createManagementClient` directly.

## Choose a surface

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

> [!NOTE]
>
> Durable `smx_agent_` tokens are mailbox-compatible and include `mailbox.read`
> and `email.receive`, not `email.send`. After owner acceptance and approval,
> exchange the durable token for a one-hour Sending-resource token before sending.

Sending uses `https://smtp.qubrics.com/api/v1` by default. Mailbox and Management use `https://app.qubrics.com/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.

```typescript theme={null}
import { core } from "@qubrics/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

> [card] [SDK overview](https://sendmux.ai/docs/developer-tools/sdks)
>
> Choose the right package family and API surface.

> [card] [Versioning and support](https://sendmux.ai/docs/developer-tools/sdks/versioning-support.md)
>
> Check compatibility, support, and upgrade guidance.

> [card] [Sending API](https://sendmux.ai/docs/sending-api/introduction.md)
>
> Review the Sending API contract used by `@qubrics/sending`.

> [card] [API keys](https://sendmux.ai/docs/account/api-keys.md)
>
> Create and scope the credentials used by SDK clients.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.