Streams, audiences, and campaigns

​

Goal

​

Prerequisites

• An explicit brand and audience in the selected environment
• A verified sender domain for Live
• A saved template or a campaign preset
• Recipient consent source and timestamp evidence

​

Workflow

​

Guided campaign drafts

• Each campaign owns its content snapshot. Editing it does not change a shared template. Existing template/version API inputs remain supported.
• Draft updates use PUT /mail/campaigns/{id} with the complete draft and its revision. A stale revision returns 409; reload before deciding how to merge your edits.
• Preview and test endpoints accept data and variant (a or b); tests also accept to. Pass revision when sending or scheduling to protect the content you reviewed.
• Scheduling accepts sendAt between one minute and one year ahead. Consent and suppressions are checked again during dispatch.
• The visual editor can insert public PNG, JPEG, or GIF assets up to 5 MB after processing and a clean malware scan. URLs include the immutable version. Existing Assets quotas and policies apply.
• A/B campaigns use a deterministic audience split between 10 and 90 percent. Sent and scheduled content is locked.

​

Traffic isolation

• Transactional streams are for user or application-triggered messages.
• Broadcast streams are for one-to-many communication and require unsubscribe behavior.
• The built-in transactional and broadcast streams are protected; custom streams retain the policy of their selected type.

​

Consent-backed audience import

const brand = await stackshift.mail.brands.create({ name: 'Product' })
const audience = await stackshift.mail.audiences.create({ brandId: brand.id, name: 'Early access' })
await stackshift.mail.audiences.importDetailed(audience.id, [{
  email: 'ada@example.net',
  consentSource: 'website_waitlist',
  consentAt: '2026-08-18T10:00:00Z',
}])

​

Create and preview through the SDK

const campaign = await stackshift.mail.campaigns.create({
  name: 'Product update', audienceId: audience.id,
  from: 'hello@example.com',
  content: {
    subject: 'Our latest update', previewText: 'What changed this month',
    html: '<p>Our latest update is ready.</p>', text: 'Our latest update is ready.',
    editorMode: 'code',
  },
})
const preview = await stackshift.mail.campaigns.preview(campaign.id, {}, 'a')
console.log(preview.diagnostics)
const estimate = await stackshift.mail.campaigns.estimate(campaign.id)
console.log(estimate.recipientCount, estimate.requiredCreditKobo, estimate.blockingReasons)

​

Campaign lifecycle

• Member states are pending_confirmation, subscribed, unsubscribed, complained, and hard_bounced. Pending members cannot receive campaigns until confirmed.
• Campaign states are draft, scheduled, processing, queued, completed, failed, and blocked. A billing-blocked campaign requires a fresh approved send action.
• A queued campaign references the resulting batch for recipient-level inspection.
• Campaign delivery uses the broadcast stream, campaign tags, list-unsubscribe behavior, and deterministic member idempotency keys.

​

Expected result

​

Common failures

​

Related guides