Courier journeys, as code

TL;DR

Courier journeys are now code. The Journeys API is the source of truth; SDKs, the Courier CLI, and the /courier-journeys-create agent skill (Claude Code, Cursor, Windsurf, Cline) are all just access points on top of it. Most teams will reach for the agent skill — describe the flow in plain English, approve the ASCII diagram, ship it — but the same JSON ships through any of them. The full skill is at the bottom of this post.

Journeys ossify

Building a Courier journey has never been the hard part. The visual designer lets PMs, marketing ops, or engineers stand one up without filing a ticket.

The problem shows up later.

A journey gets built once, then ossifies. The day-5 nudge written before the product had an activation event still fires for the user who activated on day two. The re-engagement email still links to a pricing page that moved. The branch condition still keys off a property that got renamed two quarters ago.

It's not that nobody noticed. It's that editing the journey — clicking through the visual editor or hand-rolling JSON in the browser — is annoying enough that the fix slides to next sprint, then the sprint after, then off the board entirely. "Set it and forget it" isn't a strategy. It's what happens when iteration is expensive.

Journeys-as-code makes iteration cheap. Same flow, same JSON, but now it lives next to the rest of your customer-engagement infrastructure: in source control, in PRs, in CI, and — most importantly — reachable from anything that can hit an API.

For a category-level view of where this fits (orchestration platforms, lifecycle tools, CDP-bundled journey builders), see the customer journey orchestration tools guide.

Journeys, as code

The Journeys API is the change. Every journey — every trigger, send, delay, branch, fetch, AI step — has a JSON representation, and there's now a public surface to create, update, publish, and invoke them programmatically. The visual editor still works; it's just no longer the only door.

Around the API sit a few access points:

• The API directly. POST /journeys to create, PUT /journeys/{id} for updates, POST /journeys/{id}/publish to ship. Standard CRUD. Drop-in for any backend.
• SDKs. Use the Courier SDK for your language so you get typed builders instead of hand-rolled JSON.
• The Courier CLI. Useful for scripted workflows, CI, and one-off testing without leaving the terminal.
• Agent skills. Plain-English in, real journey out. Covered in the next section.

Same JSON shape underneath. Pick the access point that matches your workflow.

Coding agents are the natural fit

The API is the foundation, but writing journey JSON by hand isn't where most teams want to spend their afternoon. Even with an SDK, you're still mapping a user story ("send a renewal email seven days out, branch on whether they've upgraded, fall back to SMS") onto node types, condition trees, and template ids.

A coding agent collapses that translation step. You describe the flow the way you'd describe it in a Notion doc; the agent emits the JSON and calls the API.

/courier-journeys-create is the agent skill that does this for Courier journeys. It runs end-to-end inside your coding agent:

1. It asks what the flow should do — trigger, each step in order, delays, branches, what every send sends.
2. It renders the result as ASCII so you can read it like a flowchart.
3. It waits for an explicit yes / change X / cancel.
4. Then it calls the Courier Journeys API — shell journey first, journey-scoped templates next, the full wired body, then publish.

It's an agent skill rather than a one-harness plugin, so the same markdown drives Claude Code, Cursor, Windsurf, Cline, and anything else that picks up skills from disk. The slash-command syntax (/courier-journeys-create) is Claude Code-flavored; other harnesses invoke skills their own way but the logic underneath is identical.

PMs use it to translate a Notion paragraph into a real flow. Growth and lifecycle teams iterate on re-engagement and renewal sequences without filing a ticket. Engineers get a fixture on disk they can drop into source control or a smoke test. Same skill, three workflows, no role-specific tooling.

Install

If you want the agent skill route (most teams will):

1. Install the Courier CLI: npm install -g @trycourier/cli
2. Drop the skill in your harness's skills directory — ~/.claude/skills/courier-journeys-create/ for Claude Code, ~/.cursor/skills/ for Cursor, equivalents for the rest. The courier-skills installation guide has the full list.
3. Export a Courier API key from your Test workspace: export COURIER_API_KEY="..."
4. Open your project and trigger the skill (/courier-journeys-create in Claude Code; the equivalent in your harness).

If the CLI isn't installed or the key isn't exported, the skill walks you through both before doing anything else.

If you want to skip the agent and go straight at the API, head to the Journeys API reference. The shape your agent skill is generating is the same shape you'd POST by hand.

An example, end to end

A renewal-alert flow with a personalized branch:

• Trigger on api-invoke
• fetch the user's subscription record
• ai step that summarizes recent usage
• branch on data.renewal_in_days:
  • Within 7 days: renewal-reminder email, two-day delay, status re-check, follow-up SMS if not renewed
  • Default: exit

Described to the skill in a couple of sentences, it came back with this (truncated):

┌────────────────────────┐
                  │ trigger api-invoke       │
                  └────────────┬───────────┘
                               ▼
                  ┌────────────────────────┐
                  │ fetch subscription       │
                  └────────────┬───────────┘
                               ▼
                  ┌────────────────────────┐
                  │ ai (usage summary)       │
                  └────────────┬───────────┘
                               ▼
                  ┌────────────────────────┐
                  │ branch renewal_in_days   │
                  └──┬───────────────────┬──┘
            WITHIN 7 │           DEFAULT │
                     ▼                   ▼
              (renewal email,        (exit)
               delay 2d,
               status check,
               SMS if not renewed)

After yes, four API calls: POST shell, a handful of POST*s for the journey-scoped templates, *PUT the full body, POST publish. State: PUBLISHED. About thirty seconds of wall time.

The same flow would build through the SDK or curl directly — the agent is just trading typing for talking.

One gotcha worth knowing

ai nodes require output_schema on submission. It's not optional. Send a journey body with an AI node missing the schema and you get a 400 with output_schema: must be a valid JSONSchema object. A minimal schema works fine:

{
  type: "ai",
  user_prompt: "Hi {{profile.name}}, summarize usage from the previous fetch.",
  output_schema: {
    type: "object",
    properties: { summary: { type: "string" } },
    required: ["summary"],
  },
}

The skill knows about this one and the other constraints worth remembering — journey-scoped templates are single-channel, POST /journeys rejects send nodes outright (so the flow has to be shell-first), every branch needs a default path. You don't have to remember any of it.

Read more

• Journeys overview
• Journeys API reference
• Manage Templates API
• Courier SDK libraries
• Courier CLI
• courier-skills on GitHub