How to Send iMessages from Ruby on Rails

Ruby on Rails developers can integrate iMessage into their applications using the Sendblue REST API. This tutorial walks you through sending messages with Faraday, receiving webhooks in a Rails controller, queuing messages with Sidekiq, and handling media attachments.

Prerequisites

Before you start, make sure you have:

Ruby 2.7+ (3.x recommended) and Rails 7+
Sendblue API credentials — sign up free to get your sb-api-key-id and sb-api-secret-key
The Faraday gem for HTTP requests (or use Net::HTTP from the standard library)

Add Faraday to your Gemfile:

gem 'faraday'
gem 'faraday-net_http'

Then run bundle install.

Making API Calls with Faraday

Sendblue's REST API uses simple JSON POST requests. Here's how to set up a reusable Faraday client:

# lib/sendblue_client.rb
require 'faraday'
require 'json'

class SendblueClient
  BASE_URL = 'https://api.sendblue.co'

  def initialize
    @api_key = ENV['SENDBLUE_API_KEY']
    @api_secret = ENV['SENDBLUE_API_SECRET']

    @conn = Faraday.new(url: BASE_URL) do |f|
      f.request :json
      f.response :json
      f.adapter :net_http
    end
  end

  def send_message(number:, content:, send_style: nil, media_url: nil)
    body = { number: number, content: content }
    body[:send_style] = send_style if send_style
    body[:media_url] = media_url if media_url

    response = @conn.post('/api/send-message') do |req|
      req.headers['sb-api-key-id'] = @api_key
      req.headers['sb-api-secret-key'] = @api_secret
      req.headers['Content-Type'] = 'application/json'
      req.body = body
    end

    response.body
  end

  def evaluate_service(number)
    response = @conn.get('/api/evaluate-service') do |req|
      req.headers['sb-api-key-id'] = @api_key
      req.headers['sb-api-secret-key'] = @api_secret
      req.params['number'] = number
    end

    response.body
  end
end

This client wraps the two most common API calls. You can extend it to cover all Sendblue endpoints.

Send Your First iMessage

With the client in place, sending an iMessage is one method call:

# In a Rails console, controller, or script:
client = SendblueClient.new

result = client.send_message(
  number: '+15551234567',
  content: 'Hello from Ruby on Rails!',
  send_style: 'celebration'
)

puts result
# => {"status"=>"QUEUED", "message_id"=>"...", ...}

The send_style parameter adds iMessage effects like celebration, fireworks, lasers, love, and confetti. These only work when the recipient has an iPhone — Sendblue automatically falls back to RCS or SMS for Android users.

You can also use Net::HTTP from the Ruby standard library if you prefer not to add Faraday as a dependency:

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.sendblue.co/api/send-message')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['sb-api-key-id'] = ENV['SENDBLUE_API_KEY']
request['sb-api-secret-key'] = ENV['SENDBLUE_API_SECRET']
request['Content-Type'] = 'application/json'
request.body = { number: '+15551234567', content: 'Hello from Ruby!' }.to_json

response = http.request(request)
puts JSON.parse(response.body)

Receive Messages with Webhooks

When someone replies to your iMessage, Sendblue sends a POST request to your webhook URL. Here's a Rails controller to handle it:

# app/controllers/webhooks_controller.rb
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def receive
    from_number = params[:from_number]
    content = params[:content]
    media_url = params[:media_url]
    service = params[:service] # "iMessage", "SMS", or "RCS"

    Rails.logger.info "[#{service}] #{from_number}: #{content}"

    # Process the incoming message
    # e.g., save to database, trigger auto-reply, notify team
    Message.create!(
      from_number: from_number,
      content: content,
      media_url: media_url,
      service: service
    )

    # Optionally auto-reply
    SendblueClient.new.send_message(
      number: from_number,
      content: "Thanks for reaching out! We'll get back to you shortly."
    )

    head :ok
  end
end

Add the route:

# config/routes.rb
post '/webhooks/receive', to: 'webhooks#receive'

Set your webhook URL in the Sendblue dashboard under Settings. For local development, use ngrok: ngrok http 3000.

Background Job Integration with Sidekiq

For production applications, you should queue message sending in background jobs to avoid blocking your web requests:

# app/jobs/send_imessage_job.rb
class SendImessageJob
  include Sidekiq::Job
  sidekiq_options queue: :messages, retry: 3

  def perform(number, content, options = {})
    client = SendblueClient.new
    result = client.send_message(
      number: number,
      content: content,
      send_style: options['send_style'],
      media_url: options['media_url']
    )

    Rails.logger.info "Sent iMessage to #{number}: #{result['status']}"
  end
end

# Usage in your controller or service:
SendImessageJob.perform_async(
  '+15551234567',
  'Your order has shipped!',
  { 'send_style' => 'celebration' }
)

Sidekiq handles retries automatically if the API call fails. This pattern ensures your web requests stay fast while messages are delivered reliably in the background.

Send Media Attachments

Send images, videos, PDFs, or contact cards alongside your message:

# Send an image
client.send_message(
  number: '+15551234567',
  content: 'Here is your invoice:',
  media_url: 'https://example.com/invoice.pdf'
)

# Send a contact card (vCard) — unique to Sendblue
client.send_message(
  number: '+15551234567',
  media_url: 'https://example.com/sales-rep.vcf'
)

Contact cards are especially powerful for sales teams. When recipients tap to save the vCard, your business name appears on all future messages. Learn more about iMessage for sales.

Check iMessage Availability

Before sending, you can check whether a phone number supports iMessage:

result = client.evaluate_service('+15551234567')

if result['is_imessage']
  # Send via iMessage (blue bubble)
  client.send_message(number: '+15551234567', content: 'Hello!')
else
  # Fall back to your SMS provider
  SmsService.send('+15551234567', 'Hello!')
end

This lets you route iPhone users through Sendblue for blue bubble delivery and Android users through your existing SMS provider for maximum deliverability.

Next Steps

You're now sending and receiving iMessages from Ruby on Rails. Here are some resources to continue:

Full API documentation — All endpoints including group messaging, typing indicators, and reactions
Webhook deep dive — Handle delivery receipts, typing indicators, and all 7 webhook types
Build an AI agent — Connect Claude or GPT to iMessage for intelligent auto-replies
CRM integrations — Connect iMessage to Salesforce, HubSpot, and more

Get your free API keys and start sending iMessages from Ruby today.

Ruby

Rails

Developer

API

Ready to send your first iMessage?

Get API access in minutes. Free sandbox, no credit card required.

Get API Access