- A Courier account. Start free.
- A Test API key from Settings → API Keys. Set it as
COURIER_API_KEY. - Ruby 3.2 or later.
- A user in Courier with an email or phone number. Step 2 creates one through the API.
1. Install the SDK
gem "trycourier" to your Gemfile and run bundle install. The gem is a typed client for the whole API, ships RBS and RBI definitions for Sorbet, and retries failed requests twice by default. It reads COURIER_API_KEY from the environment, so there is nothing to configure for the first send.
2. Create a user
Courier is built around users, not addresses. A user profile holds the email, phone number, push tokens, and chat handles for one person, plus their notification preferences. Once it exists, every send names the user and Courier works out where to reach them. Your code never handles a contact detail again.trycourier, but the file you require is courier. create merges into an existing profile and leaves any key you omit alone; courier.profiles.replace overwrites the whole profile instead.
3. Send a notification
A send names a template and a user, and passes the data specific to this event. The template lives in Design Studio, where it holds the content for every channel and the routing rules, so a copy change or a new channel never needs a deploy. The idempotency key means a retried request returns the original response instead of sending twice.send_ with a trailing underscore, because send is already a method on every Ruby object. The call returns a request_id. Open Message Logs and you will see the request, the channel Courier chose, the provider it used, and the delivery status as it updates.
4. Route across channels
Routing normally lives in the template, but a send can override it when the code knows something the template does not.single tries channels in order and stops at the first that delivers; all sends on every listed channel. The user’s preferences still apply on top, so a user who has opted out of SMS gets the email, and a user with no phone number on file does too.
method_, again because method is taken in Ruby. The SDK sends it over the wire as method.
5. Start a journey
Some notifications are sequences: a welcome email now, a reminder tomorrow if setup is not finished, a different path for team plans. A journey is that sequence built in a visual editor as steps that send, wait, branch on user data, or digest a burst of events into one message. You publish it once, and your code only has to start it. When the sequence changes, the editor changes; theinvoke call does not.
retrieve returns a wrapper, so the run itself is on .run, and its status is a plain string rather than an enum because Courier has added values to it before.
Confirm delivery
A request fans out to one message per recipient and channel, and each message moves through its own lifecycle: enqueued, sent to the provider, delivered, opened, clicked. Look a message up by ID to read where it is.:CANCELED, :DELAYED, :DIGESTED, :FILTERED, :ROUTED, :THROTTLED, :UNMAPPED, and :UNROUTABLE. For production, subscribe to an outbound webhook instead of polling: Courier posts each status change to your endpoint as it happens.
Next steps
- Working example: this guide as a runnable project.
- Add an in-app inbox with the React or web component SDK.
- Let users set preferences.
- Send API reference: every field.
- Ruby SDK reference.