Migrate from Novu

This guide helps you plan and execute a migration from Novu 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 Novu Concepts to Courier

Novu	Courier
Workflows	Templates + Journeys
Subscribers	Users / Profiles
Topics	Subscription Topics
Integrations	Integrations
Digest	Batch + Digest nodes
Delay	Delay node
Preferences	Preferences
Inbox	Inbox
Tenants	Tenants

Workflows, Templates, and Journeys

Novu workflows combine notification content, channel routing, and orchestration logic (digest, delay, conditions) into a single resource. Courier splits these into two independent pieces, 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.

Novu Step Type	Courier Equivalent
Channel step (email, SMS, push, chat)	Send node (references a template)
Digest step	Batch node (window-based) or Digest node (schedule-based)
Delay step	Delay node
Custom step	Fetch data node or branch logic

A journey starts from a trigger: an API invoke, an inbound webhook, a Segment event, or a user joining an audience. Build journeys visually in the UI or define them through the Journeys API.

Subscribers and Users

Novu subscribers are the equivalent of Courier profiles. Both store recipient data: email, phone, push tokens, locale, and custom properties. Courier profiles accept nested JSON natively, so structured data like account tiers, team roles, or feature flags fits naturally. You can create profiles ahead of time through the API, or identify users inline at send time. Pass a user_id that doesn’t exist yet and Courier creates the profile on the fly.

Topics and Subscription Topics

Novu topics group subscribers for bulk notification delivery. In Courier, the closest equivalent depends on your use case:

For notification categories (letting users opt in/out of types of notifications): use Subscription Topics within Preferences
For bulk delivery to groups: use Lists or Audiences

Integrations

Novu and Courier both call provider connections “integrations.” Courier supports 50+ providers across email, SMS, push, chat, and webhooks. You can wire up multiple providers for the same channel type, and Courier fails over between them automatically. If your primary email provider goes down, traffic shifts to the backup without any code changes.

Digest and Delay

Courier’s Batch node covers what Novu’s digest step does with a time window: collect matching events, then release them as a single aggregated payload for one summary notification. Your template gets access to the full list of collected events for rendering rich summaries. For summaries that release on a fixed schedule the user controls (a daily activity email, a weekly report), use the Digest node instead. Delay works the same way as Novu’s delay step; specify a duration and the journey pauses before continuing to the next node.

Preferences

Novu’s preference system supports global and per-workflow channel controls. Courier Preferences support the same hierarchy (global, per-topic, per-channel) and enforce them automatically at send time. On top of the API, Courier ships a hosted preference page you can deploy in minutes and embeddable React components for in-app preference centers. No custom UI work required.

In-App Notifications

Novu’s Inbox component provides in-app notifications. Courier Inbox serves the same purpose with drop-in components for React, iOS, Android, and vanilla JS. Courier Inbox runs on the same delivery pipeline as email, push, and SMS; there’s no separate service to manage. Out of the box you get read/unread state, archiving, per-user history, toast notifications, and tab-based organization.

Tenants

Tenants in Courier work much like tenants in Novu. You scope branding, preference defaults, and notification feeds to individual customer organizations. Pass a tenant_id at send time and Courier applies per-tenant branding and preferences automatically.

Why Courier

Fully managed infrastructure. No self-hosting to maintain, no bridge endpoints to deploy. Courier handles orchestration, delivery, retries, and scaling.
Content and logic stay separate. Templates and journeys are independent resources. 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 Novu (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 Novu’s inbox component, enable Courier Inbox; no external provider needed.

Recreate templates

Novu workflows contain inline content per channel step. In Courier, extract the content into templates in Design Studio:

Create a new template for each notification type
Add content blocks for each channel (email body, SMS text, push title/body, etc.)
Use {{variable}} syntax for dynamic data; both platforms use the same Handlebars-style approach
Publish the template to make it available for sending

Recreate workflows as journeys

If your Novu workflows include digest, delay, or conditional logic, recreate them in Journeys. You can build journeys visually in the UI or define them programmatically via the Journeys API.For simple notification types that don’t need orchestration (no delays, no digests), you can skip journeys entirely and send directly via the Send API.

Migrate subscriber data

Create user profiles in Courier with the same identifiers you use in Novu. 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 Novu’s subscriber preferences, recreate your structure in Courier:

Define subscription topics that map to your Novu workflow categories
Configure default channel routing per topic
Migrate subscriber 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 trigger calls

Replace Novu’s workflow trigger calls with Courier’s Send API:

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": "order-confirmation",
      "data": {
        "order_id": "ORD-456",
        "total": "$79.99"
      }
    }
  }'

import Courier from "@trycourier/courier";

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

await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "order-confirmation",
    data: {
      order_id: "ORD-456",
      total: "$79.99",
    },
  },
});

from courier import Courier

client = Courier(api_key="YOUR_API_KEY")

client.send.message(
  message={
    "to": {"user_id": "user_123"},
    "template": "order-confirmation",
    "data": {
      "order_id": "ORD-456",
      "total": "$79.99",
    },
  }
)

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 Novu 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 Novu to Courier.

Read first:
- https://www.courier.com/docs/tutorials/migrate/from-novu
  (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]
- Novu 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 Novu API to list every active workflow. For
   each, record: identifier, trigger, the channel steps it contains,
   and any digest or delay steps and their windows.

2. Classify each as transactional (an action in our product must
   produce it) or marketing/lifecycle. Flag single-step workflows,
   since those become a plain Courier template with no journey.

3. Find the send sites. Grep the codebase for Novu
   POST /v1/events/trigger calls and map each to its workflow
   identifier. Note any that target a topic rather than a subscriber.

   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
   Novu 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. Digest steps become digest or batch nodes,
   delay steps become delay nodes, conditions become branch nodes.
   Carry the digest window across exactly; do not round it.

6. Preferences, topics, and tenants. Map Novu subscriber preferences
   to Courier subscription topics, Novu topics to Courier lists, and
   Novu tenants to Courier tenants.

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 Novu. That is my call.
- If something in Novu has no Courier equivalent, say so in your
  report rather than approximating it.

Check the digest windows in step 5 closely. They are the one setting where an off-by-an-hour rebuild is invisible in testing and obvious to users the first week in production.

API Mapping

Operation	Novu	Courier
Send a notification	`POST /v1/events/trigger`	`POST /send`
Create/update a subscriber	`PUT /v1/subscribers/:id`	`PUT /profiles/:id`
Get a subscriber	`GET /v1/subscribers/:id`	`GET /profiles/:id`
Set preferences	`PATCH /v2/subscribers/:id/preferences`	`PUT /users/:id/preferences/:topic`
Get message status	`GET /v1/messages/:id`	`GET /messages/:id`
List messages	`GET /v1/messages`	`GET /messages`
Manage topics	`POST /v1/topics`	`PUT /lists/:id`
Bulk operations	Bulk trigger	`POST /bulk`

Send Messages

Design Messages

User Journeys

Inbox & Preferences

Deploying and Debugging

Migrate to Courier

Migrate from Novu

Mapping Novu Concepts to Courier

Workflows, Templates, and Journeys

Subscribers and Users

Topics and Subscription Topics

Integrations

Digest and Delay

Preferences

In-App Notifications

Tenants

Why Courier

Migration Steps

Migrating with an AI Agent

API Mapping

​Mapping Novu Concepts to Courier

​Workflows, Templates, and Journeys

​Subscribers and Users

​Topics and Subscription Topics

​Integrations

​Digest and Delay

​Preferences

​In-App Notifications

​Tenants

​Why Courier

​Migration Steps

​Migrating with an AI Agent

​API Mapping

Mapping Novu Concepts to Courier

Workflows, Templates, and Journeys

Subscribers and Users

Topics and Subscription Topics

Integrations

Digest and Delay

Preferences

In-App Notifications

Tenants

Why Courier

Migration Steps

Migrating with an AI Agent

API Mapping