Build an onboarding sequence

Walk a new user through their first week with one Journey: welcome them, wait, then nudge only the people who stalled. A Journey is a graph that runs once per user. Each run carries that user’s data, so the whole sequence is one API call from your signup code.

What you will build

Prerequisites

A signup event from your app

Build the sequence

Create the Journey

Open , select New Journey, name it user-onboarding, and choose the API Invoke trigger so your signup code starts each run.

The New Journey dialog with a name field and four trigger options

Send the welcome message

Drop a send node on the canvas, pick the email channel, and select + Create to write the content inline. Reference the run’s data with variables such as {{first_name}}.Each send node owns one template scoped to this Journey, so onboarding content stays out of your workspace template list.

Wait three days

Drag a delay node after the send and set it to three days. The run parks there and resumes on its own, so you hold no timers in your code.A delay is measured from when the run reaches the node, not from when the Journey started.

Branch on whether they activated

Add a branch node after the delay and write a condition against the run’s data, for example data.has_activated. Wire the true path straight to an end, and the false path onward.The branch reads the data the run is carrying. To decide on something that changed during the three-day wait, add a fetch data node before the branch and call your own API for the current value.

Add the follow-ups

On the false path, add a send node with a tip message, another delay of four days, and a final nudge. Only users who never activated reach these nodes.

Set a cancelation token

In the journey’s settings, set the cancelation token to onboarding-{{profile.id}}. Courier interpolates it when each run starts, so every user’s run carries its own token and you can stop one user’s sequence without touching anyone else’s.A token that references a variable missing at run start leaves the run untagged. It is still cancelable by run ID, but not by token. covers how the shape of the token decides what it covers.

Publish

Select Publish to lock the draft as a version, then copy the Journey ID. New runs use the published version. Runs in flight finish on the version they started with.

Invoke it from your signup code

Call once per new user. The run picks up the cancelation token from the journey’s settings, so invoke carries only the user and the data the branch reads.

const journeysInvokeResponse = await client.journeys.invoke('user-onboarding', {
  user_id: 'user_123',
  data: { first_name: 'Sarah', has_activated: false },
});

journeys_invoke_response = client.journeys.invoke(
    template_id="user-onboarding",
    user_id="user_123",
    data={"first_name": "Sarah", "has_activated": False},
)

curl -X POST https://api.courier.com/journeys/user-onboarding/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-user_123" \
  -d '{
    "user_id": "user_123",
    "data": { "first_name": "Sarah", "has_activated": false }
  }'

journeys_invoke_response = courier.journeys.invoke(
  "user-onboarding",
  user_id: "user_123",
  data: {first_name: "Sarah", has_activated: false}
)

journeysInvokeResponse, err := client.Journeys.Invoke(
	context.TODO(),
	"user-onboarding",
	courier.JourneyInvokeParams{
		JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
			UserID: courier.String("user_123"),
			Data: map[string]any{
				"first_name":    "Sarah",
				"has_activated": false,
			},
		},
	},
)

JourneyInvokeParams params = JourneyInvokeParams.builder()
    .templateId("user-onboarding")
    .journeysInvokeRequest(JourneysInvokeRequest.builder()
        .userId("user_123")
        .data(JourneysInvokeRequest.Data.builder()
            .putAdditionalProperty("first_name", JsonValue.from("Sarah"))
            .putAdditionalProperty("has_activated", JsonValue.from(false))
            .build())
        .build())
    .build();
JourneysInvokeResponse journeysInvokeResponse = client.journeys().invoke(params);

$journeysInvokeResponse = $client->journeys->invoke(
  'user-onboarding',
  userID: 'user_123',
  data: ['first_name' => 'Sarah', 'has_activated' => false],
);

JourneyInvokeParams parameters = new()
{
    TemplateID = "user-onboarding",
    UserID = "user_123",
    Data = new Dictionary<string, JsonElement>()
    {
        { "first_name", JsonSerializer.SerializeToElement("Sarah") },
        { "has_activated", JsonSerializer.SerializeToElement(false) },
    },
};

var journeysInvokeResponse = await client.Journeys.Invoke(parameters);

courier journeys invoke \
  --api-key "$COURIER_API_KEY" \
  --template-id user-onboarding \
  --user-id user_123 \
  --data '{"first_name":"Sarah","has_activated":false}'

With Courier MCP, start the user-onboarding journey for user_123 with first_name Sarah.

Send an Idempotency-Key header so a retried signup request returns the same run instead of starting a second sequence.

Stop the sequence when they activate

When the user finally activates, stops the run by the token the journey stamped on it. Anything already delivered stays delivered, and the pending steps never fire.

const cancelJourneyResponse = await client.journeys.cancel({ cancelation_token: 'onboarding-user_123' });

cancel_journey_response = client.journeys.cancel(
    cancelation_token="onboarding-user_123",
)

curl -X POST https://api.courier.com/journeys/cancel \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelation_token": "onboarding-user_123"
  }'

cancel_journey_response = courier.journeys.cancel(cancel_journey_request: {cancelation_token: "onboarding-user_123"})

cancelJourneyResponse, err := client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{
	CancelJourneyRequest: courier.CancelJourneyRequestUnionParam{
		OfByCancelationToken: &courier.CancelJourneyRequestByCancelationTokenParam{
			CancelationToken: "onboarding-user_123",
		},
	},
})

CancelJourneyRequest.ByCancelationToken params = CancelJourneyRequest.ByCancelationToken.builder()
    .cancelationToken("onboarding-user_123")
    .build();
CancelJourneyResponse cancelJourneyResponse = client.journeys().cancel(params);

$cancelJourneyResponse = $client->journeys->cancel(
  cancelationToken: 'onboarding-user_123'
);

JourneyCancelParams parameters = new()
{
    CancelJourneyRequest = new ByCancelationToken("onboarding-user_123")
};

var cancelJourneyResponse = await client.Journeys.Cancel(parameters);

courier journeys cancel \
  --api-key "$COURIER_API_KEY" \
  --cancelation-token onboarding-user_123

With Courier MCP, cancel the journey run with the cancelation token onboarding-user_123.

To cancel one run instead, store the runId that invoke returned and pass run_id in place of cancelation_token. That branch answers with the run’s resulting status, so you can assert the cancel landed. Cancelling by token echoes the token back and reports nothing about what it matched.

Verify

Watch a run take the right path

Invoke for a test user with has_activated: false and open the Journey’s Logs tab. Click the run to see each node’s outcome drawn on the graph, and confirm the branch took the false path.

Prove the delay parks the run

The run should sit at the delay node rather than completing. Shorten the delay to a few minutes on a test copy if you would rather not wait three days.

Confirm a cancel stops it

Cancel the token while a run waits at a delay, then confirm the run reads Canceled and no further message is delivered.

An unpublished draft has no active version, so invoking it does nothing. Publish first, then invoke.

Every node type, and what each one accepts, is in the .

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

Build an onboarding sequence

What you will build

Prerequisites

Build the sequence

Verify

​What you will build

​Prerequisites

​Build the sequence

​Verify

What you will build

Prerequisites

Build the sequence

Verify