Build a journey

A Journey runs a graph of nodes once per user when you trigger it. The canvas and the API build the same object, so pick the one that matches who owns the flow. A journey a product manager will keep tuning belongs in the canvas. A journey generated per customer, or checked into your repo, belongs in the API. A journey is not a broadcast. It runs per user, from an event or an API call, rather than going out to a group at a moment you choose. If you want one message to a list right now, use a .

Build in the canvas

Create the Journey

Open , select New Journey, and name it. Choose the API Invoke trigger so your code starts each run.

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

Add a send node

Drop a send node on the canvas, pick a channel, and select + Create to build its content inline. Each send node owns one Template scoped to this Journey.

Add a delay

Drag a delay node between the trigger and the send. Set it to wait a day. Journeys also offer branch, fetch data, throttle, batch, and digest nodes.

Publish

Select Publish to lock the draft as a version. New runs use it. Runs already in flight finish on the version they started with.Copy the Journey ID from the editor.

Build with the API

Create the Journey

takes a name and the node list. The list starts with a trigger and ends with an exit, and node ids are left out because the API assigns them. It returns the Journey ID.

const journey = await client.journeys.create({
  name: 'Welcome journey',
  nodes: [{ type: 'trigger', trigger_type: 'api-invoke' }, { type: 'exit' }],
});

journey = client.journeys.create(
    name="Welcome journey",
    nodes=[{"type": "trigger", "trigger_type": "api-invoke"}, {"type": "exit"}],
)

curl --request POST \
  --url https://api.courier.com/journeys \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Welcome journey",
    "nodes": [{ "type": "trigger", "trigger_type": "api-invoke" }, { "type": "exit" }]
  }'

journey = courier.journeys.create(
  name: "Welcome journey",
  nodes: [{type: "trigger", trigger_type: "api-invoke"}, {type: "exit"}]
)

journey, err := client.Journeys.New(context.TODO(), courier.JourneyNewParams{
	CreateJourneyRequest: courier.CreateJourneyRequestParam{
		Name: "Welcome journey",
		Nodes: []courier.JourneyNodeUnionParam{
			{OfAPIInvokeTrigger: &courier.JourneyAPIInvokeTriggerNodeParam{
				Type:        courier.JourneyAPIInvokeTriggerNodeTypeTrigger,
				TriggerType: courier.JourneyAPIInvokeTriggerNodeTriggerTypeAPIInvoke,
			}},
			{OfExit: &courier.JourneyExitNodeParam{Type: courier.JourneyExitNodeTypeExit}},
		},
	},
})

CreateJourneyRequest params = CreateJourneyRequest.builder()
    .name("Welcome journey")
    .addNode(JourneyApiInvokeTriggerNode.builder()
        .type(JourneyApiInvokeTriggerNode.Type.TRIGGER)
        .triggerType(JourneyApiInvokeTriggerNode.TriggerType.API_INVOKE)
        .build())
    .addNode(JourneyExitNode.builder()
        .type(JourneyExitNode.Type.EXIT)
        .build())
    .build();
JourneyResponse journey = client.journeys().create(params);

$journey = $client->journeys->create(
  name: 'Welcome journey',
  nodes: [['type' => 'trigger', 'trigger_type' => 'api-invoke'], ['type' => 'exit']],
);

JourneyCreateParams parameters = new()
{
    Name = "Welcome journey",
    Nodes = [new JourneyApiInvokeTriggerNode { Type = "trigger", TriggerType = "api-invoke" }, new JourneyExitNode { Type = "exit" }],
};

var journey = await client.Journeys.Create(parameters);

courier journeys create \
  --api-key "$COURIER_API_KEY" \
  --name "Welcome journey" \
  --node '{"type":"trigger","trigger_type":"api-invoke"}' \
  --node '{"type":"exit"}'

With Courier MCP, create a journey called Welcome journey with an API-invoke trigger and an exit node.

Add a scoped Template

creates the content a send node uses. These Templates belong to the Journey, separate from your workspace Templates.

const template = await client.journeys.templates.create('YOUR_JOURNEY_ID', {
  channel: 'email',
  notification: {
    name: 'Order shipped',
    tags: [],
    brand: null,
    subscription: null,
    content: {
      version: '2022-01-01',
      elements: [
        {
          type: 'channel',
          channel: 'email',
          elements: [{ type: 'text', content: 'Your order {{order_id}} shipped.' }],
        },
      ],
    },
  },
});

template = client.journeys.templates.create(
    template_id="YOUR_JOURNEY_ID",
    channel="email",
    notification={
        "name": "Order shipped",
        "tags": [],
        "brand": None,
        "subscription": None,
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [{"type": "text", "content": "Your order {{order_id}} shipped."}],
                }
            ],
        },
    },
)

curl --request POST \
  --url https://api.courier.com/journeys/YOUR_JOURNEY_ID/templates \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "channel": "email",
    "notification": {
      "name": "Order shipped",
      "tags": [],
      "brand": null,
      "subscription": null,
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [{ "type": "text", "content": "Your order {{order_id}} shipped." }]
          }
        ]
      }
    }
  }'

template = courier.journeys.templates.create(
  "YOUR_JOURNEY_ID",
  channel: "email",
  notification: {
    name: "Order shipped",
    tags: [],
    brand: nil,
    subscription: nil,
    content: {elements: [{type: "channel", channel: "email", elements: [{type: "text", content: "Your order {{order_id}} shipped."}]}], version: "2022-01-01"}
  }
)

// Elemental nodes carry no typed content field, so pass the notification as raw JSON.
notification := param.Override[courier.JourneyTemplateCreateRequestNotificationParam](json.RawMessage(`{
  "name": "Order shipped",
  "tags": [],
  "brand": null,
  "subscription": null,
  "content": {
    "version": "2022-01-01",
    "elements": [
      {
        "type": "channel",
        "channel": "email",
        "elements": [{ "type": "text", "content": "Your order {{order_id}} shipped." }]
      }
    ]
  }
}`))

template, err := client.Journeys.Templates.New(
	context.TODO(),
	"YOUR_JOURNEY_ID",
	courier.JourneyTemplateNewParams{
		JourneyTemplateCreateRequest: courier.JourneyTemplateCreateRequestParam{
			Channel:      "email",
			Notification: notification,
		},
	},
)

TemplateCreateParams params = TemplateCreateParams.builder()
    .templateId("YOUR_JOURNEY_ID")
    .journeyTemplateCreateRequest(JourneyTemplateCreateRequest.builder()
        .channel("email")
        .notification(JourneyTemplateCreateRequest.Notification.builder()
            .name("Order shipped")
            .tags(java.util.List.of())
            .brand(java.util.Optional.empty())
            .subscription(java.util.Optional.empty())
            .content(JourneyTemplateCreateRequest.Notification.Content.builder()
                // The channel builder has no addElement, so its children go in as an additional property.
                .addElement(ElementalChannelNodeWithType.builder()
                    .type(ElementalChannelNodeWithType.Type.CHANNEL)
                    .channel("email")
                    .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                        java.util.Map.of("type", "text", "content", "Your order {{order_id}} shipped."))))
                    .build())
                .version(JourneyTemplateCreateRequest.Notification.Content.Version._2022_01_01)
                .build())
            .build())
        .build())
    .build();
JourneyTemplateGetResponse template = client.journeys().templates().create(params);

$template = $client->journeys->templates->create(
  'YOUR_JOURNEY_ID',
  channel: 'email',
  notification: [
    'name' => 'Order shipped',
    'tags' => [],
    'brand' => null,
    'subscription' => null,
    'content' => ['version' => '2022-01-01', 'elements' => [['type' => 'channel', 'channel' => 'email', 'elements' => [['type' => 'text', 'content' => 'Your order {{order_id}} shipped.']]]]],
  ],
);

TemplateCreateParams parameters = new()
{
    TemplateID = "YOUR_JOURNEY_ID",
    Channel = "email",
    Notification = new()
    {
        Name = "Order shipped",
        Tags = [],
        Brand = null,
        Subscription = null,
        Content = new()
        {
            // Elemental nodes expose no typed content property, so build the node from raw JSON.
            Elements =
            [
                ElementalChannelNodeWithType.FromRawUnchecked(
                    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                    {
                      "type": "channel",
                      "channel": "email",
                      "elements": [{ "type": "text", "content": "Your order {{order_id}} shipped." }]
                    }
                    """)),
            ],
            Version = "2022-01-01",
        },
    },
};

var template = await client.Journeys.Templates.Create(parameters);

courier journeys:templates create \
  --api-key "$COURIER_API_KEY" \
  --template-id YOUR_JOURNEY_ID \
  --channel email \
  --notification '{"name":"Order shipped","tags":[],"brand":null,"subscription":null,"content":{"version":"2022-01-01","elements":[{"type":"channel","channel":"email","elements":[{"type":"text","content":"Your order {{order_id}} shipped."}]}]}}'

With Courier MCP, add an email template called Order shipped to my journey.

Wire the graph

takes the full node list, in the same body shape as the create call:

the trigger
a send node referencing the Template ID
any delay or branch nodes

Publish

snapshots the draft as the active version.

await client.journeys.publish('YOUR_JOURNEY_ID');

client.journeys.publish(
    template_id="YOUR_JOURNEY_ID",
)

curl --request POST \
  --url https://api.courier.com/journeys/YOUR_JOURNEY_ID/publish \
  --header "Authorization: Bearer $COURIER_API_KEY"

result = courier.journeys.publish("YOUR_JOURNEY_ID")

_, err := client.Journeys.Publish(
	context.TODO(),
	"YOUR_JOURNEY_ID",
	courier.JourneyPublishParams{},
)

client.journeys().publish("YOUR_JOURNEY_ID");

$result = $client->journeys->publish('YOUR_JOURNEY_ID');

JourneyPublishParams parameters = new() { TemplateID = "YOUR_JOURNEY_ID" };

await client.Journeys.Publish(parameters);

courier journeys publish \
  --api-key "$COURIER_API_KEY" \
  --template-id YOUR_JOURNEY_ID

With Courier MCP, publish my journey so the draft becomes the active version.

Invoke a run

Either path ends the same way. Publishing makes the journey live, and a run starts when your app invokes it by ID or alias. covers the call in every language. It also covers the Idempotency-Key that stops a retry starting a second run, and how to inspect or cancel a run by its runId.

Limits & behavior

Editing a send node’s content after publishing changes nothing on its own. The edit saves as a new template draft. The journey keeps sending the version it was published with, and no error marks the difference, so publish the journey again to make the edit live. Runs already in flight finish on the version they started with. A publish does not migrate them, so a change to a multi-day flow reaches only the runs that begin after it.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Build a journey

Build in the canvas

Build with the API

Invoke a run

Limits & behavior

​Build in the canvas

​Build with the API

​Invoke a run

​Limits & behavior

Build in the canvas

Build with the API

Invoke a run

Limits & behavior