---
title: "Use variation"
method: POST
path: "/campaigns/{campaignId}/variations/{variationId}/use"
tags: ["Campaigns"]
---

# Use variation

`POST /campaigns/{campaignId}/variations/{variationId}/use`

## Request

- Base URL: `https://api.sequenzy.com/api/v1`
- URL: `https://api.sequenzy.com/api/v1/campaigns/{campaignId}/variations/{variationId}/use`
- Auth: HTTP bearer

Copies a ready variation into the campaign email (blocks, and the subject, preview text, theme and font when the variation has its own). If the email's current content is not already a variation, it is saved first as a new variation named "Before {label}" and returned as savedPrevious, so nothing is lost. When the variation has its own look, the other variations that follow the email's look keep the one it had. Draft campaigns only. Translations are re-derived from the new content.

## Path parameters

- `campaignId` string, required
- `variationId` string, required

## Response `200`

The email now has the variation's content

- object
  - `success` boolean
  - `variation` EmailVariation: An alternative version of a campaign email, compared side by side on the editor canvas.
    - `id` string
    - `emailId` string
    - `parentId` string, nullable: The nearest variation this one descends from that has not been discarded. Null when derived from the email.
    - `label` string: Canvas label. V1, V2, ... for versions of the email; V2.1, V2.2, ... for branches of V2.
    - `name` string
    - `summary` string, nullable: What changed, in a sentence.
    - `prompt` string, nullable: The request that generated this variation.
    - `style` 'close' | 'fresh' | 'bold' | 'null', nullable: How far it was asked to move from its source, when AI generated it.
    - `status` 'generating' | 'ready' | 'failed'
    - `error` string, nullable: Why generation failed.
    - `subject` string, nullable: Subject this variation uses. Null keeps the email's subject.
    - `previewText` string, nullable
    - `blocks` EmailBlock[], nullable: Null while generating or after a failure.
      - `id` string
      - `type` 'text' | 'html' | 'heading' | 'list' | 'button' | 'spacer' | 'divider' | 'image' | 'columns' | 'group' | 'conditional-group' | 'repeat' | 'card' | 'cta' | 'social' | 'logo' | 'header' | 'footer' | 'video' | 'product' | 'discount-code' | 'code' | 'countdown' | 'hero' | 'testimonial' | 'gallery' | 'badge' | 'table' | 'features' | 'image-card' | 'pricing' | 'author' | 'article' | 'rating' | 'stats' | 'steps' | 'product-grid' | 'poll', required
      - `content` string: Content for text, html, and heading-like blocks.
      - `label` string: Editor label for a structural group block.
      - `layout` 'stack' | 'row' | 'grid' | 'overlay': Direct-child layout for a structural group block.
      - `columns` integer: Number of columns used by a group with grid layout.
      - `gap` integer: Gap in pixels between direct group children.
      - `stackOnMobile` boolean: Columns block only. Multi-column rows stack into a single column on screens 480px wide or narrower. Set to false to keep the columns side by side on mobile. Omit or set to true for the default stacking.
      - `padding` integer: Uniform group padding in pixels; per-side styles.padding* fields override it.
      - `overlayColor` string: Opaque fallback and shade color for an overlay group.
      - `overlayShade` integer: Overlay shade intensity as a percentage.
      - `overlayPosition` 'top' | 'center' | 'bottom': Vertical position of overlay foreground content.
      - `children` EmailBlock[]: Recursive child blocks for group and repeat containers.
      - `styles` object: Per-block visual styles. For compatibility, style fields such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius can also be supplied at the block top level and are normalized into this object.
        - `paddingTop` number
        - `paddingBottom` number
        - `paddingLeft` number
        - `paddingRight` number
        - `backgroundColor` string
        - `backgroundOpacity` number: Background opacity percentage from 0 to 100.
        - `textColor` string
        - `textAlign` 'left' | 'center' | 'right'
        - `keepAlign` boolean: Keep a centered button, logo or footer centered when the email is left-aligned (layout.contentAlign left). Without it a left email moves these blocks left; right always stays.
        - `borderRadius` number
        - `borderColor` string
        - `borderWidth` number
        - `bleed` boolean: Stretch the block edge-to-edge across the email container. Top-level blocks only.
      - `conditions` object[]: Optional per-block display rules. The block renders only when every rule matches. The same shape is used for a conditional-group block's top-level `conditions`.
        - `id` string, required
        - `field` 'variable' | 'attribute' | 'email' | 'firstName' | 'lastName', required: `variable` resolves a merge-tag path from the transactional send `variables` or an automation `event` payload (nested paths like `order.total` or `event.plan` work). `attribute` reads a stored subscriber attribute. `email`, `firstName`, and `lastName` read core subscriber fields.
        - `operator` 'is' | 'is_not' | 'contains' | 'not_contains' | 'gt' | 'gte' | 'lt' | 'lte' | 'is_empty' | 'is_not_empty', required
        - `value` string, required: For `variable` and `attribute`, use `name:value` - the part before the colon is the variable path or attribute name, and the part after it is the comparison value. For `email`, `firstName`, and `lastName`, provide the plain comparison string.
    - `emailTheme` object, nullable: The variation's own email theme. Null means it uses the email's theme.
    - `fontFamily` string, nullable: The variation's own body font stack. Null means it uses the email's font.
    - `position` object, nullable: Where the user placed it on the editor canvas, in canvas pixels. Null means the canvas places it automatically.
      - `x` integer
      - `y` integer
    - `inUse` boolean: Whether using this variation would leave the campaign email unchanged (same blocks, and its own subject, preview text, theme and font when it has them). When several match, only the one used most recently is in use.
    - `usedAt` string, date-time, nullable: When this variation was last put in the campaign email.
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `savedPrevious` EmailVariation: An alternative version of a campaign email, compared side by side on the editor canvas.
    - `id` string
    - `emailId` string
    - `parentId` string, nullable: The nearest variation this one descends from that has not been discarded. Null when derived from the email.
    - `label` string: Canvas label. V1, V2, ... for versions of the email; V2.1, V2.2, ... for branches of V2.
    - `name` string
    - `summary` string, nullable: What changed, in a sentence.
    - `prompt` string, nullable: The request that generated this variation.
    - `style` 'close' | 'fresh' | 'bold' | 'null', nullable: How far it was asked to move from its source, when AI generated it.
    - `status` 'generating' | 'ready' | 'failed'
    - `error` string, nullable: Why generation failed.
    - `subject` string, nullable: Subject this variation uses. Null keeps the email's subject.
    - `previewText` string, nullable
    - `blocks` EmailBlock[], nullable: Null while generating or after a failure.
      - `id` string
      - `type` 'text' | 'html' | 'heading' | 'list' | 'button' | 'spacer' | 'divider' | 'image' | 'columns' | 'group' | 'conditional-group' | 'repeat' | 'card' | 'cta' | 'social' | 'logo' | 'header' | 'footer' | 'video' | 'product' | 'discount-code' | 'code' | 'countdown' | 'hero' | 'testimonial' | 'gallery' | 'badge' | 'table' | 'features' | 'image-card' | 'pricing' | 'author' | 'article' | 'rating' | 'stats' | 'steps' | 'product-grid' | 'poll', required
      - `content` string: Content for text, html, and heading-like blocks.
      - `label` string: Editor label for a structural group block.
      - `layout` 'stack' | 'row' | 'grid' | 'overlay': Direct-child layout for a structural group block.
      - `columns` integer: Number of columns used by a group with grid layout.
      - `gap` integer: Gap in pixels between direct group children.
      - `stackOnMobile` boolean: Columns block only. Multi-column rows stack into a single column on screens 480px wide or narrower. Set to false to keep the columns side by side on mobile. Omit or set to true for the default stacking.
      - `padding` integer: Uniform group padding in pixels; per-side styles.padding* fields override it.
      - `overlayColor` string: Opaque fallback and shade color for an overlay group.
      - `overlayShade` integer: Overlay shade intensity as a percentage.
      - `overlayPosition` 'top' | 'center' | 'bottom': Vertical position of overlay foreground content.
      - `children` EmailBlock[]: Recursive child blocks for group and repeat containers.
      - `styles` object: Per-block visual styles. For compatibility, style fields such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius can also be supplied at the block top level and are normalized into this object.
        - `paddingTop` number
        - `paddingBottom` number
        - `paddingLeft` number
        - `paddingRight` number
        - `backgroundColor` string
        - `backgroundOpacity` number: Background opacity percentage from 0 to 100.
        - `textColor` string
        - `textAlign` 'left' | 'center' | 'right'
        - `keepAlign` boolean: Keep a centered button, logo or footer centered when the email is left-aligned (layout.contentAlign left). Without it a left email moves these blocks left; right always stays.
        - `borderRadius` number
        - `borderColor` string
        - `borderWidth` number
        - `bleed` boolean: Stretch the block edge-to-edge across the email container. Top-level blocks only.
      - `conditions` object[]: Optional per-block display rules. The block renders only when every rule matches. The same shape is used for a conditional-group block's top-level `conditions`.
        - `id` string, required
        - `field` 'variable' | 'attribute' | 'email' | 'firstName' | 'lastName', required: `variable` resolves a merge-tag path from the transactional send `variables` or an automation `event` payload (nested paths like `order.total` or `event.plan` work). `attribute` reads a stored subscriber attribute. `email`, `firstName`, and `lastName` read core subscriber fields.
        - `operator` 'is' | 'is_not' | 'contains' | 'not_contains' | 'gt' | 'gte' | 'lt' | 'lte' | 'is_empty' | 'is_not_empty', required
        - `value` string, required: For `variable` and `attribute`, use `name:value` - the part before the colon is the variable path or attribute name, and the part after it is the comparison value. For `email`, `firstName`, and `lastName`, provide the plain comparison string.
    - `emailTheme` object, nullable: The variation's own email theme. Null means it uses the email's theme.
    - `fontFamily` string, nullable: The variation's own body font stack. Null means it uses the email's font.
    - `position` object, nullable: Where the user placed it on the editor canvas, in canvas pixels. Null means the canvas places it automatically.
      - `x` integer
      - `y` integer
    - `inUse` boolean: Whether using this variation would leave the campaign email unchanged (same blocks, and its own subject, preview text, theme and font when it has them). When several match, only the one used most recently is in use.
    - `usedAt` string, date-time, nullable: When this variation was last put in the campaign email.
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

## Other responses

- `400`: The campaign is not a draft, or not an email campaign
- `401`: Unauthorized
- `404`: Campaign or variation not found
- `409`: The variation is still generating or failed

## Changes

- **2026-10-26** `e2e7d27d7804`: 2 info
  - added the optional property `savedPrevious/oneOf[#/components/schemas/EmailVariation]/blocks/items/styles/keepAlign` to the response with the `200` status
  - added the optional property `variation/blocks/items/styles/keepAlign` to the response with the `200` status
- **2026-10-16** `db3873ca3d4d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sequenzy/apis/sequenzy-api/changes/campaigns/:campaignId/variations/:variationId/use/post.md)

---

[API](https://skmtc.dev/sequenzy/apis/sequenzy-api.md) - [All operations](https://skmtc.dev/sequenzy/apis/sequenzy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sequenzy/apis/sequenzy-api/revisions/8156dc12d8b4?raw)