List broadcasts

List broadcasts

curl --request GET \
  --url https://{notifuseDomain}/api/broadcasts.list \
  --header 'Authorization: Bearer <token>'

{
  "broadcasts": [
    {
      "id": "broadcast_12345",
      "workspace_id": "ws_1234567890",
      "name": "Spring Newsletter 2024",
      "channel_type": "email",
      "status": "draft",
      "audience": {
        "list": "newsletter",
        "segments": [
          "premium_users"
        ],
        "exclude_unsubscribed": true
      },
      "schedule": {
        "is_scheduled": true,
        "scheduled_date": "2024-03-15",
        "scheduled_time": "10:30",
        "timezone": "America/New_York",
        "use_recipient_timezone": false
      },
      "test_settings": {
        "enabled": true,
        "sample_percentage": 20,
        "auto_send_winner": true,
        "auto_send_winner_metric": "open_rate",
        "test_duration_hours": 24,
        "variations": [
          {
            "template_id": "template_variant_a",
            "variation_name": "Variation A",
            "metrics": {
              "recipients": 123,
              "delivered": 123,
              "opens": 123,
              "clicks": 123,
              "bounced": 123,
              "complained": 123,
              "unsubscribed": 123
            },
            "template": {}
          }
        ]
      },
      "utm_parameters": {
        "source": "newsletter",
        "medium": "email",
        "campaign": "spring_2024",
        "term": "<string>",
        "content": "<string>"
      },
      "metadata": {},
      "winning_template": "template_winner",
      "test_sent_at": "2023-11-07T05:31:56Z",
      "winner_sent_at": "2023-11-07T05:31:56Z",
      "test_phase_recipient_count": 123,
      "winner_phase_recipient_count": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "cancelled_at": "2023-11-07T05:31:56Z",
      "paused_at": "2023-11-07T05:31:56Z",
      "pause_reason": "<string>"
    }
  ],
  "total_count": 45
}

GET

api

broadcasts.list

List broadcasts

curl --request GET \
  --url https://{notifuseDomain}/api/broadcasts.list \
  --header 'Authorization: Bearer <token>'

{
  "broadcasts": [
    {
      "id": "broadcast_12345",
      "workspace_id": "ws_1234567890",
      "name": "Spring Newsletter 2024",
      "channel_type": "email",
      "status": "draft",
      "audience": {
        "list": "newsletter",
        "segments": [
          "premium_users"
        ],
        "exclude_unsubscribed": true
      },
      "schedule": {
        "is_scheduled": true,
        "scheduled_date": "2024-03-15",
        "scheduled_time": "10:30",
        "timezone": "America/New_York",
        "use_recipient_timezone": false
      },
      "test_settings": {
        "enabled": true,
        "sample_percentage": 20,
        "auto_send_winner": true,
        "auto_send_winner_metric": "open_rate",
        "test_duration_hours": 24,
        "variations": [
          {
            "template_id": "template_variant_a",
            "variation_name": "Variation A",
            "metrics": {
              "recipients": 123,
              "delivered": 123,
              "opens": 123,
              "clicks": 123,
              "bounced": 123,
              "complained": 123,
              "unsubscribed": 123
            },
            "template": {}
          }
        ]
      },
      "utm_parameters": {
        "source": "newsletter",
        "medium": "email",
        "campaign": "spring_2024",
        "term": "<string>",
        "content": "<string>"
      },
      "metadata": {},
      "winning_template": "template_winner",
      "test_sent_at": "2023-11-07T05:31:56Z",
      "winner_sent_at": "2023-11-07T05:31:56Z",
      "test_phase_recipient_count": 123,
      "winner_phase_recipient_count": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "cancelled_at": "2023-11-07T05:31:56Z",
      "paused_at": "2023-11-07T05:31:56Z",
      "pause_reason": "<string>"
    }
  ],
  "total_count": 45
}

Authorizations

Authorization

string

header

required

API token for authentication

Query Parameters

workspace_id

string

required

The ID of the workspace

status

enum<string>

Filter broadcasts by status

Available options:

draft,

scheduled,

sending,

paused,

sent,

cancelled,

failed,

testing,

test_completed,

winner_selected

limit

integer

default:50

Maximum number of broadcasts to return

offset

integer

default:0

Number of broadcasts to skip for pagination

with_templates

boolean

default:false

Include full template details for each variation

Response

List of broadcasts retrieved successfully

broadcasts

object[]

List of broadcasts

Show child attributes

broadcasts.id

string

Unique identifier for the broadcast

Example:

"broadcast_12345"

broadcasts.workspace_id

string

The ID of the workspace

Example:

"ws_1234567890"

broadcasts.name

string

Name of the broadcast

Maximum string length: 255

Example:

"Spring Newsletter 2024"

broadcasts.channel_type

string

Communication channel type

Example:

"email"

broadcasts.status

enum<string>

Current status of the broadcast

Available options:

draft,

scheduled,

sending,

paused,

sent,

cancelled,

failed,

testing,

test_completed,

winner_selected

Example:

"draft"

broadcasts.audience

object

Show child attributes

broadcasts.audience.list

string

required

List ID to send to

Example:

"newsletter"

broadcasts.audience.segments

string[]

Optional segment IDs to filter recipients

Example:

["premium_users"]

broadcasts.audience.exclude_unsubscribed

boolean

Whether to exclude unsubscribed contacts

Example:

true

broadcasts.schedule

object

Show child attributes

broadcasts.schedule.is_scheduled

boolean

Whether the broadcast is scheduled

Example:

true

broadcasts.schedule.scheduled_date

string

Scheduled date in YYYY-MM-DD format

Example:

"2024-03-15"

broadcasts.schedule.scheduled_time

string

Scheduled time in HH:MM format

Example:

"10:30"

broadcasts.schedule.timezone

string

IANA timezone

Example:

"America/New_York"

broadcasts.schedule.use_recipient_timezone

boolean

Send at scheduled time in each recipient's timezone

Example:

false

broadcasts.test_settings

object

Show child attributes

broadcasts.test_settings.enabled

boolean

Whether A/B testing is enabled

Example:

true

broadcasts.test_settings.sample_percentage

integer

Percentage of audience to use for testing

Required range: 1 <= x <= 100

Example:

20

broadcasts.test_settings.auto_send_winner

boolean

Automatically send winning variation to remaining audience

Example:

true

broadcasts.test_settings.auto_send_winner_metric

enum<string>

Metric used to determine the winner

Available options:

open_rate,

click_rate

Example:

"open_rate"

broadcasts.test_settings.test_duration_hours

integer

Duration of the test in hours (max 7 days)

Required range: 1 <= x <= 168

Example:

24

broadcasts.test_settings.variations

object[]

Test variations (2-8 variations allowed)

Required array length: 2 - 8 elements

Show child attributes

broadcasts.test_settings.variations.template_id

string

required

Template ID for this variation

Example:

"template_variant_a"

broadcasts.test_settings.variations.variation_name

string

Name of this variation

Example:

"Variation A"

broadcasts.test_settings.variations.metrics

object

Show child attributes

broadcasts.test_settings.variations.metrics.recipients

integer

Number of recipients

broadcasts.test_settings.variations.metrics.delivered

integer

Number of delivered messages

broadcasts.test_settings.variations.metrics.opens

integer

Number of opens

broadcasts.test_settings.variations.metrics.clicks

integer

Number of clicks

broadcasts.test_settings.variations.metrics.bounced

integer

Number of bounces

broadcasts.test_settings.variations.metrics.complained

integer

Number of complaints

broadcasts.test_settings.variations.metrics.unsubscribed

integer

Number of unsubscribes

broadcasts.test_settings.variations.template

object

Full template object (populated when with_templates=true)

broadcasts.utm_parameters

object

Show child attributes

broadcasts.utm_parameters.source

string

UTM source parameter

Example:

"newsletter"

broadcasts.utm_parameters.medium

string

UTM medium parameter

Example:

"email"

broadcasts.utm_parameters.campaign

string

UTM campaign parameter

Example:

"spring_2024"

broadcasts.utm_parameters.term

string

UTM term parameter

broadcasts.utm_parameters.content

string

UTM content parameter

broadcasts.metadata

object

Custom metadata for the broadcast

broadcasts.winning_template

string | null

ID of the winning template variation

Example:

"template_winner"

broadcasts.test_sent_at

string<date-time> | null

When the A/B test was sent

broadcasts.winner_sent_at

string<date-time> | null

When the winning variation was sent

broadcasts.test_phase_recipient_count

integer

Number of recipients in test phase

broadcasts.winner_phase_recipient_count

integer

Number of recipients in winner phase

broadcasts.created_at

string<date-time>

When the broadcast was created

broadcasts.updated_at

string<date-time>

When the broadcast was last updated

broadcasts.started_at

string<date-time> | null

When the broadcast started sending

broadcasts.completed_at

string<date-time> | null

When the broadcast completed sending

broadcasts.cancelled_at

string<date-time> | null

When the broadcast was cancelled

broadcasts.paused_at

string<date-time> | null

When the broadcast was paused

broadcasts.pause_reason

string | null

Reason for pausing the broadcast

total_count

integer

Total number of broadcasts matching the query

Example:

45

Import custom events Get a broadcast

⌘I

Transactional

Contacts

Lists

Custom Events

Broadcasts

Templates

Webhooks

Authorizations

Query Parameters

Response