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

# List broadcasts

> Retrieves a list of broadcasts with pagination and optional filtering by status. Supports fetching template details for each variation.



## OpenAPI

````yaml /openapi.json get /api/broadcasts.list
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
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.list:
    get:
      summary: List broadcasts
      description: >-
        Retrieves a list of broadcasts with pagination and optional filtering by
        status. Supports fetching template details for each variation.
      operationId: listBroadcasts
      parameters:
        - name: workspace_id
          in: query
          required: true
          schema:
            type: string
          description: The ID of the workspace
          example: ws_1234567890
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - draft
              - scheduled
              - sending
              - paused
              - sent
              - cancelled
              - failed
              - testing
              - test_completed
              - winner_selected
          description: Filter broadcasts by status
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
          description: Maximum number of broadcasts to return
          example: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of broadcasts to skip for pagination
          example: 0
        - name: with_templates
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include full template details for each variation
          example: false
      responses:
        '200':
          description: List of broadcasts retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastListResponse'
        '400':
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: workspace_id is required
        '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 list broadcasts
      security:
        - BearerAuth: []
components:
  schemas:
    BroadcastListResponse:
      type: object
      properties:
        broadcasts:
          type: array
          description: List of broadcasts
          items:
            $ref: '#/components/schemas/Broadcast'
        total_count:
          type: integer
          description: Total number of broadcasts matching the query
          example: 45
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    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
        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
    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
          description: Whether to exclude unsubscribed contacts
          example: true
    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
    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'
    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
    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'
    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
        metrics:
          $ref: '#/components/schemas/VariationMetrics'
        template:
          type: object
          nullable: true
          description: Full template object (populated when with_templates=true)
    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'
    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
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API token for authentication

````