Broadcasts

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

POST

/broadcasts

Create a new broadcast. Specify recipients via segment and configure A/B testing. The segment_id is the numeric integer DB id (as a string), not the seg_* publicId.

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": "1",
  "scheduled_at": "2026-03-25T09:00:00.000Z"
}

GET

/broadcasts

List all broadcasts with pagination.

json

{
  "data": [
    {
      "id": "bc_abc123def456ghi789",
      "name": "March Newsletter",
      "status": "sent",
      "totalRecipients": 1250,
      "deliveredCount": 1230,
      "openedCount": 456,
      "clickedCount": 89,
      "bouncedCount": 12,
      "sentAt": "2026-03-25T09:00:00.000Z",
      "createdAt": "2026-03-23T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 24,
    "totalPages": 2
  }
}

GET

/broadcasts/:id

Retrieve a single broadcast with delivery statistics and configuration.

json

{
  "broadcast": {
    "id": "bc_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>",
    "segmentId": 1,
    "totalRecipients": 1250,
    "deliveredCount": 1230,
    "bouncedCount": 12,
    "openedCount": 456,
    "clickedCount": 89,
    "sentAt": "2026-03-25T09:00:00.000Z",
    "createdAt": "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

{
  "success": true
}

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

{
  "success": true
}

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: '1',
  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)