Ruby SDK

The official Ruby SDK for Sendexa. One gem, one client, every API — SMS, OTP, WhatsApp, Email, Voice, and Webhook verification.

Zero Dependencies

Uses only Ruby stdlib — net/http, openssl, json, base64. No bundler bloat.

Works Everywhere

Compatible with Rails, Sinatra, Hanami, bare Rack apps, or plain Ruby scripts.

Secure by Default

HMAC-SHA256 webhook verification with constant-time comparison to prevent timing attacks.

Idiomatic Ruby

Keyword arguments, module namespacing, and clean error classes that play well with rescue.

Installation

Bash

gem install sendexa

Requirements

Ruby 3.0 or later. Zero external dependencies — uses only net/http, openssl, json, and base64, all part of the Ruby standard library.

Initialise the Client

Create one client per process and reuse it across requests — it is thread-safe.

Ruby

require "sendexa"

client = Sendexa.new(
  api_key:    ENV["SENDEXA_API_KEY"],
  api_secret: ENV["SENDEXA_API_SECRET"]
)

API Examples

Send single and bulk SMS messages with delivery tracking.

Ruby

# Send a single SMS
resp = client.sms.send(
  to:      "0244123456",
  from:    "MyBrand",
  message: "Your order #1234 has been confirmed!"
)
puts resp["data"]["messageId"]

# Send bulk SMS
client.sms.send_bulk(
  from:    "MyBrand",
  message: "Hello from MyBrand!",   # shared fallback
  messages: [
    { to: "0244123456", message: "Hi Alice!" },
    { to: "0555987654" },             # uses shared message
  ]
)

# Check delivery status
status = client.sms.get_status(resp["data"]["messageId"])
puts status["data"]["status"]  # "delivered"

# Resend a failed message
client.sms.resend(resp["data"]["messageId"])

Error Handling

All API errors raise Sendexa::Error, which inherits from StandardError.

Ruby

begin
  resp = client.sms.send(
    to:      "0244123456",
    from:    "MyBrand",
    message: "Hello!"
  )
rescue Sendexa::Error => e
  puts e.message     # "Invalid API credentials"
  puts e.status      # 401
  puts e.code        # "INVALID_CREDENTIALS"
  puts e.request_id  # "req_abc123" (if available)
end

Attribute	Type	Description
message	String	Human-readable error description
status	Integer?	HTTP status code (e.g. 401, 422, 429)
code	String?	Machine-readable error code from Sendexa
request_id	String?	Unique request ID for support tickets
raw	Hash?	Full parsed response body

Best Practices

Store credentials in environment variables or Rails encrypted credentials — never commit them to source control.
Create one client per process and reuse it. The underlying Net::HTTP connection is reused on repeated calls to the same host.
In Rails, declare the client as a constant in an initializer (SENDEXA = Sendexa.new(...)) so it is available everywhere without passing it through the call stack.
Always verify webhook signatures with webhooks.verify before processing the payload.
Rescue Sendexa::Error at the boundary where you can act on it — retry on 5xx, surface the message on 4xx.