Skip to main content
Use the Ruby SDK when your application needs gems for the Sending, Mailbox, or Management API.
Sending and Mailbox clients require mailbox-scoped smx_mbx_ keys. 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. 
gem install sendmux-sdk

​
Create a client

The umbrella gem exposes helpers for each surface. 
require 'sendmux/sdk'

client = Sendmux::SDK.sending(
  api_key: ENV.fetch('SENDMUX_MAILBOX_API_KEY')
)
Surface gems expose Sendmux::Sending::Client, Sendmux::Mailbox::Client, and Sendmux::Management::Client directly.

​
Choose a surface

SurfaceGemClient or helperAPI key
Sendingsendmux-sendingSendmux::SDK.sending, client.emailssmx_mbx_
Mailboxsendmux-mailboxSendmux::SDK.mailbox, client.mailbox_apismx_mbx_
Managementsendmux-managementSendmux::SDK.management, client.mailboxessmx_root_
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. 
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

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.