Migrate from OneSignal to Courier

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

OneSignal	Courier
Apps	Workspaces
Segments	Audiences
Templates	Templates
Journeys	Automations
Subscriptions	Channel tokens on User Profiles
Users / Aliases	Users / Profiles
Tags	Custom properties on profiles + Preferences
Outcomes	Analytics + Message Logs
In-App Messages	Inbox

Apps and Workspaces

OneSignal apps map to Courier workspaces. Each workspace has its own integrations, templates, and user profiles. Courier gives you separate Test and Production environments within a workspace, so you can develop safely without affecting live traffic.

Segments and Audiences

OneSignal segments use filters on user attributes, activity, and tags to create dynamic groups. Courier Audiences work similarly: define filter rules on profile attributes and Courier keeps membership current as profiles change. For static subscriber groups (mailing lists, beta testers, etc.), Courier also supports Lists.

Templates

OneSignal templates are reusable message blueprints for push, email, and SMS. Courier templates take a unified approach: a single resource holds content for every channel (email, SMS, push, chat, inbox), so you design all channel variants in one place. The visual Designer uses drag-and-drop content blocks, and there’s a code-first path through Elemental JSON if you prefer to define content programmatically. Both support {{variable}} Handlebars-style personalization, channel-specific overrides, and localization. OneSignal uses Liquid syntax for templating; Courier uses Handlebars. The concepts are similar (conditionals, loops, variable interpolation), just with different syntax.

Journeys and Automations

OneSignal Journeys are automated multi-step message flows. Courier Automations serve the same purpose with delays, conditions, branching, digests, and cancellation.

Journey Step	Courier Equivalent
Send message	Send node (references a template)
Wait	Delay node
Yes/No branch	Condition node
Multi-split branch	Multiple condition nodes

Build automations visually in the Automations Designer or define them through the Automations API.

Users, Subscriptions, and Profiles

OneSignal separates users (identified by aliases) from subscriptions (individual devices, email addresses, phone numbers). Courier consolidates these into a single profile per user that stores all contact information: email, phone, push tokens, and custom properties. 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.

Tags and Preferences

OneSignal tags are key-value pairs on users used for both targeting and preference management. In Courier, these split into two features:

Custom profile properties: Store arbitrary attributes on user profiles for targeting and personalization
Preferences: A dedicated system for notification opt-in/opt-out by channel, category, or specific topic, enforced automatically at send time

Courier also ships a hosted preference page you can deploy in minutes and embeddable React components for building a preference center directly into your app.

In-App Messages and Inbox

OneSignal’s in-app messages are modal overlays triggered by user activity. Courier Inbox is a persistent in-app notification center with drop-in components for React, iOS, Android, and vanilla JS. Inbox runs on the same delivery pipeline as email, push, and SMS; there’s no separate provider to configure. Out of the box you get read/unread state, archiving, per-user history, toast notifications, and tab-based organization.

Outcomes and Analytics

OneSignal Outcomes track conversion events tied to notifications. Courier provides delivery observability through Message Logs (per-message timeline from API request to provider delivery) and Analytics (aggregate delivery and engagement metrics). For piping events to your own analytics, configure Outbound Webhooks.

Why Courier

Truly multi-channel. Courier treats email, SMS, push, chat, webhooks, and in-app as equal channels with unified orchestration. You’re not bolting non-push channels onto a push-first platform.
Content and logic stay separate. Templates and automations are independent resources. Your product team updates copy in the Designer while engineers tune workflow timing; neither blocks the other.
Visual template designer. Build email, SMS, push, and chat content with drag-and-drop blocks. Preview across channels, personalize with variables, and publish without deploying code.
Automatic failover. Configure multiple providers per channel and Courier fails over automatically. If your primary email provider goes down, traffic shifts to the backup without code changes.
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.
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 delivery providers for each channel you use in OneSignal. If you send push via FCM and APNs, configure both. For email and SMS, connect your providers (SendGrid, Twilio, etc.). You can configure multiple providers per channel for failover.For in-app notifications, enable Courier Inbox; no external provider needed.

Recreate templates

OneSignal templates are per-channel. In Courier, a single template holds content for all channels:

Create a new template for each notification type
Add content blocks for each channel (email body, SMS text, push title/body, etc.)
Convert Liquid variables to Handlebars syntax ({{variable}}); the data comes from the send request’s data field
Publish the template to make it available for sending

Migrate user data

Create user profiles in Courier that consolidate your OneSignal user and subscription data. 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",
    "firebaseToken": "fcm_device_token_here",
    "custom": {
      "name": "Jane Doe",
      "plan": "enterprise"
    }
  }
}

For bulk migration, use the Bulk API to upsert users in batches. Map OneSignal external_id to Courier user_id for a seamless transition.

Set up preferences

If you use OneSignal tags for opt-in/opt-out management, recreate that structure using Courier Preferences:

Define subscription topics for each notification category
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 OneSignal’s Create Notification API 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"
      }
    }
  }'

Courier handles routing, preferences, and failover automatically based on your template and workspace configuration. For multi-channel sends, set the routing field:

{
  "message": {
    "to": { "user_id": "user_123" },
    "template": "order-confirmation",
    "routing": {
      "method": "single",
      "channels": ["push", "email", "sms"]
    }
  }
}

This tries push first, then email, then SMS; the first successful delivery wins.

Recreate automations

If you use OneSignal Journeys, recreate them in Courier Automations. Build visually in the Automations Designer or define them via the Automations API.For simple notification types that don’t need orchestration, you can skip automations entirely and send directly via the Send API.

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 OneSignal setup
Switch your production code to use Courier’s Production API key
Monitor Message Logs and Analytics for delivery confirmation

API Mapping

Operation	OneSignal	Courier
Send a notification	`POST /notifications`	`POST /send`
Create/update a user	`POST /apps/:id/users`	`PUT /profiles/:id`
Get a user	`GET /apps/:id/users/by/external_id/:id`	`GET /profiles/:id`
Add a subscription	`POST /apps/:id/users/by/external_id/:id/subscriptions`	Push tokens on `PUT /profiles/:id`
Manage segments	`POST /apps/:id/segments`	`PUT /audiences/:id`
Get message status	`GET /notifications/:id`	`GET /messages/:id`
Bulk operations	`POST /notifications` (with `include_aliases`)	`POST /bulk`
Create a template	`POST /templates`	Template Designer or Elemental API

What’s Next

Quickstart

Send your first notification in under 2 minutes

Template Designer

Build notification content with the visual editor

Automations

Add delays, conditions, digests, and branching to your notification workflows

Preferences

Let users control which notifications they receive

Send

Design

Automate

Inbox & Preferences

Ops

Migrate to Courier

Migrate from OneSignal to Courier

Mapping OneSignal Concepts to Courier

Apps and Workspaces

Segments and Audiences

Templates

Journeys and Automations

Users, Subscriptions, and Profiles

Tags and Preferences

In-App Messages and Inbox

Outcomes and Analytics

Why Courier

Migration Steps

API Mapping

What’s Next

Quickstart

Template Designer

Automations

Preferences

Send

Design

Automate

Inbox & Preferences

Ops

Migrate to Courier

​Mapping OneSignal Concepts to Courier

​Apps and Workspaces

​Segments and Audiences

​Templates

​Journeys and Automations

​Users, Subscriptions, and Profiles

​Tags and Preferences

​In-App Messages and Inbox

​Outcomes and Analytics

​Why Courier

​Migration Steps

​API Mapping

​What’s Next

Quickstart

Template Designer

Automations

Preferences

Mapping OneSignal Concepts to Courier

Apps and Workspaces

Segments and Audiences

Templates

Journeys and Automations

Users, Subscriptions, and Profiles

Tags and Preferences

In-App Messages and Inbox

Outcomes and Analytics

Why Courier

Migration Steps

API Mapping

What’s Next