Skip to main content
Use the Ruby SDK when your application needs gems for the Sending, Mailbox, or Management API.
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 for the surface you are calling.

​
Install

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

​
OAuth access tokens

Set access_token to a bare token string or callable. Do not also set api_key.
The provider runs before each request. Your application owns secure token storage, expiry checks, and refresh coordination; see OAuth for REST APIs. The same token option is available for Sending and Management clients.

​
Create a client

The umbrella gem exposes helpers for each surface.
Surface gems expose Sendmux::Sending::Client, Sendmux::Mailbox::Client, and Sendmux::Management::Client directly.

​
Choose a surface

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

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.