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

# Ruby SDK

> Install and configure the Qubrics Ruby SDK gems.

Use the Ruby SDK when your application needs gems for the Sending, Mailbox, or Management API.

> [!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

* Ruby 3.1 or newer.
* An API key or [REST OAuth grant](https://sendmux.ai/docs/developer-tools/oauth.md) for the surface you are calling.

## Install

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

```bash Umbrella theme={null}
gem install sendmux-sdk
```

```bash Sending theme={null}
gem install sendmux-sending
```

```bash Mailbox theme={null}
gem install sendmux-mailbox
```

```bash Management theme={null}
gem install sendmux-management
```

## OAuth access tokens

Set `access_token` to a bare token string or callable. Do not also set `api_key`.

```ruby theme={null}
require 'sendmux/sdk'

client = Sendmux::Mailbox::Client.new(
  access_token: -> { ENV.fetch('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.

## Create a client

The umbrella gem exposes helpers for each surface.

```ruby Sending theme={null}
require 'sendmux/sdk'

client = Sendmux::SDK.sending(
  api_key: ENV.fetch('QUBRICS_MAILBOX_API_KEY')
)
```

```ruby Mailbox theme={null}
require 'sendmux/sdk'

client = Sendmux::SDK.mailbox(
  api_key: ENV.fetch('QUBRICS_MAILBOX_API_KEY')
)
```

```ruby Management theme={null}
require 'sendmux/sdk'

client = Sendmux::SDK.management(
  api_key: ENV.fetch('QUBRICS_ROOT_API_KEY')
)
```

Surface gems expose `Sendmux::Sending::Client`, `Sendmux::Mailbox::Client`, and `Sendmux::Management::Client` directly.

## Choose a surface

| Surface | Gem | Client or helper | API key |
| - | - | - | - |
| Sending | `sendmux-sending` | `Sendmux::SDK.sending`, `client.emails` | `smx_mbx_` or owner-approved `smx_agent_` with `email.send` |
| Mailbox | `sendmux-mailbox` | `Sendmux::SDK.mailbox`, `client.mailbox_api` | `smx_mbx_` or scoped `smx_agent_` |
| Management | `sendmux-management` | `Sendmux::SDK.management`, `client.mailboxes` | `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.sendmux.ai/api/v1` by default. Mailbox and Management use `https://app.sendmux.ai/api/v1`.

## Shared API behaviour

Surface clients validate API key prefixes, configure bearer auth, and map generated API errors.

### Pagination

List responses use cursor pagination with `pagination.has_more` and `pagination.next_cursor`. The core gem exports `Sendmux::Core.each_cursor()` and `Sendmux::Core::CursorPager` for cursor iteration when you wrap a page-fetching function.

### Retries and rate limits

Surface clients call `Sendmux::Core::Retry.configure()` by default. Retries apply to safe methods and retry-safe `POST` requests that include `Idempotency-Key`, then honour `Retry-After` and `X-RateLimit-Reset` response headers.

Pass `Sendmux::Core::RetryOptions` into a surface helper or client to change attempts, delays, or jitter.

### Idempotency and ETags

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

```ruby theme={null}
headers = Sendmux::Core::Headers.conditional(if_match: etag)
headers.merge!(Sendmux::Core::Headers.idempotency_key('order-123'))
```

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

### Errors

Generated API errors are mapped to `Sendmux::Core::ApiError`. The error includes status, code, retryability, request ID, param, nested errors, response body, and response headers when available.

Use the request ID when contacting 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 `sendmux-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.