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

# Create a broadcast

Creates a new broadcast campaign in draft status.

**Important:** Creating a broadcast does not schedule or send it. After creating the broadcast,
you must call the `/api/broadcasts.schedule` endpoint to schedule or send it immediately.

## OpenAPI

````yaml /openapi.json post /api/broadcasts.create
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.create:
    post:
      summary: Create a broadcast
      description: >
        Creates a new broadcast campaign in draft status.


        **Important:** Creating a broadcast does not schedule or send it. After
        creating the broadcast,

        you must call the `/api/broadcasts.schedule` endpoint to schedule or
        send it immediately.
      operationId: createBroadcast
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateBroadcastRequest"
      responses:
        "201":
          description: Broadcast created 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:
                missingName:
                  value:
                    error: name is required
                missingList:
                  value:
                    error: list is required
                invalidTestSettings:
                  value:
                    error: at least 2 variations are required for A/B testing
        "401":
          description: Unauthorized - invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Failed to create broadcast
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
    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)
    CreateBroadcastRequest:
      type: object
      required:
        - workspace_id
        - name
        - audience
      properties:
        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
        audience:
          $ref: "#/components/schemas/AudienceSettings"
        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
        tracking_mode:
          type: string
          enum:
            - inherit
            - no_tracking
          description: See `Broadcast.tracking_mode`.
    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
    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
````
