SMS Quickstart Guide for Ruby

This guide is for the current version of the Ruby SDK.

Looking for v1? See our Quickstart guide for our Ruby v1 SDK.

Send your first SMS with the official ClickSend Ruby SDK (the clicksend_client gem) in under 5 minutes.

1. Prerequisites

Before you start, make sure you have:

Requirement	Details
A ClickSend account	Sign up free if you don't have one. New accounts get free credit to test with.
API credentials	Your username and API key, both on the API Credentials page of the dashboard. You'll authenticate with these, not your dashboard login password.
Ruby 2.7 or newer	Check with `ruby -v`.
Account credit	Sending SMS consumes credit. Free trial credit is enough for this guide; top up on the Billing page if you get an `INSUFFICIENT_CREDIT` error later.

2. Install

Add the gem to your Gemfile:

gem 'clicksend_client', '~> 6.0.2'

bundle install

Or install it directly:

gem install clicksend_client

3. Configure the client

The SDK authenticates with HTTP Basic auth, using your ClickSend username and API key set through ClickSend.configure. Never hard-code real credentials — load them from environment variables:

export CLICKSEND_USERNAME="your-clicksend-username"
export CLICKSEND_API_KEY="your-clicksend-api-key"

require 'clicksend_client'

ClickSend.configure do |config|
  config.username = ENV['CLICKSEND_USERNAME'] # placeholder: your ClickSend username
  config.password = ENV['CLICKSEND_API_KEY']  # placeholder: your ClickSend API key
end

sms_api = ClickSend::SmsApi.new

sms_api is now an authenticated client for every SMS endpoint (send, history, templates, delivery receipts, etc.). Each ClickSend resource has its own API class (ClickSend::MmsApi, ClickSend::ManagementApi, ClickSend::ContactsApi, ...) — construct one per resource you need; they all share the configuration set via ClickSend.configure.

4. Send your first SMS

This is a complete, runnable example. Save it as send_sms.rb, set the two environment variables from step 3, replace the to number with a real one, and run it.

require 'clicksend_client'

ClickSend.configure do |config|
  config.username = ENV['CLICKSEND_USERNAME']
  config.password = ENV['CLICKSEND_API_KEY']
end

sms_api = ClickSend::SmsApi.new

message = ClickSend::SendSmsRequestMessagesInner.new(
  source: 'sdk',
  from: 'YOUR_SENDER_ID',      # placeholder: e.g. a ClickSend number, or omit to use your default sender
  body: 'Hello from ClickSend!',
  to: '+61411111111'           # placeholder: recipient in E.164 format
)
request = ClickSend::SendSmsRequest.new(messages: [message])

begin
  result = sms_api.send_sms(send_sms_request: request)
  puts result
rescue ClickSend::ApiError => e
  puts "Failed to send SMS: #{e.code} #{e.response_body}"
end

Run it:

ruby send_sms.rb

5. Understand the response

sms_api.send_sms(...) returns a ClickSend::SendSms object. Its attributes mirror the API's JSON response (native snake_case):

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Messages queued for delivery.",
  "data": {
    "total_price": 0.0388,
    "total_count": 1,
    "queued_count": 1,
    "blocked_count": 0,
    "messages": [
      {
        "to": "+61411111111",
        "body": "Hello from ClickSend!",
        "from": "SENDERID",
        "message_id": "6811A5CE-E374-5D26-82F5-1D9E52FA9AB3",
        "message_parts": 1,
        "message_price": "0.0388",
        "status": "SUCCESS",
        "date": 1758434400
      }
    ]
  }
}

The fields you'll use most:

Field	Where	Meaning
Message ID	`result.data.messages[0].message_id`	The unique ID for this message. Quote this when contacting support or looking up delivery receipts.
Status	`result.data.messages[0].status`	The outcome for this specific message (`SUCCESS`, `INVALID_RECIPIENT`, ...). Check this per message — a batch send can succeed overall while individual messages fail (see §6).
Cost	`result.data.messages[0].message_price`	Cost of this one message. `result.data.total_price` is the sum across every message in the request.

message = result.data.messages.first
puts "Message ID: #{message.message_id}"
puts "Status: #{message.status}"
puts "Cost: #{message.message_price}"

6. Common errors

sms_api.send_sms(...) raises a ClickSend::ApiError on a non-2xx HTTP response — rescue it. But ClickSend also reports some failures — like an invalid recipient in an otherwise-valid batch — inside a 200 OK response, which won't raise at all. Always check each message's own status, not just whether the call raised.

begin
  result = sms_api.send_sms(send_sms_request: request)

  # Even on HTTP 200, check each message's own status
  result.data.messages.each do |message|
    unless message.status == 'SUCCESS'
      puts "Message to #{message.to} failed: #{message.status}"
    end
  end
rescue ClickSend::ApiError => e
  puts "#{e.code} #{e.response_body}"
end

Error	How it shows up	What it means	Fix
Authentication failure	`ClickSend::ApiError` with `.code == 401` — raised, rescued in `rescue`. `.response_body`'s `response_code` is `MISSING_CREDENTIALS` (no username/API key sent) or `INVALID_CREDENTIALS` (wrong username/API key).	Your `ClickSend.configure` username/password doesn't match a valid ClickSend account, or an env var wasn't set.	Double-check `CLICKSEND_USERNAME`/`CLICKSEND_API_KEY` are set and copied exactly from the API Credentials page — use the API key, not your dashboard password.
Invalid recipient	Request usually still returns HTTP 200 (`response_code: SUCCESS` at the top level) — the failure is on the individual message: `message.status` is `INVALID_RECIPIENT`. This does not raise — you must check the status yourself.	The destination mobile number isn't a valid, deliverable number (bad format, wrong country, disconnected, etc).	Validate/normalize numbers to E.164 (e.g. `+61411111111`) before sending, and surface per-message status values to your own logs or users.
Insufficient balance	`response_code` (or a message's `status`) is `INSUFFICIENT_CREDIT`, typically alongside a `ClickSend::ApiError` with `.code == 400` when it blocks the whole request.	Your account has run out of message credit.	Top up credit on the Billing page, or check balance first with `ClickSend::ManagementApi.new.view_account_details`.

Next steps

Full endpoint reference: developers.clicksend.com/docs/rest/v3
Every other message type (MMS, voice, email, campaigns) and account/contact management: the package README
SDK source & issues: github.com/ClickSend/clicksend-ruby-v2

Products

Developers

Resources

SMS Quickstart

On this page:

Resources: