---
title: "Update a broadcast"
method: PUT
path: "/v1/broadcasts/{broadcast_id}"
tags: ["Broadcasts"]
---

# Update a broadcast

`PUT /v1/broadcasts/{broadcast_id}`

## Request

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

Updates an existing Broadcast draft. Scheduled, running, completed, and failed Broadcasts cannot be changed here. Before changing a scheduled Broadcast, read it by ID and retain its scheduled_at in the current task only. If the saved time is no longer safely in the future, ask the user for a new time before unscheduling. Otherwise unschedule it, apply the update, reschedule it for the same time, and verify both status and scheduled_at. If the update fails after unscheduling, restore the unchanged Broadcast to the same future time when possible. If the schedule cannot be restored, leave it as a Draft and immediately report that it will not send; never choose a replacement time without the user.

## Path parameters

- `broadcast_id` string, required

## Request body

- BroadcastUpdateRequest
  - `subject` string: 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.
  - `preview_text` string, nullable
  - `body_document` BroadcastEmailDocument
    - `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
          - `photoId` string
          - `photographerName` string, required
          - `photographerUsername` string
          - `photographerUrl` string
          - `unsplashUrl` string
        - `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
          - `href` string
          - `color` string
          - `fontSize` string
    - `text` string
    - `marks` BroadcastEmailMark[]
      - `type` 'bold' | 'italic' | 'strike' | 'underline' | 'link' | 'textStyle' | 'highlight', required
      - `attrs` object
        - `href` string
        - `color` string
        - `fontSize` string
  - `connection_id` string, nullable
  - `reply_to_email` string, nullable
  - `audience_definition` 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
  - `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

## Response `200`

Successful response

- object
  - `data` Broadcast, required
    - `self` string, required: Stable relative Public API path for retrieving this resource.
    - `id` string, required
    - `subject` string, required
    - `preview_text` string, nullable, required
    - `body` string, required
    - `body_document` 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
            - `photoId` string
            - `photographerName` string, required
            - `photographerUsername` string
            - `photographerUrl` string
            - `unsplashUrl` string
          - `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
            - `href` string
            - `color` string
            - `fontSize` string
      - `text` string
      - `marks` BroadcastEmailMark[]
        - `type` 'bold' | 'italic' | 'strike' | 'underline' | 'link' | 'textStyle' | 'highlight', required
        - `attrs` object
          - `href` string
          - `color` string
          - `fontSize` string
    - `status` 'draft' | 'scheduled' | 'running' | 'completed' | 'failed', required
    - `scheduled_at` string, date-time, nullable, required
    - `completed_at` string, date-time, nullable, required
    - `connection_id` string, nullable, required
    - `from_name` string, nullable, required
    - `from_email` string, nullable, required
    - `reply_to_email` string, nullable, required
    - `audience_definition` AudienceDefinition, required
      - `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
    - `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
    - `recipient_count` integer, required
    - `opened_count` integer, required
    - `clicked_count` integer, required
    - `unsubscribed_count` integer, required
    - `bounced_count` integer, required
    - `complained_count` integer, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: Invalid request
- `404`: Not found
- `409`: The Broadcast must be a draft before it can be updated. Before changing a scheduled Broadcast, read it by ID and retain its scheduled_at in the current task only. If the saved time is no longer safely in the future, ask the user for a new time before unscheduling. Otherwise unschedule it, apply the update, reschedule it for the same time, and verify both status and scheduled_at. If the update fails after unscheduling, restore the unchanged Broadcast to the same future time when possible. If the schedule cannot be restored, leave it as a Draft and immediately report that it will not send; never choose a replacement time without the user.

---

[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)