Migrate from OneSignal

This guide maps OneSignal concepts to Courier and gives you a step-by-step migration plan.

Map OneSignal concepts to Courier

OneSignal	Courier
Apps
Segments
Templates
Journeys
Subscriptions	Channel tokens on
Users / Aliases
Tags	Custom properties on profiles +
Outcomes	+
In-App Messages

Apps and workspaces

OneSignal apps map to Courier . Each workspace has its own integrations, templates, and user profiles, plus separate Test and Production .

Segments and audiences

OneSignal segments filter on user attributes, activity, and tags to build dynamic groups. Courier work the same way. Define filter rules on profile attributes and Courier keeps membership current as profiles change. For static groups like mailing lists or beta testers, use .

Templates

OneSignal templates are reusable message blueprints for push, email, and SMS. One Courier holds content for every channel: email, SMS, push, chat, and inbox. uses drag-and-drop content blocks. JSON is the code-first path. Both support Handlebars personalization, channel-specific overrides, and . OneSignal uses Liquid syntax. Courier uses Handlebars. Both have conditionals, loops, and variable interpolation, with different syntax.

Journeys

OneSignal Journeys are automated multi-step message flows. Courier do the same, with , , , , and .

Journey Step	Courier Equivalent
Send message	(references a template)
Wait
Yes/No branch
Multi-split branch	with multiple paths

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

Users, subscriptions, and profiles

OneSignal separates users (identified by aliases) from subscriptions (individual devices, email addresses, phone numbers). One Courier per user holds all of it: email, phone, push tokens, and custom properties. Profiles accept nested JSON, so account tiers, team roles, or feature flags fit as they are. Create profiles ahead of time through the API, or identify users inline at send time.

Tags and preferences

OneSignal tags are key-value pairs used for both targeting and preference management. Courier splits these in two:

Custom profile properties: any attribute on a user profile, for targeting and personalization
: opt-in and opt-out by channel, category, or topic, enforced at send time

In-app messages and Inbox

OneSignal’s in-app messages are modal overlays triggered by user activity. Courier is a persistent in-app notification center with drop-in components for , , , and . Inbox runs on the same delivery pipeline as email, push, and SMS, with no separate provider to configure. You get read/unread state, archiving, per-user history, , and .

Outcomes and analytics

OneSignal Outcomes track conversion events tied to notifications. Courier gives you (per-message timeline from API request to provider delivery) and (aggregate delivery and engagement metrics). To pipe events into your own analytics, configure .

Why Courier

Multi-channel. Courier treats email, SMS, push, chat, webhooks, and in-app as equal channels with one orchestration layer. You’re not bolting non-push channels onto a push-first platform.
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.
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. Ship a user-facing preference center with a single config, or embed React components in your app. No custom UI required.
The providers you already use. Email, SMS, push, chat, webhooks, CDPs, and observability tools. Switch providers without changing your send code.
Full delivery observability. track every message from API request to provider delivery with a detailed timeline, error details, and rendered content inspection.

Migrate step by step

Create your Courier workspace

and create a workspace. The Test and Production have independent API keys, so you can migrate without touching live traffic.

Configure integrations

Go to Integrations in your Courier dashboard and connect a provider for each channel you use in OneSignal. If you send push via FCM and APNs, configure both. Connect your email and SMS providers (SendGrid, Twilio, etc.). Multiple providers on one channel gives you .For in-app notifications, enable . No external provider needed.

Recreate templates

OneSignal templates are per-channel. In Courier, a single 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 ({{variable}}). The data comes from the send request’s data field
Publish the template so you can send it

Migrate user data

Create Courier profiles that consolidate your OneSignal user and subscription data. Use the , or identify users inline at send time.

{
  "user_id": "user_123",
  "profile": {
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "firebaseToken": "fcm_device_token_here",
    "custom": {
      "name": "Sarah Bennett",
      "plan": "enterprise"
    }
  }
}

Set up preferences

If you use OneSignal tags for opt-in and opt-out, rebuild that structure with Courier :

Define for each notification category
Configure default channel routing per topic
Migrate user preference selections via the

Courier ships a you can deploy immediately, or to embed preferences in your app.

Update your send calls

Replace OneSignal’s Create Notification API calls with Courier’s :

const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: {
      order_id: 'ORD-456',
      total: 79.99,
    },
  },
});

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

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "order_id": "ORD-456",
        "total": 79.99
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { order_id: "ORD-456", total: 79.99 }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"order_id": "ORD-456",
			"total": 79.99,
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "order_id", "ORD-456",
            "total", 79.99)))
        .build())
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_id' => 'ORD-456', 'total' => 79.99],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_id", JsonSerializer.SerializeToElement("ORD-456") },
            { "total", JsonSerializer.SerializeToElement(79.99) },
        },
    },
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"order_id":"ORD-456","total":79.99}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with the order details.

Courier applies routing, preferences, and failover from your template and workspace configuration. For multi-channel sends, set the routing field:

const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
        "email",
        "sms",
      ],
    },
  },
});

response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "push",
                "email",
                "sms",
            ],
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "push",
          "email",
          "sms"
        ]
      }
    }
  }'

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

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
				{OfString: courier.String("email")},
				{OfString: courier.String("sms")},
			},
			Method: "single",
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .addChannel("email")
            .addChannel("sms")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'push',
        'email',
        'sms',
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push", "email", "sms"], Method = Send::Method.Single },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push", "email", "sms"]}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 over email and push.

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

Recreate journeys

If you use OneSignal Journeys, recreate them in Courier , visually or through the .For notifications that need no orchestration, skip journeys and send directly via the Send API.

Test and cut over

Send test messages in your Test environment and verify delivery in
Check that preferences, routing, and template rendering match your OneSignal setup
Switch your production code to Courier’s Production API key
Monitor and for delivery confirmation

Migrate with an AI agent

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

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.
gives the agent direct access to your workspace, so it can create templates, build journeys, upsert users, and read send logs. See 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 OneSignal to Courier.

Read first:
- https://www.courier.com/docs/guides/migrate/from-onesignal
  (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]
- OneSignal 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 OneSignal API to list every template, journey,
   and segment in each app. For each template record its channels; for
   each journey record its trigger, steps, and target segment.

2. Classify each as:
   - transactional (an action in our product must produce it)
   - marketing (campaign or lifecycle)
   - in-app messages (these are a separate surface, see the guide)

3. Find the send sites. Grep the codebase for OneSignal
   POST /notifications calls. Note which ones send inline content and
   which reference a template_id, and which target segments or filters
   rather than an external_id.

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

4. Transactional first. For each one: create the Courier template with
   the channels it needs, then rewrite the call site to a Courier /send
   that names the template and passes data. Recipients addressed by
   external_id become a Courier user_id. Leave the OneSignal call in
   place behind a flag so we can run both and compare.

5. Journeys. Recreate each OneSignal journey through the Courier
   journeys API. Waits become delay nodes, branches become branch
   nodes, message steps become send nodes.

6. Segments and tags. Convert segments to Courier audiences built on
   profile attributes, and map the tags you use for opt-out into
   Courier subscription topics rather than leaving them as attributes.

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

Step 6 deserves a careful pass. OneSignal data tags cover both segmentation and opt-out, and only the opt-out tags should become subscription topics. Anything that gates whether a user may be contacted belongs in Preferences, where Courier enforces it at send time.

Map the API

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

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Migrate from OneSignal

Map OneSignal concepts to Courier

Apps and workspaces

Segments and audiences

Templates

Journeys

Users, subscriptions, and profiles

Tags and preferences

In-app messages and Inbox

Outcomes and analytics

Why Courier

Migrate step by step

Migrate with an AI agent

Map the API

​Map OneSignal concepts to Courier

​Apps and workspaces

​Segments and audiences

​Templates

​Journeys

​Users, subscriptions, and profiles

​Tags and preferences

​In-app messages and Inbox

​Outcomes and analytics

​Why Courier

​Migrate step by step

​Migrate with an AI agent

​Map the API

Map OneSignal concepts to Courier

Apps and workspaces

Segments and audiences

Templates

Journeys

Users, subscriptions, and profiles

Tags and preferences

In-app messages and Inbox

Outcomes and analytics

Why Courier

Migrate step by step

Migrate with an AI agent

Map the API