> ## 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.

# Which API should I use?

> Choose between emails.send, emails.batchSend, events.track, journeys.trigger, Broadcasts, and Newsletter Issues.

Start with the job your backend or marketing team is trying to do. Segmentflow keeps precise domain resources underneath each job, so the right API depends on whether you are sending one expected email, recording a business event, starting an automation, or preparing audience-based email.

## Quick decision table

| Job                                                  | Use                | Segmentflow domain term                                | Good fit                                                                                                                                                               | Not a fit                                                                                                    |
| ---------------------------------------------------- | ------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Send one email to one Profile                        | `emails.send`      | Creates one `EmailSend`                                | Password reset, order confirmation, account invite, receipt, shipping update, lead magnet delivery, product update from a saved Template or rendered JSX Email         | Multi-step automation, audience campaigns, recurring editorial sends                                         |
| Send many independent email sends                    | `emails.batchSend` | Creates many independent `EmailSend` records           | Backfilling receipts, notifying several known recipients, small server-side batches where each item has its own recipient, content source, idempotency key, and result | A campaign to a computed audience, a newsletter issue, or one shared message to a segment                    |
| Record a backend event and let active Journeys react | `events.track`     | Writes one `UserEvent` and evaluates matching Journeys | `order.created`, `trial.started`, `payment.failed`, `password_reset.requested` when Journey configuration should own routing                                           | A caller that already knows exactly which Journey must start                                                 |
| Start one named Journey directly                     | `journeys.trigger` | Starts one API-entry `Journey` run                     | Advanced integrations tightly coupled to a specific Journey id                                                                                                         | General event reporting, broad business facts, or cases where multiple Journeys may listen to the same event |
| Send one campaign to a computed audience             | Broadcasts         | `Broadcast` carrier                                    | Product announcements, sale campaigns, one-time audience sends with preview, scheduling, and dashboard confirmation                                                    | One-to-one email, per-recipient independent results, or direct SDK `send now`                                |
| Send recurring editorial content                     | Newsletter Issues  | `NewsletterIssue` carrier inside a Newsletter          | Weekly updates, content digests, recurring editorial cadence with preview, scheduling, and dashboard confirmation                                                      | Password resets, receipts, one-off promotional campaigns, or direct SDK `publish now`                        |

<Note>
  The API reference documents the current v1 launch endpoints. This guide also
  names adjacent job-oriented surfaces so you can choose the right product path
  before you design an integration.
</Note>

## One email versus a Journey

Use `emails.send` when your application already made the decision to send one message. The request creates one durable `EmailSend` from either a saved Email Template or rendered JSX Email content. Marketing-class saved Template purposes and rendered `purpose: "marketing"` or `purpose: "newsletter"` require `subscriptionGroupId`. It does not require a Journey.

```ts theme={null}
await client.v1.emails.send({
  "idempotency-key": "password-reset:req_123",
  templateKey: "password-reset",
  to: {
    email: "sam@example.com",
  },
  data: {
    firstName: "Sam",
    resetUrl: "https://app.example.com/reset?token=secret-token",
    expiresInMinutes: 30,
  },
  tracking: {
    clicks: false,
  },
});
```

Use `events.track` when the backend is reporting a fact and Segmentflow should decide what happens through active Journey configuration. The request writes a `UserEvent`; any Journey that listens for `password_reset.requested` can enroll the Profile.

```ts theme={null}
await client.v1.events.track({
  "idempotency-key": "password_reset.requested:req_123",
  event: "password_reset.requested",
  profile: {
    email: "sam@example.com",
    properties: {
      firstName: "Sam",
    },
  },
  data: {
    resetRequestId: "req_123",
    expiresInMinutes: 30,
  },
  referenceId: "req_123",
});
```

Choose the simple `emails.send` version when password reset is only one service-requested message. Choose the `events.track` version when the reset request should enter an automation, branch, wait, send follow-ups, or be handled by multiple active Journeys. Prefer a reset request id or another safe lookup value in event `data`; send raw reset tokens only when your retention policy allows them.

## Profile, send, and event data

Keep state in the bucket that matches its lifetime:

| Field                    | Use for                                                                                           | Template state                              |
| ------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `data` in `emails.send`  | One-send payload such as order totals, reset links, or invite links                               | `/data/*`                                   |
| `profile.properties`     | Durable Profile data in Profile and Event APIs, such as first name, plan, locale, or account tier | `/profile/*`                                |
| `data` in `events.track` | One-event payload such as order data, payment state, reset-request metadata, or trial details     | `/event/*` in event-triggered Journey email |

Do not copy one-time reset URLs, order line items, or event metadata into durable Profile properties unless they are truly long-lived Profile attributes.

## Bulk emails

"Bulk emails" can mean three different jobs:

| If you mean...                                                        | Use                |
| --------------------------------------------------------------------- | ------------------ |
| Many independent email sends, each with its own recipient and payload | `emails.batchSend` |
| One campaign to a computed audience or segment                        | Broadcasts         |
| One issue in a recurring editorial series                             | Newsletter Issues  |

`emails.batchSend` is not a Broadcast and not a NewsletterIssue. It creates independent `EmailSend` records, so one bad item should not redefine the whole batch. Broadcasts and Newsletter Issues are audience-send carriers with preview, scheduling, compliance, and send-safety controls.

## Audience send guardrails

Broadcasts and Newsletter Issues can fan out to a computed audience, so their first developer surface is intentionally guarded. When these surfaces are available, use developer APIs to draft, update, duplicate, preview or preflight the audience, send a single-recipient test, schedule a future send, cancel a scheduled send, inspect results, or create a dashboard confirmation handoff.

Do not expect a direct SDK or API `send now` primitive for these carriers in the first public surface. The final immediate send action stays behind an authenticated dashboard confirmation, where a human can review audience size, sender/domain readiness, consent state, and content before dispatch.

This is the main difference from `emails.batchSend`: batch email sends only the caller-enumerated items in the request, while Broadcasts and Newsletter Issues compute or manage an audience and send one shared campaign or issue to that audience.

## Naming boundary

Use email-specific names for today's email sending APIs: `emails.send`, `emails.batchSend`, Broadcasts, and Newsletter Issues.

`Messaging` is reserved for the future cross-channel product umbrella. It may eventually include email plus SMS, WhatsApp, or other channels, but it is not today's name for the email-send API.

## Related guides

<CardGroup cols={2}>
  <Card title="Emails" icon="send" href="/docs/emails">
    Send one expected email and retrieve the EmailSend status.
  </Card>

  <Card title="Events" icon="activity" href="/docs/events">
    Track server-side business events and trigger matching Journeys.
  </Card>
</CardGroup>