Broadcasts

Send bulk emails to your contacts or segments. Broadcasts support topic targeting, A/B testing, test sends, scheduling, and cancellation.

POST

/broadcasts

Create a new broadcast. Specify recipients via segment, optionally target a subscription topic, and configure A/B testing.

json

{
  "name": "March Newsletter",
  "from": "Newsletter <newsletter@yourdomain.com>",
  "subject": "What's new in March",
  "html": "<h1>March Updates</h1><p>Here's what happened...</p>",
  "text": "March Updates: Here's what happened...",
  "reply_to": "hello@yourdomain.com",
  "segment_id": "seg_abc123def456",
  "scheduled_at": "2026-03-25T09:00:00.000Z"
}

GET

/broadcasts

List all broadcasts with pagination.

json

{
  "broadcasts": [
    {
      "id": "brd_abc123def456ghi789",
      "name": "March Newsletter",
      "status": "sent",
      "recipients": 1250,
      "delivered": 1230,
      "opened": 456,
      "clicked": 89,
      "sent_at": "2026-03-25T09:00:00.000Z",
      "created_at": "2026-03-23T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 24,
    "page": 1,
    "per_page": 20,
    "total_pages": 2
  }
}

GET

/broadcasts/:id

Retrieve a single broadcast with delivery statistics and configuration.

json

{
  "id": "brd_abc123def456ghi789",
  "name": "March Newsletter",
  "status": "sent",
  "from": "Newsletter <newsletter@yourdomain.com>",
  "subject": "What's new in March",
  "html": "<h1>March Updates</h1><p>Here's what happened...</p>",
  "segment_id": "seg_abc123def456",
  "recipients": 1250,
  "delivered": 1230,
  "bounced": 12,
  "opened": 456,
  "clicked": 89,
  "unsubscribed": 3,
  "sent_at": "2026-03-25T09:00:00.000Z",
  "created_at": "2026-03-23T10:00:00.000Z"
}

PATCH

/broadcasts/:id

Update a draft broadcast. All fields are optional. Only works for broadcasts in 'draft' status.

json

{
  "subject": "Updated: What's new in March",
  "html": "<h1>Updated March Newsletter</h1><p>New content here.</p>",
  "scheduled_at": "2026-03-26T09:00:00.000Z"
}

POST

/broadcasts/:id/send

Send a draft broadcast immediately. The broadcast must be in 'draft' status.

json

{
  "id": "brd_abc123def456ghi789",
  "status": "sending",
  "recipients": 1250
}

POST

/broadcasts/:id/test

Send a test copy of the broadcast to a specific email address before sending to all recipients.

json

{
  "email": "test@yourdomain.com"
}

POST

/broadcasts/:id/cancel

Cancel a sending or scheduled broadcast. Emails already delivered cannot be recalled.

json

{
  "id": "brd_abc123def456ghi789",
  "status": "cancelled"
}

GET

/broadcasts/:id/variants

List A/B test variants for a broadcast. Only available when the broadcast was created with A/B testing.

json

{
  "variants": [
    {
      "id": 1,
      "name": "A",
      "subject": "What's new in March",
      "weight": 50,
      "delivered_count": 625,
      "opened_count": 230,
      "clicked_count": 45
    },
    {
      "id": 2,
      "name": "B",
      "subject": "March product updates",
      "weight": 50,
      "delivered_count": 625,
      "opened_count": 280,
      "clicked_count": 52
    }
  ]
}

GET

/broadcasts/:id/variant-stats

Get performance statistics for A/B test variants, including which variant won.

json

{
  "variants": [
    {
      "id": 1,
      "name": "A",
      "subject": "What's new in March",
      "weight": 50,
      "delivered_count": 625,
      "opened_count": 230,
      "clicked_count": 45
    },
    {
      "id": 2,
      "name": "B",
      "subject": "March product updates",
      "weight": 50,
      "delivered_count": 625,
      "opened_count": 280,
      "clicked_count": 52
    }
  ],
  "winner": {
    "variant_id": 2,
    "metric": "open_rate"
  }
}

A/B Testing

Test different subject lines and content by creating broadcasts with A/B test variants. PostStack sends each variant to a sample of your audience, measures performance, then automatically sends the winning variant to the rest.

typescript

const { broadcast } = await poststack.broadcasts.create({
  name: 'A/B Test: Subject Lines',
  from: 'Newsletter <newsletter@yourdomain.com>',
  subject: 'Default subject (used as fallback)',
  html: '<p>Newsletter content</p>',
  segment_id: 'seg_abc123def456',
  ab_test: {
    variants: [
      {
        name: 'A',
        subject: "What's new in March",
        weight: 50,
      },
      {
        name: 'B',
        subject: 'March product updates',
        weight: 50,
      },
    ],
    test_sample_size: 20,      // Send to 20% of audience first
    test_duration_minutes: 120, // Wait 2 hours before picking winner
  },
});

await poststack.broadcasts.send(broadcast.id);

Parameter	Description
`variants`	2-5 variants, each with name (max 10 chars), subject, optional html/text, and weight (1-100)
`test_sample_size`	Percentage of audience for the test phase (5-50%, default: 20%)
`test_duration_minutes`	How long to wait before picking a winner (30-1440 minutes, default: 120)

Topic Targeting

Broadcasts can be targeted to contacts subscribed to a specific subscription topic. When a topic_id is set, only contacts who have opted into that topic will receive the broadcast. This can be combined with segment_id for more granular targeting.

typescript

// Send only to contacts in the "Pro Users" segment
// who are subscribed to the "Product Updates" topic
const { broadcast } = await poststack.broadcasts.create({
  name: 'New Feature Announcement',
  from: 'updates@yourdomain.com',
  subject: 'New feature: Workflows',
  html: '<p>We just launched workflows!</p>',
  segment_id: 'seg_pro_users',
  topic_id: 1,
});

await poststack.broadcasts.send(broadcast.id);