> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coldsend.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Follow-up Sequences

> Configure automated follow-up emails based on recipient behavior.

Sequences define automated follow-up emails that trigger based on recipient behavior. Each follow-up step has its own email variants.

## How Sequences Work

1. Initial email is sent to lead
2. ColdSend waits the configured number of days
3. If the trigger condition is met, follow-up is sent
4. Process repeats for subsequent steps

## Campaign Status and Sequence Updates

Sequences can be managed differently depending on campaign status:

| Status     | Field            | Behavior                              | Use Case                         |
| ---------- | ---------------- | ------------------------------------- | -------------------------------- |
| **DRAFT**  | `sequences`      | Replaces all sequences at once        | Initial campaign setup           |
| **PAUSED** | `sequence_edits` | Granular add/edit/delete per sequence | Update copy on running campaigns |

<Warning>
  `sequences` and `sequence_edits` are **mutually exclusive** — you cannot use both in the same request. Using `sequences` on a PAUSED campaign returns a 400 error, and `sequence_edits` on a DRAFT campaign also returns a 400 error.
</Warning>

## Configuring Sequences (DRAFT campaigns)

Use the `sequences` array to replace all follow-up sequences at once. This is the simplest approach during initial campaign setup:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    response = requests.put(
        f"{base_url}/api/public/v1/campaigns/{campaign_id}",
        headers={"X-API-Key": api_key},
        json={
            "sequences": [
                {
                    "step_number": 2,
                    "trigger_type": "NOT_OPENED",
                    "wait_days": 3,
                    "variants": [
                        {
                            "variant_name": "A",
                            "subject_template": "Following up on my previous email",
                            "email_content": "Hi {{first_name}},\n\nI wanted to follow up on my previous email...\n\nBest,\nJohn",
                            "distribution_percent": 100
                        }
                    ]
                },
                {
                    "step_number": 3,
                    "trigger_type": "NOT_REPLIED",
                    "wait_days": 5,
                    "variants": [
                        {
                            "variant_name": "A",
                            "subject_template": "Last thought",
                            "email_content": "Hi {{first_name}},\n\nOne last thought I wanted to share...\n\nBest,\nJohn",
                            "distribution_percent": 100
                        }
                    ]
                }
            ]
        }
    )
    ```
  </Tab>
</Tabs>

## Sequence Fields

| Field                | Type   | Required | Description                                                            |
| -------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `step_number`        | int    | Yes      | Sequence position (2-4). Step 1 is the initial email.                  |
| `trigger_type`       | string | Yes      | When to send: `NOT_OPENED`, `NOT_REPLIED`, or `OPENED_BUT_NOT_REPLIED` |
| `wait_days`          | int    | Yes      | Days to wait (1-30)                                                    |
| `enable_unsubscribe` | bool   | No       | Override campaign setting. Inherits if not specified.                  |
| `variants`           | array  | Yes      | At least one email variant required per sequence                       |

## Trigger Types

| Trigger                  | Fires When                                                                     |
| ------------------------ | ------------------------------------------------------------------------------ |
| `NOT_OPENED`             | Lead has not opened any previous email                                         |
| `NOT_REPLIED`            | Lead has not replied to any email (includes those who opened but didn't reply) |
| `OPENED_BUT_NOT_REPLIED` | Lead opened at least one email but hasn't replied                              |

<Tip>
  `NOT_REPLIED` is the most commonly used trigger — it reaches both non-openers and openers who didn't respond.
</Tip>

## Sequence Limits

| Limit                   | Value           |
| ----------------------- | --------------- |
| Maximum sequences       | 3 per campaign  |
| Step numbers            | 2, 3, or 4      |
| Wait days per sequence  | 1-30 days       |
| Total sequence duration | 45 days maximum |

## Sequence Edits (PAUSED campaigns)

For PAUSED campaigns, use `sequence_edits` to modify individual sequences without replacing everything. Each item has an `action` field:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    response = requests.put(
        f"{base_url}/api/public/v1/campaigns/{campaign_id}",
        headers={"X-API-Key": api_key},
        json={
            "sequence_edits": [
                {
                    "action": "add",
                    "step_number": 3,
                    "trigger_type": "NOT_REPLIED",
                    "wait_days": 5,
                    "variants": [
                        {
                            "variant_name": "A",
                            "subject_template": "One more thought",
                            "email_content": "Hi {{first_name}},\n\nOne last thing I wanted to share...\n\nBest,\nJohn",
                            "distribution_percent": 100
                        }
                    ]
                },
                {
                    "action": "edit",
                    "sequence_id": "existing-sequence-uuid",
                    "variants": [
                        {
                            "variant_name": "A",
                            "subject_template": "Updated subject",
                            "email_content": "Updated follow-up content...",
                            "distribution_percent": 100
                        }
                    ]
                },
                {
                    "action": "delete",
                    "sequence_id": "sequence-to-remove-uuid"
                }
            ]
        }
    )
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(`${baseUrl}/api/public/v1/campaigns/${campaignId}`, {
      method: "PUT",
      headers: {
        "X-API-Key": apiKey,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        sequence_edits: [
          {
            action: "add",
            step_number: 3,
            trigger_type: "NOT_REPLIED",
            wait_days: 5,
            variants: [{
              variant_name: "A",
              subject_template: "One more thought",
              email_content: "Hi {{first_name}},\n\n...",
              distribution_percent: 100
            }]
          }
        ]
      })
    });
    ```
  </Tab>
</Tabs>

### Sequence Edit Actions

| Action   | Required Fields                                        | Description                                  |
| -------- | ------------------------------------------------------ | -------------------------------------------- |
| `add`    | `step_number`, `trigger_type`, `wait_days`, `variants` | Create a new follow-up sequence              |
| `edit`   | `sequence_id`, + any fields to update                  | Modify an existing sequence (partial update) |
| `delete` | `sequence_id`                                          | Remove a sequence entirely                   |

<Tip>
  Use `GET /campaigns/{campaign_id}` to retrieve existing `sequence_id` values before editing or deleting.
</Tip>

## Best Practices

### Recommended Timing

| Step                 | Recommended Wait | Purpose                                 |
| -------------------- | ---------------- | --------------------------------------- |
| 2 (first follow-up)  | 2-4 days         | Reference original email, add value     |
| 3 (second follow-up) | 5-7 days         | Offer a case study or specific resource |
| 4 (final follow-up)  | 7-10 days        | Create urgency or breakup email         |

### Subject Line Patterns

| Approach           | Example                                |
| ------------------ | -------------------------------------- |
| Reference previous | `Re: Quick question about {{company}}` |
| Fresh angle        | `One more thing about {{company}}`     |
| Curiosity          | `Did you see this?`                    |

## Next Steps

<CardGroup cols={2}>
  <Card title="Email Variants" href="/campaigns/variants" icon="files">
    A/B testing and personalization for follow-ups.
  </Card>

  <Card title="Personalization" href="/campaigns/personalization" icon="sparkles">
    Use variables, spintax, and conditionals.
  </Card>
</CardGroup>