Courier

# Courier > Courier is infrastructure for product-to-user communication. Send notifications across email, SMS, push, chat, and in-app channels through one API call. ## About - **Type**: APIService - **Category**: Notifications / Messaging Infrastructure - **Language**: English - **Audience**: Developers, SaaS platforms, product engineers - **Pricing**: Free tier available; usage-based pricing - **Last Updated**: 2026-05 - **Base URL**: `https://api.courier.com` - **Auth**: `Authorization: Bearer <YOUR_API_KEY>` (workspace-scoped; Test and Production keys are separate) - **API Version**: V2 (no version header required; latest is default) ## Core Data Model ``` message → routing (single | all) → channel (email, sms, push, inbox, chat) → provider (SendGrid, Twilio, FCM, etc.) ``` A **message** targets one or more **recipients** (user_id, email, phone_number, list_id, or audience_id). The **routing** object controls whether delivery fans out to all channels in parallel (`method: "all"`) or tries them in order as a fallback chain (`method: "single"`). Each **channel** is fulfilled by a configured **provider**. ## Agent Routing (which API to use) | Intent | Endpoint | Notes | |--------|----------|-------| | One-off send | `POST /send` | Single or multi-recipient | | Inline multi-step workflow | `POST /automations/invoke` (ad-hoc steps) | Define steps inline; no saved template needed | | Saved automation | `POST /automations/{id}/invoke` | Trigger a pre-built automation template | | Visual/long-running flows | `POST /journeys/{id}/invoke` | Journeys API; create via `POST /journeys` | | Many users, one message | Bulk API (3 steps) | `POST /bulk` → add users → run | | Dynamic segment | Audiences (`audience_id` in send) | Filter-based, auto-updating membership | | Static group | Lists (`list_id` in send) | Manual subscribe/unsubscribe | ## Key Concepts - **Recipient types**: `user_id` (stored profile), `email` / `phone_number` (inline), `list_id` (subscriber group), `audience_id` (dynamic segment) - **Inline vs template**: Send with `message.content` for inline content or `message.template` for a dashboard-designed notification - **Routing method**: `"single"` = fallback chain (try first channel, then next on failure); `"all"` = parallel delivery to every channel - **Profile merge vs replace**: `POST /profiles/{id}` merges (PATCH semantics); `PUT /profiles/{id}` replaces the entire profile - **Environments**: Test and Production share a workspace but use different API keys; templates must be published and migrated separately - **Tenants**: `tenant_id` in message context sets multi-tenant scope; affects brand, preferences, and routing defaults - **Preferences**: Users opt in/out per subscription topic; Courier enforces at send time automatically - **Idempotency**: Include an `Idempotency-Key` header on transactional sends (OTP, order confirmations, billing) to prevent duplicates ## Critical Gotchas - `PUT /profiles/{id}` is a **full replacement**; any fields not included are deleted. Use `POST` (merge) for partial updates. - Bulk sending is a 3-step flow: create job → add users → run job. You cannot send in a single call. - `routing.method: "all"` sends to **every** channel simultaneously. Most use cases want `"single"` (fallback chain). - The `requestId` returned by `/send` is a single ID for single-recipient sends but a `requestId` per recipient for multi-recipient. - Templates exist in draft until published. Sending with a template ID uses the last published version. - Brand creation requires `settings` (the API returns 400 without it). Minimal valid: `{ "name": "X", "settings": { "colors": { "primary": "#000", "secondary": "#fff" } } }`. - List subscription objects use `recipientId` (camelCase), not `recipient_id`. - Automation cancellation uses `cancelation_token` (one "l") and a second ad-hoc invoke with `action: "cancel"`. There is no separate `/cancel` endpoint. - Subscription topics must exist before assigning as ten […gekürzt]