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

  • Ruby 3.1 or newer.
  • A Sendmux API key for the surface you are calling.

​
Install

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

​
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

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

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.