> ## 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.

# Email Variants

> Create A/B test variants for your campaign emails.

Variants allow you to A/B test different email approaches within a single campaign. Each variant has its own subject line, content, and distribution percentage.

<Info>
  You can create up to 4 variants per campaign. Leads are randomly assigned to variants based on distribution percentages when the campaign launches.
</Info>

## Campaign Status and Variant Updates

Variants can be updated on both **DRAFT** and **PAUSED** campaigns via `PUT /campaigns/{campaign_id}`, but the behavior differs:

| Status     | Behavior                    | Use Case                                                   |
| ---------- | --------------------------- | ---------------------------------------------------------- |
| **DRAFT**  | Replaces all variants       | Initial campaign setup, full content rewrite               |
| **PAUSED** | Smart merge by variant name | Update copy on existing campaigns without losing analytics |

When updating variants on a **PAUSED** campaign:

* Existing variants are matched by `variant_name` and updated in place (preserving IDs and analytics)
* New variant names are created
* Variant names omitted from the request are deleted

<Note>
  ACTIVE campaigns must be paused first before updating variants. Use `POST /campaigns/{campaign_id}/pause` to pause, then update, then `POST /campaigns/{campaign_id}/activate` to resume.
</Note>

## Configuring Variants

Variants are provided in the `variants` array when updating a campaign via `PUT /api/public/v1/campaigns/{campaign_id}`:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.put(
        f"{base_url}/api/public/v1/campaigns/{campaign_id}",
        headers={"X-API-Key": api_key},
        json={
            "variants": [
                {
                    "variant_name": "A",
                    "variant_label": "Direct Approach",
                    "subject_template": "Quick question about {{company}}",
                    "email_content": "Hi {{first_name}},\n\nI noticed {{company}} is expanding. I'd love to share how we've helped similar companies.\n\nBest,\nJohn",
                    "distribution_percent": 50
                },
                {
                    "variant_name": "B",
                    "variant_label": "Soft Introduction",
                    "subject_template": "Introduction - {{company}}",
                    "email_content": "Hi {{first_name}},\n\nI hope this finds you well. I wanted to introduce our company and see if there's an opportunity to collaborate.\n\nBest,\nJohn Smith",
                    "distribution_percent": 50
                }
            ]
        }
    )
    ```
  </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({
        variants: [
          {
            variant_name: "A",
            variant_label: "Direct Approach",
            subject_template: "Quick question about {{company}}",
            email_content: "Hi {{first_name}},\n\n...",
            distribution_percent: 50
          },
          {
            variant_name: "B",
            variant_label: "Soft Introduction",
            subject_template: "Introduction - {{company}}",
            email_content: "Hi {{first_name}},\n\n...",
            distribution_percent: 50
          }
        ]
      })
    });
    ```
  </Tab>
</Tabs>

## Variant Fields

| Field                  | Type   | Required | Description                                                                                                                         |
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `variant_name`         | string | Yes      | Unique identifier (A, B, C, D). Only letters allowed. Automatically uppercased.                                                     |
| `subject_template`     | string | Yes      | Subject line with personalization. Max 500 characters.                                                                              |
| `email_content`        | string | Yes      | Email body content. Max 100,000 characters. Must be at least 10 characters (enforced at service layer). Supports Liquid templating. |
| `distribution_percent` | int    | Yes      | Percentage of leads for this variant (0-100). All must sum to 100.                                                                  |
| `variant_label`        | string | No       | User-friendly label for analytics (max 100 chars).                                                                                  |
| `content_type`         | string | No       | Content mode: `plaintext`, `html`, or `raw_html`. Inferred from tracking setting if omitted.                                        |

<Note>
  Distribution percentages must sum to exactly 100%. If configuring variants, the API validates this on every update.
</Note>

## Subject Line Best Practices

* **Keep it concise** — 40-60 characters for optimal display
* **Focus on value** — Lead with a benefit or question
* **Personalize** — Use `{{first_name}}` or `{{company}}`
* **Avoid spam triggers** — No ALL CAPS, excessive punctuation, or words like free, urgent

## Testing Different Approaches

Test one element at a time:

| What to Test     | Variant A          | Variant B              |
| ---------------- | ------------------ | ---------------------- |
| **Subject line** | Direct question    | Statement of value     |
| **Opening**      | Personal reference | Generic greeting       |
| **CTA**          | Calendar link      | Reply request          |
| **Length**       | Short (3-4 lines)  | Detailed (10-15 lines) |

<Info>
  Compare variant performance after 7-14 days to reach statistical significance.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Follow-up Sequences" href="/campaigns/sequences" icon="layers">
    Set up automated follow-up emails.
  </Card>

  <Card title="Personalization" href="/campaigns/personalization" icon="sparkles">
    Use variables and conditionals for personalized content.
  </Card>
</CardGroup>