Which API should I use? - SegmentFlow.ai

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`

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.

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.

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.

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.

Emails

Send one expected email and retrieve the EmailSend status.

Events

Track server-side business events and trigger matching Journeys.

​Quick decision table

​One email versus a Journey

​Profile, send, and event data

​Bulk emails

​Audience send guardrails

​Naming boundary

​Related guides

Emails

Events

Quick decision table

One email versus a Journey

Profile, send, and event data

Bulk emails

Audience send guardrails

Naming boundary

Related guides