> ## Documentation Index
> Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Broadcasts

> Create one-time audience emails for a Segment.

Use `broadcasts.create` when your backend needs to create a one-time email campaign for a saved Segment.

The route is `POST /api/v1/broadcasts`. It accepts a Resend-style payload with `segmentKey`, `from`, `subject`, and `html`/`text`. Segmentflow creates a saved Email Template from the inline content, creates a Broadcast linked to the Segment, and returns the Broadcast id.

You can also pass `templateKey` to reuse an existing Segmentflow Email Template instead of inline content. `segmentId` and `templateId` remain available as advanced fallbacks.

Reusable Email Templates stay unchanged when you create or edit a Broadcast draft from them. Segmentflow creates a Broadcast-specific Template Snapshot for the draft/send instance, so multiple Broadcasts can start from the same base Template without overwriting one another.

```ts theme={null}
import { Segmentflow } from "@segmentflow/segmentflow-typescript";

const client = new Segmentflow({ apiKey: process.env.SEGMENTFLOW_API_KEY });

const draft = await client.v1.broadcasts.create({
  segmentKey: "vip-customers",
  from: "Acme <news@example.com>",
  subject: "hello world",
  html: "Hi there, here is this week's update.",
});
```

Use `broadcasts.retrieve` to poll a Broadcast status handle and `broadcasts.stats` to read aggregate delivery stats:

```ts theme={null}
import Segmentflow from "@segmentflow/segmentflow-typescript";

const client = new Segmentflow({ apiKey: process.env.SEGMENTFLOW_API_KEY });

const broadcast = await client.v1.broadcasts.retrieve("broadcast_123");
const stats = await client.v1.broadcasts.stats("broadcast_123");
```

Set `send: true` to start the Broadcast immediately. To schedule it, combine `send: true` with `scheduledAt`.

```ts theme={null}
await client.v1.broadcasts.create({
  segmentKey: "vip-customers",
  from: "Acme <news@example.com>",
  subject: "hello world",
  html: "Hi there, here is this week's update.",
  send: true,
  scheduledAt: "in 1 hour",
});
```

`topicId` maps to Segmentflow's Email SubscriptionGroup id and is required before a Broadcast can be sent.