Skip to main content
The Courier Ruby SDK provides typed access to the Courier REST API from any Ruby 3.2+ application. It ships with Yard docstrings, RBS and RBI type definitions for Sorbet, and uses net/http with connection pooling. Available on GitHub and RubyGems.

​
Installation

Add to your Gemfile: 
gem "trycourier", "~> 4.7"
Then run bundle install. Requires Ruby 3.2+.

​
Quick Start

require "bundler/setup"
require "courier"

client = Courier::Client.new

response = client.send_.message(
  message: {
    to: { email: "you@example.com" },
    content: {
      title: "Hello from Courier!",
      body: "Your first notification, sent with the Ruby SDK."
    }
  }
)

puts response.request_id
The client reads COURIER_API_KEY from your environment automatically. You can also pass it explicitly: Courier::Client.new(api_key: "your-key").
The method is send_ (with a trailing underscore) because send is a reserved method in Ruby.

​
Authentication

Get your API key from Settings > API Keys in the Courier dashboard. Set it as an environment variable: 
export COURIER_API_KEY="your-api-key"
The SDK picks this up by default. To pass it explicitly: 
client = Courier::Client.new(api_key: "your-api-key")

​
Sending Notifications

​
With a template

response = client.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "my-template-id",
    data: { orderNumber: "10042", itemName: "Courier Hoodie" }
  }
)

​
With inline content

response = client.send_.message(
  message: {
    to: { email: "jane@example.com" },
    content: {
      title: "Order shipped",
      body: "Your order {{orderNumber}} has shipped!"
    },
    data: { orderNumber: "10042" },
    routing: { method: "single", channels: ["email"] }
  }
)

​
Available Resources

The SDK covers the full Courier API. Every method is documented with Yard docstrings.
ResourceNamespaceDescription
Sendclient.send_Send messages to one or more recipients
Messagesclient.messagesRetrieve status, history, and content of sent messages
Profilesclient.profilesCreate, update, and retrieve user profiles
Usersclient.usersManage preferences, tenants, and push tokens per user
Authclient.authIssue JWT tokens for client-side SDK authentication
Bulkclient.bulkSend messages to large recipient lists via jobs
Listsclient.listsManage subscription lists and their subscribers
Audiencesclient.audiencesDefine and query audience segments
Tenantsclient.tenantsManage tenants for multi-tenant setups
Automationsclient.automationsInvoke multi-step automation workflows
Brandsclient.brandsManage brand settings (logos, colors, templates)
Notificationsclient.notificationsList and inspect notification templates
Translationsclient.translationsManage localized content

​
Common Operations

​
Checking Message Status

message = client.messages.retrieve("your-message-id")
puts message.status
puts message.delivered

history = client.messages.history("your-message-id")

​
Managing User Profiles

client.profiles.create("user_123", profile: {
  email: "jane@example.com",
  phone_number: "+15551234567",
  name: "Jane Doe"
})

profile = client.profiles.retrieve("user_123")

​
Issuing JWT Tokens

result = client.auth.issue_token(
  scope: "user_id:user_123 inbox:read:messages inbox:write:events",
  expires_in: "2 days"
)

puts result.token
ScopePermission
user_id:<id>Which user the token is for (required)
inbox:read:messagesRead inbox messages
inbox:write:eventsMark messages as read/archived
read:preferencesRead notification preferences
write:preferencesUpdate notification preferences
write:user-tokensRegister push notification tokens

​
Configuration

​
Error Handling

The SDK throws typed errors for API failures. All errors extend Courier::Errors::APIError: 
begin
  client.send_.message(message: { to: { user_id: "user_123" }, template: "my-template" })
rescue Courier::Errors::APIConnectionError => e
  puts "The server could not be reached"
rescue Courier::Errors::RateLimitError => e
  puts "Rate limited; back off a bit."
rescue Courier::Errors::APIStatusError => e
  puts "API error: #{e.status}"
end

​
Retries

The SDK automatically retries failed requests up to 2 times with exponential backoff. 
client = Courier::Client.new(max_retries: 0)

# Or per-request
client.send_.message(
  message: { to: { user_id: "user_123" }, template: "my-template" },
  request_options: { max_retries: 5 }
)

​
Timeouts

Requests time out after 60 seconds by default. Configure globally or per-request: 
client = Courier::Client.new(timeout: 20)

client.send_.message(
  message: { to: { user_id: "user_123" }, template: "my-template" },
  request_options: { timeout: 5 }
)

​
More Operations

The SDK covers the full Courier REST API. Here are a few more resources beyond what’s documented above:
ResourceMethodUse case
User preferencesclient.users.preferences.retrieve(user_id)Fetch a user’s notification preferences for your preference center
Cancel a messageclient.messages.cancel(message_id)Cancel a delayed or queued message before delivery
Push tokensclient.users.tokens.add_single(token, user_id:)Register a device push token for iOS, Android, or React Native
Automationsclient.automations.invoke.invoke_ad_hoc(automation:)Run a multi-step workflow via Automations

API Reference

Full REST API docs with request/response examples.

Send API

Learn about the Send endpoint, routing, and message options.

Quickstart

Send your first notification in under two minutes.

GitHub

Source code, issues, and changelog.