Courier Ruby SDK

The Courier Ruby SDK gives typed access to the 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"

Then run bundle install. Requires Ruby 3.2+. See RubyGems for the latest version.

Quick start

require "bundler/setup"
require "courier"

client = Courier::Client.new

response = client.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" }
  }
)

puts response.request_id

The client reads COURIER_API_KEY from your environment. Pass it explicitly: Courier::Client.new(api_key: "YOUR_COURIER_API_KEY").

The method is send_ (with a trailing underscore) because send is a reserved method in Ruby.

Authentication

Get your API key from in the Courier dashboard. Set it as an environment variable:

export COURIER_API_KEY="YOUR_COURIER_API_KEY"

The SDK reads it by default. To pass the key explicitly:

client = Courier::Client.new(api_key: "YOUR_COURIER_API_KEY")

Sending notifications

Design your notification in , then reference it by ID:

response = client.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { order_id: "10042", item_name: "Courier Hoodie" }
  }
)

Available resources

The SDK covers the full Courier API. Every method carries Yard docstrings.

Resource	Namespace	Description
Send	`client.send_`	Send messages to one or more recipients
Messages	`client.messages`	Retrieve status, history, and content of sent messages
Profiles	`client.profiles`	Create, update, and retrieve user profiles
Users	`client.users`	Manage preferences, tenants, and push tokens per user
Auth	`client.auth`	Issue JWT tokens for client-side SDK authentication
Lists	`client.lists`	Manage subscription lists and their subscribers
Audiences	`client.audiences`	Define and query audience segments
Tenants	`client.tenants`	Manage tenants for multi-tenant setups
Journeys	`client.journeys`	Invoke and cancel runs. Create, list, publish, and archive
Brands	`client.brands`	Manage brand settings (logos, colors, templates)
Notifications	`client.notifications`	List and inspect notification templates
Translations	`client.translations`	Workspace `.po` strings for the `{{t}}` helper

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: "sarah@acme-corp.com",
  phone_number: "+15551234567",
  name: "Sarah Bennett"
})

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

Issuing JWT tokens

Courier’s (React, JavaScript, mobile) authenticate users with a JWT your backend issues. covers the token flow, the scope strings, and token refresh. Use client.auth.issue_token:

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

puts result.token

Scope	Permission
`user_id:<id>`	Which user the token is for (required)
`inbox:read:messages`	Read inbox messages
`inbox:write:events`	Mark messages as read/archived
`read:preferences`	Read notification preferences
`write:preferences`	Update notification preferences
`write:user-tokens`	Register 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: "nt_01kx4h2jdafq8bk9aftxak4b40" })
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 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: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  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: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  request_options: { timeout: 5 }
)

Journeys

are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.

# Start a run (by journey ID or alias); the response includes run_id
response = client.journeys.invoke(
  "your-journey-id",
  user_id: "user_123",
  data: { order_id: "A-1042" }
)

# Cancel one run, or every run sharing a cancelation token
client.journeys.cancel(cancel_journey_request: { run_id: response.run_id })
# client.journeys.cancel(cancel_journey_request: { cancelation_token: "order-A-1042" })

cancel takes exactly one of run_id or cancelation_token (spelled with one “l”). Build and manage journeys from code with create, list, publish, and archive. See .

More operations

A few more resources from the full :

Resource	Method	Use case
User preferences	`client.users.preferences.retrieve(user_id)`	Fetch a user’s notification preferences for your
Cancel a message	`client.messages.cancel(message_id)`	Cancel a delayed or queued message before delivery
Push tokens	`client.users.tokens.add_single(token, user_id:, provider_key: :"firebase-fcm")`	Register a device push token for , , , or

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.

Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the Idempotency-Key header for you. covers the scoping rule and the replay window.

response = courier.send_.message(
  message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  idempotency_key: "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91"
)

Get started

Server

Client

Courier Ruby SDK

Installation

Quick start

Authentication

Sending notifications

Available resources

Common operations

Checking message status

Managing user profiles

Issuing JWT tokens

Configuration

Error handling

Retries

Timeouts

Journeys

More operations

API Reference

Send API

Quickstart

GitHub

Idempotent sends

​Installation

​Quick start

​Authentication

​Sending notifications

​Available resources

​Common operations

​Checking message status

​Managing user profiles

​Issuing JWT tokens

​Configuration

​Error handling

​Retries

​Timeouts

​Journeys

​More operations

API Reference

Send API

Quickstart

GitHub

​Idempotent sends

Installation

Quick start

Authentication

Sending notifications

Available resources

Common operations

Checking message status

Managing user profiles

Issuing JWT tokens

Configuration

Error handling

Retries

Timeouts

Journeys

More operations

Idempotent sends