Migrate from Knock

This guide helps you plan and execute a migration from Knock to Courier. It covers how the two platforms compare, where Courier gives you more flexibility, and a concrete step-by-step plan for moving everything over.

Mapping Knock Concepts to Courier

Knock	Courier
Channels	Integrations
Workflows	Templates + Journeys
Recipients / Users	Users / Profiles
Objects	`data` on send
Preferences	Preferences
Tenants	Tenants
Feeds (in-app)	Inbox
Commits	Publish (draft/live)

Integrations

Knock Channels map to Courier Integrations, where you configure delivery providers like SendGrid, Twilio, and FCM. You can wire up multiple providers for the same channel type and Courier automatically fails over between them; if your primary email provider is down, the backup kicks in without any code changes on your side. With 50+ supported providers across email, SMS, push, chat, and webhooks, you’re unlikely to hit a gap. And because provider config lives in the dashboard, swapping or adding a provider never requires a deploy.

Templates and Journeys

Knock bundles notification content and delivery logic into a single Workflow. Courier splits these into two independent resources, and this is the most meaningful architectural difference between the platforms. Templates own the content layer. You design them visually in Design Studio (drag-and-drop blocks for email, SMS, push, and chat) or define them in code with Elemental JSON. Either way, your product team can ship copy changes without an engineering cycle. Journeys own the orchestration layer: delays, branching, batching, digests, and cancellation. A journey’s send node references a template by ID, so the two evolve independently. A PM updates a welcome email while an engineer tunes the onboarding sequence, and they never step on each other. A journey starts from a trigger: an API invoke, an inbound webhook, a Segment event, or a user joining an audience. That covers the same entry points as Knock workflow triggers.

Users and Profiles

Courier profiles store everything about a recipient: email, phone, push tokens, and any custom properties you need for personalization. Profiles accept nested JSON, so structured data like feature flags, team roles, or subscription tiers fits naturally. You can create profiles ahead of time through the API, or identify users inline at send time. If you pass a user_id that doesn’t exist yet, Courier creates the profile on the fly.

Passing Context

Where Knock uses Objects as non-user entities that can receive notifications, Courier keeps things simpler: you pass arbitrary context through the data field on each send request. No need to create and manage separate entity types; any data your template needs for rendering just goes in data.

Preferences

Knock’s PreferenceSet maps to Courier Preferences, which let users opt out by channel, category, or specific notification topic. Courier enforces these automatically at send time; you don’t need conditional logic in your code. On top of the API, Courier ships a hosted preference page you can deploy in minutes and embeddable React components for building a preference center directly into your app. No custom UI work required.

Tenants

Tenants in Courier work much like Tenants in Knock. You scope branding, preference defaults, and notification feeds to individual customer organizations, workspaces, or accounts. Pass a tenant_id at send time and Courier applies per-tenant branding and preference defaults automatically. One difference: Courier stores branding attributes directly on the Tenant resource rather than as a separate Brands object.

In-App Notifications

Knock’s Feeds map to Courier Inbox, a real-time in-app notification center with drop-in components for React, iOS, Android, and vanilla JS. It runs on the same pipeline as your other channels, so there’s no extra provider to configure; enable it and start sending. Out of the box you get read/unread state, archiving, per-user history, and toast notifications.

Versioning

Knock uses a git-style commit model to version dashboard changes. Courier uses a simpler draft/published model. You edit templates and journeys in draft, preview them, and publish when ready. Published versions are immutable, so you always have a clear snapshot of what’s live.

Why Courier

Content and logic stay separate. Templates and journeys are independent. Your product team updates copy in Design Studio while engineers tune journey timing; neither blocks the other.
Design Studio. Build email, SMS, push, and chat content with drag-and-drop blocks. Preview across channels, personalize with variables, and publish without deploying code.
Built-in in-app channel. Courier Inbox works without a third-party provider. Drop in a React, iOS, or Android component and deliver in-app notifications on the same pipeline as email and push.
Automatic failover. Configure multiple providers per channel and Courier fails over automatically. If SendGrid goes down, your email still goes out through your backup provider.
Hosted preferences out of the box. Ship a user-facing preference center with a single config, or embed React components directly in your app. No custom UI required.
50+ integrations. Email, SMS, push, chat, webhooks, CDPs, and observability tools. Switch providers without changing your send code.
Full delivery observability. Message Logs track every message from API request to provider delivery with a detailed timeline, error details, and rendered content inspection.

Migration Steps

Create your Courier workspace

Sign up and create a workspace. Courier gives you separate Test and Production environments with independent API keys, so you can migrate safely without affecting live traffic.

Configure integrations

Go to Integrations in your Courier dashboard and connect the same providers you use in Knock (SendGrid, Twilio, FCM, etc.). Each provider maps to a channel type (email, SMS, push, chat). You can configure multiple providers per channel for failover.If you use Knock’s in-app feed, enable Courier Inbox; no external provider needed.

Recreate templates

Knock workflows combine content and logic. In Courier, start by recreating the content portion as templates in Design Studio:

Create a new template for each notification type
Add content blocks for each channel (email, SMS, push, etc.)
Use {{variable}} syntax for dynamic data; Courier supports the same Handlebars-style variables
Publish the template to make it available for sending

If your Knock workflows include orchestration logic (delays, conditions, batching), recreate that separately in Journeys.

Migrate user data

Create user profiles in Courier with the same identifiers you use in Knock. You can create profiles via the Profiles API or inline at send time.

{
  "user_id": "user_123",
  "profile": {
    "email": "user@example.com",
    "phone_number": "+15551234567",
    "custom": {
      "name": "Jane Doe",
      "plan": "enterprise"
    }
  }
}

For bulk migration, use the Bulk API to upsert users in batches.

Set up preferences

If you use Knock’s PreferenceSet, recreate your preference structure in Courier:

Define subscription topics that map to your Knock categories
Configure default channel routing per topic
Migrate user preference selections via the Preferences API

Courier also provides a hosted preference page you can deploy immediately, or React components for embedding preferences in your app.

Update your send calls

Replace Knock’s workflow trigger calls with Courier’s Send API. A basic send looks like this:

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "welcome-email",
      "data": {
        "name": "Jane Doe",
        "action_url": "https://app.example.com"
      }
    }
  }'

import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: "YOUR_API_KEY" });

await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "welcome-email",
    data: {
      name: "Jane Doe",
      action_url: "https://app.example.com",
    },
  },
});

from courier import Courier

client = Courier(api_key="YOUR_API_KEY")

client.send.message(
  message={
    "to": {"user_id": "user_123"},
    "template": "welcome-email",
    "data": {
      "name": "Jane Doe",
      "action_url": "https://app.example.com",
    },
  }
)

Courier handles routing, preferences, and failover automatically based on your template and workspace configuration.

Test and cut over

Send test messages in your Test environment and verify delivery in Message Logs
Validate that preferences, routing, and template rendering match your Knock setup
Switch your production code to use Courier’s Production API key
Monitor Message Logs and Analytics for delivery confirmation

Migrating with an AI Agent

Most of this migration is mechanical: read a workflow definition, create the equivalent Courier template, rewrite the call site. That suits a coding agent well. Three things to set up first:

Courier Skills teaches the agent Courier’s real APIs and patterns so it stops guessing at endpoints:
npx skills add trycourier/courier-skills
In Claude Code you can install it as a plugin instead, which self-updates and ships the Courier docs MCP server.
Courier’s MCP server gives the agent direct access to your workspace, so it can create templates, build journeys, upsert users, and read send logs as it works. See Build with AI for setup in Claude Code, Cursor, Codex, and VS Code.
Docs for agents. Point it at llms-full.txt when it needs API detail beyond this page.

Then start it with a prompt like this one. Fill in the bracketed parts.

Help me migrate our notifications from Knock to Courier.

Read first:
- https://www.courier.com/docs/tutorials/migrate/from-knock
  (concept mapping and the migration steps you should follow)
- https://www.courier.com/docs/llms-full.txt
  (full Courier docs, for API detail as you need it)

Our setup:
- Codebase: [path]
- Knock API credentials: [env var]
- Courier: connected through the Courier MCP server

Work in this order. Stop after step 3 and wait for my review
before you create anything in Courier.

0. Setup. Install Courier Skills so you build against Courier's real
   APIs and patterns rather than guessing:
   npx skills add trycourier/courier-skills
   Then confirm the Courier MCP server is connected. If either one is
   missing, stop and tell me before going further.

1. Inventory. Use the Knock API to list every committed workflow.
   For each, record: key, trigger, channel steps, any batch, delay,
   or conditional steps, and the preference category it respects.

2. Classify each as transactional (an action in our product must
   produce it) or marketing/lifecycle. Note which ones are a single
   send with no orchestration, since those become a plain Courier
   template and need no journey at all.

3. Find the send sites. Grep the codebase for Knock
   POST /workflows/:key/trigger calls and map each to its workflow.
   Note where recipients are passed as a list, since those become
   either a Courier list send or a bulk job.

   Report the inventory, the classification, and the send-site list.
   Then wait.

4. Single-step workflows first. For each one: create the Courier
   template with the channels it needs, then rewrite the trigger call
   to a Courier /send naming the template and passing data. Leave the
   Knock call in place behind a flag so we can run both and compare.

5. Multi-step workflows become journeys. Recreate them through the
   Courier journeys API. Delay steps become delay nodes, batch steps
   become batch or digest nodes, conditions become branch nodes.

6. Preferences and tenants. Map Knock preference categories to Courier
   subscription topics, and Knock tenants to Courier tenants. Import
   the PreferenceSet state before any marketing send.

Rules:
- Never send to a real user. Use a test profile in the Test
  environment for every verification send.
- Never pause, disable, or delete anything in Knock. That is my call.
- If something in Knock has no Courier equivalent, say so in your
  report rather than approximating it.

Step 2 is where most of the value is. Knock models every notification as a workflow, so a good portion of them are single-step sends that do not need a Courier journey. Sorting those out first keeps the migration much smaller than a one-to-one rebuild.

API Mapping

Operation	Knock	Courier
Send a notification	`POST /workflows/:key/trigger`	`POST /send`
Create/update a user	`PUT /users/:id`	`PUT /profiles/:id`
Get a user	`GET /users/:id`	`GET /profiles/:id`
Set user preferences	`PUT /users/:id/preferences`	`PUT /users/:id/preferences/:topic`
Get message status	`GET /messages/:id`	`GET /messages/:id`
List messages	`GET /messages`	`GET /messages`
Bulk send	`POST /workflows/:key/trigger` (with recipients array)	`POST /bulk`
Create/update tenant	`PUT /tenants/:id`	`PUT /tenants/:id`

Send Messages

Design Messages

User Journeys

Inbox & Preferences

Deploying and Debugging

Migrate to Courier

Migrate from Knock

Mapping Knock Concepts to Courier

Integrations

Templates and Journeys

Users and Profiles

Passing Context

Preferences

Tenants

In-App Notifications

Versioning

Why Courier

Migration Steps

Migrating with an AI Agent

API Mapping

​Mapping Knock Concepts to Courier

​Integrations

​Templates and Journeys

​Users and Profiles

​Passing Context

​Preferences

​Tenants

​In-App Notifications

​Versioning

​Why Courier

​Migration Steps

​Migrating with an AI Agent

​API Mapping

Mapping Knock Concepts to Courier

Integrations

Templates and Journeys

Users and Profiles

Passing Context

Preferences

Tenants

In-App Notifications

Versioning

Why Courier

Migration Steps

Migrating with an AI Agent

API Mapping