Skip to content

AGENTS.md

Latest commit

 

History

History
53 lines (39 loc) · 2.2 KB

AGENTS.md

File metadata and controls

53 lines (39 loc) · 2.2 KB

Courier Ruby SDK

Courier is a notifications API for sending messages across email, SMS, push, in-app inbox, Slack, and WhatsApp from a single API call.

Setup

require "courier"

courier = Courier::Client.new # reads COURIER_API_KEY from env

Core pattern

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "TEMPLATE_ID",
    data: { order_id: "456" },
    routing: { method: "single", channels: ["email", "sms"] }
  }
)

puts response.requestId

Note: the method is send_ (with trailing underscore) because send is a reserved Ruby method.

Key rules

  • Use routing.method: "single" (fallback chain) unless the user explicitly asks for parallel delivery ("all").
  • Use courier.profiles.create for partial profile updates (it merges). Use courier.profiles.replace only when fully replacing all profile data.
  • Test and production use different API keys from the same workspace. Always confirm which environment before sending.
  • For transactional sends (OTP, orders, billing), pass an Idempotency-Key header via request_options: { extra_headers: { "Idempotency-Key" => value } } to prevent duplicates.
  • Bulk sends are a 3-step flow: courier.bulk.create_job → courier.bulk.add_users → courier.bulk.run_job.
  • requestId from a single-recipient send doubles as the message_id. For multi-recipient sends, each recipient gets a unique message_id.

Concepts

  • template — notification template ID from the Courier dashboard
  • routing.method — "single" = try channels in order until one succeeds; "all" = send on every channel simultaneously
  • tenant_id — multi-tenant context; affects brand and preference defaults for the message
  • list_id — send to all subscribers of a named list
  • to: { email: } / to: { phone_number: } — ad-hoc recipient (no stored profile needed)
  • to: { user_id: } — registered user whose profile has channel addresses

More context