# Chapter 11: Your First Journey

## The Problem

Segments are powerful, but they're snapshots. You want something more: "When a customer signs up, send a welcome email. Wait 3 days. If they haven't made a purchase, send a reminder. If they have, send a thank-you and add them to the loyalty program."

This is a journey—a multi-step experience that unfolds over time.

## The Key Idea

Core concept
A journey is a sequence of steps that customers move through based on time and behavior. It's marketing automation defined as code.

Instead of configuring flows in a UI, you describe the experience to AI and get a YAML file that orchestrates everything.

## Creating Your First Journey

Describe the customer experience:


```
> "Create a welcome journey: send a welcome email when someone signs up, wait 3 days, then send a follow-up if they haven't purchased"
```


```mermaid
flowchart TD
    Entry([New Signups]) --> Welcome[Send Welcome Email]
    Welcome --> Wait[Wait 3 Days]
    Wait --> Check{Purchased?}
    Check -->|Yes| ThankYou[Send Thank You]
    Check -->|No| Reminder[Send Reminder]
    ThankYou --> End1([End])
    Reminder --> End2([End])
```

AI generates:


```yaml
name: Welcome Series
description: Onboard new customers with welcome and follow-up emails

entry:
  segment: New Signups

stages:
  - name: Onboarding
    steps:
      - type: activation
        name: Send Welcome Email
        id: welcome-email
        with:
          activation: welcome-email-sendgrid
        next: wait-period

      - type: wait
        name: Wait 3 Days
        id: wait-period
        with:
          duration: 3
          unit: day
        next: check-purchase

      - type: decision_point
        name: Did They Purchase?
        id: check-purchase
        with:
          condition:
            segment: Made First Purchase
        branches:
          - match: true
            next: thank-you
          - match: false
            next: reminder

      - type: activation
        name: Send Reminder
        id: reminder
        with:
          activation: reminder-email-sendgrid
        next: end

      - type: activation
        name: Send Thank You
        id: thank-you
        with:
          activation: thankyou-email-sendgrid
```

## Understanding the Structure

A journey has three main parts:

### Entry

Who enters the journey:


```yaml
entry:
  segment: New Signups
```

Customers enter when they join the "New Signups" segment.

### Stages

Organizational containers for steps:


```yaml
stages:
  - name: Onboarding
    steps: [...]
```

Stages help you organize complex journeys into logical phases.

### Steps

The actual actions and logic:


```yaml
steps:
  - type: activation
    name: Send Welcome Email
```

Each step does something: send a message, wait, check a condition, etc.

## Step Types

| Type | What It Does | Example Use |
|  --- | --- | --- |
| `activation` | Send to a channel | Email, SMS, push notification |
| `wait` | Pause for time | Wait 3 days |
| `decision_point` | Branch based on condition | Did they purchase? |
| `ab_test` | Split audience | Test two messages |
| `end` | Exit the journey | Journey complete |


## How Steps Connect

Steps link via `next`:


```yaml
- type: activation
  name: Send Welcome Email
  id: welcome-email
  next: wait-period  # Go here after

- type: wait
  name: Wait 3 Days
  id: wait-period
  next: check-purchase  # Then go here
```

Each step has an `id` that other steps reference. This creates the flow.

## Visualizing the Journey

Push the journey in draft mode to see it in the Console:


```
> "Push this journey as a draft"
```


```
Pushing journey: Welcome Series (draft mode)

✓ Journey created in draft state
✓ Not launched - no customers will enter

View in Console:
https://console.treasuredata.com/app/journeys/12345

Click the link to see the visual flow in the UI.
```

Draft mode lets you verify the flow visually before launching.

## Entry Conditions

Control who enters:

**Segment-based entry:**


```yaml
entry:
  segment: New Signups
```

**With additional filters:**


```yaml
entry:
  segment: New Signups
  filter:
    attribute: country
    operator: In
    values: ["USA", "Canada"]
```

## Re-entry Rules

Can customers go through the journey multiple times?


```yaml
reentry: no_reentry        # Once only
reentry: allow_reentry     # Can repeat
reentry: reentry_after_exit  # Can repeat after finishing
```

## Goals

Define what success looks like:


```yaml
goals:
  - name: Made Purchase
    segment: Purchasers
    exit_on_goal: true
```

When a customer achieves a goal, they can exit the journey early. This prevents sending a "please buy" email to someone who already bought.

## Mental Model: Choose Your Own Adventure

Journeys are like those books where the reader makes choices:

- Start: "You receive a welcome email. Turn to page 2."
- Page 2: "Wait 3 days. Turn to page 3."
- Page 3: "Did you make a purchase? If yes, turn to page 4. If no, turn to page 5."
- Page 4: "Thank you! The end."
- Page 5: "Here's a reminder. The end."


Each customer reads their own path through the story based on their actions.

## Previewing a Journey

Before going live:


```
> "Preview the journey"
```


```
Journey: Welcome Series

Entry: New Signups segment
Currently in segment: 1,247 customers would enter

Steps:
1. Send Welcome Email → welcome-email-sendgrid
2. Wait 3 days
3. Check: Made First Purchase segment
   - If yes: Send Thank You
   - If no: Send Reminder

Estimated flow:
- ~70% expected to reach decision point
- ~25% expected to have purchased (based on historical data)
```

## Validating and Pushing

Same workflow as segments:


```
> "Validate the journey"
```


```
✓ Journey syntax is valid
✓ All segments referenced exist
✓ All activations referenced exist
✓ No unreachable steps

Ready to push.
```


```
> "Push the journey"
```

## Pitfalls

**"Customers aren't entering."**

Check the entry segment—it might be empty or have wrong criteria:


```
> "How many customers are in the New Signups segment?"
```

**"The flow seems wrong."**

Verify the `next` references:


```
> "Trace the path from welcome email to end"
```

**"Activations aren't firing."**

Check that the connection is enabled and working:


```
> "Show me the status of welcome-email-sendgrid activation"
```

## What You've Learned

- Journeys are multi-step customer experiences
- Customers enter via segments
- Steps are actions (activate), waits, or decisions
- Steps connect via `next` and `id` references
- Goals define success and can trigger early exit
- Preview and validate before pushing


## Next Step

You've built a linear journey. [Chapter 12](/treasure-code/book/12-journey-logic) explores advanced patterns—conditional branches, A/B tests, and complex decision trees.

*You've created your first journey. Next, you'll add intelligence to the path.*