---
title: "Update a sequence"
method: PUT
path: "/v1/sequences/{sequence_id}"
tags: ["Sequences"]
---

# Update a sequence

`PUT /v1/sequences/{sequence_id}`

## Request

- Base URL: `https://api.mailrith.com`
- URL: `https://api.mailrith.com/v1/sequences/{sequence_id}`
- Auth: HTTP bearer

Updates an existing paused Sequence. Before changing a running Sequence, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Sequence, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate a Sequence that was not already running.

## Path parameters

- `sequence_id` string, required

## Request body

- SequenceUpdateRequest
  - `name` string
  - `connection_id` string, nullable
  - `reply_to_email` string, nullable
  - `track_opens` boolean
  - `track_clicks` boolean
  - `utm_source` string, nullable
  - `utm_medium` string, nullable
  - `utm_campaign` string, nullable
  - `utm_term` string, nullable
  - `utm_content` string, nullable
  - `definition` SequenceDefinition
    - `emails` SequenceEmail[], required
      - `id` string, required
      - `subject` string, required: For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback="friend"] or [Subscriber_Email, fallback=""]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.
      - `previewText` string, nullable, required
      - `body` string: Rendered HTML returned by Mailrith. Agents should send bodyDocument when creating or updating a Sequence.
      - `bodyDocument` BroadcastEmailDocument, required
        - `type` 'doc' | 'paragraph' | 'heading' | 'text' | 'hardBreak' | 'bulletList' | 'orderedList' | 'listItem' | 'blockquote' | 'emailSection' | 'emailSectionColumn' | 'emailButton' | 'image' | 'horizontalRule', required
        - `attrs` object
          - `id` string
          - `level` 1 | 2 | 3
          - `textAlign` 'left' | 'center' | 'right' | 'justify'
          - `columns` 1 | 2 | 3
          - `width` 'default' | 'large' | 'full' | 'fit'
          - `backgroundColor` string
          - `blockquoteBorderColor` string
          - `linkColor` string
          - `layoutAlignment` 'left' | 'center'
          - `backgroundImageUrl` string
          - `margin` 'none' | 'normal' | 'large'
          - `padding` 'none' | 'normal' | 'large'
          - `borderColor` string
          - `borderWidth` 'none' | 'normal' | 'large'
          - `borderRadius` 'none' | 'normal' | 'small' | 'large' | 'full'
          - `verticalAlign` 'top' | 'middle' | 'bottom'
          - `href` string
          - `textColor` string
          - `size` 'small' | 'medium' | 'large'
          - `align` 'left' | 'center' | 'right'
          - `label` string
          - `src` string
          - `alt` string
          - `title` string
          - `caption` string
          - `source` 'unsplash'
          - `unsplash` object
            - `photoId` string
            - `photographerName` string, required
            - `photographerUsername` string
            - `photographerUrl` string
            - `unsplashUrl` string
          - `widthPercent` number
          - `crop` 'none' | 'square' | 'circle'
          - `fillColumn` boolean
        - `content` BroadcastEmailNode[]
          - `type` 'doc' | 'paragraph' | 'heading' | 'text' | 'hardBreak' | 'bulletList' | 'orderedList' | 'listItem' | 'blockquote' | 'emailSection' | 'emailSectionColumn' | 'emailButton' | 'image' | 'horizontalRule', required
          - `attrs` object
            - `id` string
            - `level` 1 | 2 | 3
            - `textAlign` 'left' | 'center' | 'right' | 'justify'
            - `columns` 1 | 2 | 3
            - `width` 'default' | 'large' | 'full' | 'fit'
            - `backgroundColor` string
            - `blockquoteBorderColor` string
            - `linkColor` string
            - `layoutAlignment` 'left' | 'center'
            - `backgroundImageUrl` string
            - `margin` 'none' | 'normal' | 'large'
            - `padding` 'none' | 'normal' | 'large'
            - `borderColor` string
            - `borderWidth` 'none' | 'normal' | 'large'
            - `borderRadius` 'none' | 'normal' | 'small' | 'large' | 'full'
            - `verticalAlign` 'top' | 'middle' | 'bottom'
            - `href` string
            - `textColor` string
            - `size` 'small' | 'medium' | 'large'
            - `align` 'left' | 'center' | 'right'
            - `label` string
            - `src` string
            - `alt` string
            - `title` string
            - `caption` string
            - `source` 'unsplash'
            - `unsplash` object
              - …
            - `widthPercent` number
            - `crop` 'none' | 'square' | 'circle'
            - `fillColumn` boolean
          - `content` BroadcastEmailNode[]
          - `text` string
          - `marks` BroadcastEmailMark[]
            - `type` 'bold' | 'italic' | 'strike' | 'underline' | 'link' | 'textStyle' | 'highlight', required
            - `attrs` object
              - …
        - `text` string
        - `marks` BroadcastEmailMark[]
          - `type` 'bold' | 'italic' | 'strike' | 'underline' | 'link' | 'textStyle' | 'highlight', required
          - `attrs` object
            - `href` string
            - `color` string
            - `fontSize` string
      - `status` 'Draft' | 'Published', required
      - `delayValue` number, required
      - `delayUnit` 'minute' | 'hour' | 'day', required
      - `sendOnWeekdays` string[], required
      - `audienceMode` 'all' | 'include' | 'exclude'
      - `audienceDefinition` AudienceDefinition
        - `match` 'all' | 'any', required
        - `groups` AudienceConditionGroup[], required
          - `id` string, required
          - `match` 'all' | 'any', required
          - `conditions` AudienceCondition[], required
            - `id` string, required
            - `field` 'subscriber_status' | 'country' | 'segment' | 'tag' | 'sequence' | 'form' | 'custom_field' | 'email_opened' | 'email_unsubscribed' | 'magic_link_clicked', required
            - `operator` 'is' | 'is_not' | 'has_any_of' | 'has_none_of' | 'is_active_in_any_of' | 'is_not_active_in_any_of' | 'has_completed_any_of' | 'has_not_completed_any_of' | 'has_ever_been_in_any_of' | 'has_never_been_in_any_of' | 'contains' | 'does_not_contain' | 'is_empty' | 'is_not_empty' | 'before' | 'after' | 'on' | 'in_last_days' | 'greater_than' | 'less_than' | 'in_region' | 'not_in_region', required
            - `value` union
              - …
            - `customFieldId` string, nullable
      - `stats` EmailEngagementStats
        - `recipientCount` integer, required
        - `engagedCount` integer
        - `openedCount` integer, required
        - `clickedCount` integer, required
        - `clickedSubscriberCount` integer
        - `unsubscribedCount` integer, required
        - `bouncedCount` integer
        - `complainedCount` integer
        - `sentCountsByDay` object
    - `defaultTemplateId` string, nullable
    - `sendOnWeekdays` string[]
    - `excludeAudienceDefinition` AudienceDefinition
      - `match` 'all' | 'any', required
      - `groups` AudienceConditionGroup[], required
        - `id` string, required
        - `match` 'all' | 'any', required
        - `conditions` AudienceCondition[], required
          - `id` string, required
          - `field` 'subscriber_status' | 'country' | 'segment' | 'tag' | 'sequence' | 'form' | 'custom_field' | 'email_opened' | 'email_unsubscribed' | 'magic_link_clicked', required
          - `operator` 'is' | 'is_not' | 'has_any_of' | 'has_none_of' | 'is_active_in_any_of' | 'is_not_active_in_any_of' | 'has_completed_any_of' | 'has_not_completed_any_of' | 'has_ever_been_in_any_of' | 'has_never_been_in_any_of' | 'contains' | 'does_not_contain' | 'is_empty' | 'is_not_empty' | 'before' | 'after' | 'on' | 'in_last_days' | 'greater_than' | 'less_than' | 'in_region' | 'not_in_region', required
          - `value` union
            - string
            - number
            - boolean
            - string[]
          - `customFieldId` string, nullable
    - `restartSequenceForCompletedSubscribers` boolean
    - `sendNewEmailsToCompletedSubscribers` boolean

## Response `200`

Successful response

- object
  - `data` Sequence, required
    - `self` string, required: Stable relative Public API path for retrieving this resource.
    - `id` string, required
    - `name` string, required
    - `status` 'running' | 'paused', required
    - `is_updating` boolean, required: True while Mailrith updates existing Subscriber progress after a structural Sequence change.
    - `connection_id` string, nullable, required
    - `from_name` string, nullable, required
    - `from_email` string, nullable, required
    - `reply_to_email` string, nullable, required
    - `track_opens` boolean, required
    - `track_clicks` boolean, required
    - `utm_source` string, nullable, required
    - `utm_medium` string, nullable, required
    - `utm_campaign` string, nullable, required
    - `utm_term` string, nullable, required
    - `utm_content` string, nullable, required
    - `definition` SequenceDefinition, required
      - `emails` SequenceEmail[], required
        - `id` string, required
        - `subject` string, required: For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback="friend"] or [Subscriber_Email, fallback=""]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.
        - `previewText` string, nullable, required
        - `body` string: Rendered HTML returned by Mailrith. Agents should send bodyDocument when creating or updating a Sequence.
        - `bodyDocument` BroadcastEmailDocument, required
          - `type` 'doc' | 'paragraph' | 'heading' | 'text' | 'hardBreak' | 'bulletList' | 'orderedList' | 'listItem' | 'blockquote' | 'emailSection' | 'emailSectionColumn' | 'emailButton' | 'image' | 'horizontalRule', required
          - `attrs` object
            - `id` string
            - `level` 1 | 2 | 3
            - `textAlign` 'left' | 'center' | 'right' | 'justify'
            - `columns` 1 | 2 | 3
            - `width` 'default' | 'large' | 'full' | 'fit'
            - `backgroundColor` string
            - `blockquoteBorderColor` string
            - `linkColor` string
            - `layoutAlignment` 'left' | 'center'
            - `backgroundImageUrl` string
            - `margin` 'none' | 'normal' | 'large'
            - `padding` 'none' | 'normal' | 'large'
            - `borderColor` string
            - `borderWidth` 'none' | 'normal' | 'large'
            - `borderRadius` 'none' | 'normal' | 'small' | 'large' | 'full'
            - `verticalAlign` 'top' | 'middle' | 'bottom'
            - `href` string
            - `textColor` string
            - `size` 'small' | 'medium' | 'large'
            - `align` 'left' | 'center' | 'right'
            - `label` string
            - `src` string
            - `alt` string
            - `title` string
            - `caption` string
            - `source` 'unsplash'
            - `unsplash` object
              - …
            - `widthPercent` number
            - `crop` 'none' | 'square' | 'circle'
            - `fillColumn` boolean
          - `content` BroadcastEmailNode[]
            - `type` 'doc' | 'paragraph' | 'heading' | 'text' | 'hardBreak' | 'bulletList' | 'orderedList' | 'listItem' | 'blockquote' | 'emailSection' | 'emailSectionColumn' | 'emailButton' | 'image' | 'horizontalRule', required
            - `attrs` object
              - …
            - `content` BroadcastEmailNode[]
            - `text` string
            - `marks` BroadcastEmailMark[]
              - …
          - `text` string
          - `marks` BroadcastEmailMark[]
            - `type` 'bold' | 'italic' | 'strike' | 'underline' | 'link' | 'textStyle' | 'highlight', required
            - `attrs` object
              - …
        - `status` 'Draft' | 'Published', required
        - `delayValue` number, required
        - `delayUnit` 'minute' | 'hour' | 'day', required
        - `sendOnWeekdays` string[], required
        - `audienceMode` 'all' | 'include' | 'exclude'
        - `audienceDefinition` AudienceDefinition
          - `match` 'all' | 'any', required
          - `groups` AudienceConditionGroup[], required
            - `id` string, required
            - `match` 'all' | 'any', required
            - `conditions` AudienceCondition[], required
              - …
        - `stats` EmailEngagementStats
          - `recipientCount` integer, required
          - `engagedCount` integer
          - `openedCount` integer, required
          - `clickedCount` integer, required
          - `clickedSubscriberCount` integer
          - `unsubscribedCount` integer, required
          - `bouncedCount` integer
          - `complainedCount` integer
          - `sentCountsByDay` object
      - `defaultTemplateId` string, nullable
      - `sendOnWeekdays` string[]
      - `excludeAudienceDefinition` AudienceDefinition
        - `match` 'all' | 'any', required
        - `groups` AudienceConditionGroup[], required
          - `id` string, required
          - `match` 'all' | 'any', required
          - `conditions` AudienceCondition[], required
            - `id` string, required
            - `field` 'subscriber_status' | 'country' | 'segment' | 'tag' | 'sequence' | 'form' | 'custom_field' | 'email_opened' | 'email_unsubscribed' | 'magic_link_clicked', required
            - `operator` 'is' | 'is_not' | 'has_any_of' | 'has_none_of' | 'is_active_in_any_of' | 'is_not_active_in_any_of' | 'has_completed_any_of' | 'has_not_completed_any_of' | 'has_ever_been_in_any_of' | 'has_never_been_in_any_of' | 'contains' | 'does_not_contain' | 'is_empty' | 'is_not_empty' | 'before' | 'after' | 'on' | 'in_last_days' | 'greater_than' | 'less_than' | 'in_region' | 'not_in_region', required
            - `value` union
              - …
            - `customFieldId` string, nullable
      - `restartSequenceForCompletedSubscribers` boolean
      - `sendNewEmailsToCompletedSubscribers` boolean
    - `subscriber_count` integer, required
    - `open_rate` integer, required
    - `click_rate` integer, required
    - `unsubscribed_count` integer, required
    - `bounced_count` integer, required
    - `complained_count` integer, required
    - `send_progress` BroadcastSendProgress
      - `run_id` string, required
      - `phase` 'preparing' | 'sending' | 'paused' | 'canceling' | 'sent' | 'sent_with_errors' | 'canceled' | 'failed', required
      - `selected` integer, required
      - `materialized` integer, required
      - `sent` integer, required
      - `accepted` integer, required
      - `skipped` integer, required
      - `retrying` integer, required
      - `permanent_failed` integer, required
      - `unknown` integer, required
      - `canceled` integer, required
      - `percent_complete` number, required
      - `effective_rate` number, required
      - `provider_limited_rate` number, nullable, required
      - `provider` string, nullable, required: The email delivery provider used by this send.
      - `estimated_completion` string, date-time, nullable, required
      - `estimated_completion_basis` 'current-rate' | 'provider-quota', nullable, required: Whether the estimate uses only the current rate or also includes known provider quota windows.
      - `last_progress_at` string, date-time, nullable, required
      - `pause_reason` string, nullable, required
      - `next_retry_at` string, date-time, nullable, required
      - `next_retry_action` 'resume' | 'recheck', nullable, required: Whether the next time is a known quota reset or another connection check.
      - `pause_message` string, nullable, required
      - `terminal` boolean, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: Request is invalid
- `404`: Resource not found
- `409`: A running Sequence must be paused before it can be updated. Before changing a running Sequence, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Sequence, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate a Sequence that was not already running.

---

[API](https://skmtc.dev/mailrith/apis/mailrith-api.md) · [All operations](https://skmtc.dev/mailrith/apis/mailrith-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailrith/apis/mailrith-api/revisions/41f09536f2da?raw)