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

# Update a broadcast

Updates an existing broadcast. Only broadcasts in draft, scheduled, or paused status can be updated.

## OpenAPI

````yaml /openapi.json post /api/broadcasts.update
openapi: 3.0.3
info:
  title: Notifuse API
  description: API for Notifuse - a transactional email and newsletter management platform
  version: 1.0.0
  contact:
    name: Notifuse Support
    url: https://www.notifuse.com/support
    email: hello@notifuse.com
  license:
    name: BUSL-1.1
    url: https://github.com/Notifuse/notifuse/blob/main/LICENSE
servers:
  - url: https://{notifuseDomain}
    description: Customer-specific Notifuse API server
    variables:
      notifuseDomain:
        description: Your unique Notifuse domain
        default: demo.notifuse.com
security: []
paths:
  /api/broadcasts.update:
    post:
      summary: Update a broadcast
      description: Updates an existing broadcast. Only broadcasts in draft, scheduled,
        or paused status can be updated.
      operationId: updateBroadcast
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateBroadcastRequest"
      responses:
        "200":
          description: Broadcast updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  broadcast:
                    $ref: "#/components/schemas/Broadcast"
        "400":
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidStatus:
                  value:
                    error: "cannot update broadcast with status: sending"
        "401":
          description: Unauthorized - invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Broadcast not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Broadcast not found
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  schemas:
    AudienceSettings:
      type: object
      required:
        - list
      properties:
        list:
          type: string
          description: List ID to send to
          example: newsletter
        segments:
          type: array
          description: Optional segment IDs to filter recipients
          items:
            type: string
          example:
            - premium_users
        exclude_unsubscribed:
          type: boolean
          default: true
          description: Whether to exclude the list's unsubscribed contacts. Omitting the
            key excludes them; send false to mail them too, e.g. for a legal
            notice. With false the emails carry no List-Unsubscribe and
            List-Unsubscribe-Post headers. Bounced and complained contacts are
            never mailed, whatever this value.
          example: true
    AudienceSettingsPatch:
      type: object
      description: "The audience keys a broadcasts.update body carries. Same fields as
        AudienceSettings, but none of them is required: each key the body names
        replaces the stored value and each key it leaves out keeps it."
      properties:
        list:
          type: string
          description: List ID to send to. Omit to keep the stored list.
          example: newsletter
        segments:
          type: array
          description: Segment IDs to filter recipients. Omit to keep the stored segments;
            send an empty array to remove segment targeting and send to the
            whole list.
          items:
            type: string
          example:
            - premium_users
        exclude_unsubscribed:
          type: boolean
          description: Whether to exclude the list's unsubscribed contacts. Omit to keep
            the stored value; send false to mail them too, in emails without the
            List-Unsubscribe and List-Unsubscribe-Post headers. Bounced and
            complained contacts are never mailed, whatever this value.
          example: true
    Broadcast:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the broadcast
          example: broadcast_12345
        workspace_id:
          type: string
          description: The ID of the workspace
          example: ws_1234567890
        name:
          type: string
          description: Name of the broadcast
          example: Spring Newsletter 2024
          maxLength: 255
        channel_type:
          type: string
          description: Communication channel type
          example: email
        status:
          type: string
          enum:
            - draft
            - scheduled
            - processing
            - paused
            - processed
            - cancelled
            - failed
            - testing
            - test_completed
            - winner_selected
          description: Current status of the broadcast
          example: draft
        audience:
          $ref: "#/components/schemas/AudienceSettings"
        schedule:
          $ref: "#/components/schemas/ScheduleSettings"
        test_settings:
          $ref: "#/components/schemas/BroadcastTestSettings"
        utm_parameters:
          $ref: "#/components/schemas/UTMParameters"
        data_feed:
          $ref: "#/components/schemas/DataFeedSettings"
        metadata:
          type: object
          additionalProperties: true
          description: Custom metadata for the broadcast
        winning_template:
          type: string
          nullable: true
          description: ID of the winning template variation
          example: template_winner
        test_sent_at:
          type: string
          format: date-time
          nullable: true
          description: When the A/B test was sent
        winner_sent_at:
          type: string
          format: date-time
          nullable: true
          description: When the winning variation was sent
        enqueued_count:
          type: integer
          description: Number of emails added to the queue by orchestrator
          example: 1000
        test_phase_recipient_count:
          type: integer
          description: Number of recipients in test phase
        winner_phase_recipient_count:
          type: integer
          description: Number of recipients in winner phase
        test_paused_seconds:
          type: integer
          description: Seconds an A/B test waiting for its winner spent paused. The
            automatic winner is picked once the test duration has passed without
            them. Omitted when 0.
          example: 3600
        created_at:
          type: string
          format: date-time
          description: When the broadcast was created
        updated_at:
          type: string
          format: date-time
          description: When the broadcast was last updated
        started_at:
          type: string
          format: date-time
          nullable: true
          description: When the broadcast started sending
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: When the broadcast completed sending
        cancelled_at:
          type: string
          format: date-time
          nullable: true
          description: When the broadcast was cancelled
        paused_at:
          type: string
          format: date-time
          nullable: true
          description: When the broadcast was paused
        pause_reason:
          type: string
          nullable: true
          description: Reason for pausing the broadcast
        tracking_mode:
          type: string
          enum:
            - inherit
            - no_tracking
          description: >
            Absent or `inherit` follows the workspace tracking settings and each
            recipient's

            tracking consent (stored as absent). `no_tracking` sends every email
            without the

            open pixel and the click-tracking redirect, keeping the UTM
            parameters; it cannot be

            combined with an A/B test whose winner is sent automatically.
    BroadcastTestSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether A/B testing is enabled
          example: true
        sample_percentage:
          type: integer
          minimum: 1
          maximum: 100
          description: Percentage of audience to use for testing
          example: 20
        auto_send_winner:
          type: boolean
          description: Automatically send winning variation to remaining audience
          example: true
        auto_send_winner_metric:
          type: string
          enum:
            - open_rate
            - click_rate
          description: Metric used to determine the winner
          example: open_rate
        test_duration_hours:
          type: integer
          minimum: 1
          maximum: 168
          description: Duration of the test in hours (max 7 days)
          example: 24
        variations:
          type: array
          description: Test variations (2-8 variations allowed)
          minItems: 2
          maxItems: 8
          items:
            $ref: "#/components/schemas/BroadcastVariation"
    BroadcastVariation:
      type: object
      required:
        - template_id
      properties:
        variation_name:
          type: string
          description: Name of this variation
          example: Variation A
        template_id:
          type: string
          description: Template ID for this variation
          example: template_variant_a
        sender_id:
          type: string
          description: >
            ID of one of the marketing email integration's senders. This
            variation leaves from it

            instead of its template's sender. Omitted, the variation uses its
            template's sender:

            sending test_settings without it clears a sender chosen earlier. An
            ID that is not one

            of the integration's senders is refused with a 400. A variation
            whose chosen sender has

            since been removed from the integration is queued for no further
            recipient until another

            sender is chosen: the broadcast cannot be scheduled, cannot be
            resumed while that

            variation still has recipients to queue, and pauses at the next run
            of its sending task if

            it is queuing them. Emails already queued keep the sender they were
            queued with; nothing

            falls back to another address. Saving test_settings checks every
            variation's sender, a

            losing one's included. Two variations using the same template must
            choose the same

            sender.
          example: 3f1c2a9e-7b4d-4e1a-9c2f-5d8e6a0b1c3d
        metrics:
          $ref: "#/components/schemas/VariationMetrics"
        template:
          type: object
          nullable: true
          description: Full template object (populated when with_templates=true)
    DataFeedHeader:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: HTTP header name
          example: Authorization
        value:
          type: string
          description: HTTP header value
          example: Bearer token123
    DataFeedSettings:
      type: object
      description: Configuration for external data feeds
      properties:
        global_feed:
          $ref: "#/components/schemas/GlobalFeedSettings"
        global_feed_data:
          type: object
          additionalProperties: true
          description: Cached data from the global feed (populated after fetch)
        global_feed_fetched_at:
          type: string
          format: date-time
          nullable: true
          description: When the global feed was last fetched
        recipient_feed:
          $ref: "#/components/schemas/RecipientFeedSettings"
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    GlobalFeedSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the global data feed is enabled
          example: true
        url:
          type: string
          description: URL endpoint to fetch global data from (must be HTTPS)
          example: https://api.example.com/broadcast-data
        headers:
          type: array
          description: Custom HTTP headers to include in the request
          items:
            $ref: "#/components/schemas/DataFeedHeader"
    RecipientFeedSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the per-recipient data feed is enabled
          example: true
        url:
          type: string
          description: URL endpoint to fetch per-recipient data from (must be HTTPS)
          example: https://api.example.com/recipient-data
        headers:
          type: array
          description: Custom HTTP headers to include in the request
          items:
            $ref: "#/components/schemas/DataFeedHeader"
    ScheduleSettings:
      type: object
      description: >
        Schedule settings for a broadcast. Note: When a broadcast is first
        created,

        these fields are empty/false. Use the /api/broadcasts.schedule endpoint
        to

        configure scheduling.
      properties:
        is_scheduled:
          type: boolean
          description: Whether the broadcast is scheduled (false after creation, set via
            broadcasts.schedule)
          example: false
        scheduled_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Scheduled date in YYYY-MM-DD format
          example: 2024-03-15
        scheduled_time:
          type: string
          pattern: ^\d{2}:\d{2}$
          description: Scheduled time in HH:MM format
          example: 10:30
        timezone:
          type: string
          description: IANA timezone
          example: America/New_York
        use_recipient_timezone:
          type: boolean
          description: Send at scheduled time in each recipient's timezone
          example: false
    UTMParameters:
      type: object
      properties:
        source:
          type: string
          description: UTM source parameter
          example: newsletter
        medium:
          type: string
          description: UTM medium parameter
          example: email
        campaign:
          type: string
          description: UTM campaign parameter
          example: spring_2024
        term:
          type: string
          description: UTM term parameter
        content:
          type: string
          description: UTM content parameter
    UpdateBroadcastRequest:
      type: object
      description: Partial update of a broadcast. workspace_id, id and name are always
        applied; audience is merged one key at a time, and schedule,
        test_settings, utm_parameters, metadata, data_feed and tracking_mode
        keep their stored value when the key is left out of the body. Send the
        key to change it — including an explicitly empty object to clear it.
      required:
        - workspace_id
        - id
        - name
      properties:
        workspace_id:
          type: string
          description: The ID of the workspace
          example: ws_1234567890
        id:
          type: string
          description: ID of the broadcast to update
          example: broadcast_12345
        name:
          type: string
          description: Name of the broadcast
          example: Spring Newsletter 2024
          maxLength: 255
        audience:
          allOf:
            - $ref: "#/components/schemas/AudienceSettingsPatch"
          description: Merged into the stored audience one key at a time, so a body naming
            only list retargets the broadcast without dropping its segments or
            its exclusion of unsubscribed contacts. Omit the whole object to
            leave the audience untouched.
        schedule:
          allOf:
            - $ref: "#/components/schemas/ScheduleSettings"
          description: Omit to keep the stored schedule. Sending it replaces the schedule
            wholesale, so a body carrying an empty or partial object clears
            is_scheduled — which a later resume reads to decide between
            restoring the schedule and sending now.
        test_settings:
          allOf:
            - $ref: "#/components/schemas/BroadcastTestSettings"
          description: Omit to keep the stored test settings. These hold the broadcast's
            template variations, so sending a partial object detaches its
            templates.
        utm_parameters:
          allOf:
            - $ref: "#/components/schemas/UTMParameters"
          description: Omit to keep the stored UTM parameters; send an empty object to
            clear them.
        data_feed:
          allOf:
            - $ref: "#/components/schemas/DataFeedSettings"
          description: Omit to keep the stored data feed settings and their last fetched
            data.
        metadata:
          type: object
          additionalProperties: true
          description: Custom metadata for the broadcast. Omit to keep the stored
            metadata; send an empty object to clear it.
        tracking_mode:
          type: string
          enum:
            - inherit
            - no_tracking
          description: Omit to keep the stored mode. Can be changed only while the
            broadcast is a draft or scheduled. See `Broadcast.tracking_mode`.
    VariationMetrics:
      type: object
      properties:
        recipients:
          type: integer
          description: Number of recipients
        delivered:
          type: integer
          description: Number of delivered messages
        opens:
          type: integer
          description: Number of opens
        clicks:
          type: integer
          description: Number of clicks
        bounced:
          type: integer
          description: Number of bounces
        complained:
          type: integer
          description: Number of complaints
        unsubscribed:
          type: integer
          description: Number of unsubscribes
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API token for authentication
````
