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

# List broadcasts

Retrieves a list of broadcasts with pagination and optional filtering by status, name and start date. Supports fetching template details for each variation, and the number of broadcasts in each status. Requires the broadcasts read permission.

## 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
  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.list:
    get:
      summary: List broadcasts
      description: Retrieves a list of broadcasts with pagination and optional
        filtering by status, name and start date. Supports fetching template
        details for each variation, and the number of broadcasts in each status.
        Requires the broadcasts read permission.
      operationId: listBroadcasts
      security:
        - BearerAuth: []
      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
          description: "Filter broadcasts by status: one status, or several separated by
            commas. Each one is draft, scheduled, processing, paused, processed,
            cancelled, failed, testing, test_completed or winner_selected; any
            other value is refused with 400."
          example: processing,paused
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Keep the broadcasts whose name contains this text, ignoring case.
            Leading and trailing spaces are ignored.
          example: autumn
        - name: started_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Keep the broadcasts that started sending at or after this RFC 3339
            date-time. A broadcast that never started is left out. Applies to
            the rows, total_count and status_counts. An unreadable value is
            refused with 400.
          example: 2026-10-13T00:00:00Z
        - name: with_status_counts
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Return status_counts, the number of broadcasts in each status. The
            counts follow search and started_after but not status, so each
            status tab has its own number. A value that is not a boolean is
            refused with 400.
          example: true
        - 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"
        "403":
          description: Forbidden - missing required permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "Insufficient permissions: read access to broadcasts required"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Failed to list broadcasts
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.
    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
        status_counts:
          type: object
          description: Returned only with with_status_counts=true, always an object then.
            The number of broadcasts in each status, following search and
            started_after but not status. A status no broadcast has is absent.
          additionalProperties:
            type: integer
          example:
            draft: 3
            processed: 12
            paused: 1
    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
    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
````
