Skip to main content
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

JobUseSegmentflow domain termGood fitNot a fit
Send one expected email to one Profileemails.sendCreates one EmailSendPassword reset, order confirmation, account invite, receipt, shipping updateMulti-step automation, audience campaigns, recurring editorial sends
Send many independent email sendsemails.batchSendCreates many independent EmailSend recordsBackfilling receipts, notifying several known recipients, small server-side batches where each item has its own recipient, payload, idempotency key, and resultA campaign to a computed audience, a newsletter issue, or one shared message to a segment
Record a backend event and let active Journeys reactevents.trackWrites one UserEvent and evaluates matching Journeysorder.created, trial.started, payment.failed, password_reset.requested when Journey configuration should own routingA caller that already knows exactly which Journey must start
Start one named Journey directlyjourneys.triggerStarts one API-entry Journey runAdvanced integrations tightly coupled to a specific Journey idGeneral event reporting, broad business facts, or cases where multiple Journeys may listen to the same event
Send one campaign to a computed audienceBroadcastsBroadcast carrierProduct announcements, sale campaigns, one-time audience sends with preview, scheduling, and dashboard confirmationOne-to-one email, per-recipient independent results, or direct SDK send now
Send recurring editorial contentNewsletter IssuesNewsletterIssue carrier inside a NewsletterWeekly updates, content digests, recurring editorial cadence with preview, scheduling, and dashboard confirmationPassword 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 expected message. The request creates one durable EmailSend; it does not require a Journey. 
await client.v1.emails.send(
  {
    templateId: "d0df2e4d-8e44-4792-b2d5-8d3f2ea3d54b",
    to: {
      email: "sam@example.com",
    },
    data: {
      firstName: "Sam",
      resetUrl: "https://app.example.com/reset?token=secret-token",
      expiresInMinutes: 30,
    },
    tracking: {
      clicks: false,
    },
  },
  {
    headers: { "Idempotency-Key": "password-reset:req_123" },
  },
);
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(
  {
    event: "password_reset.requested",
    profile: {
      email: "sam@example.com",
      properties: {
        firstName: "Sam",
      },
    },
    data: {
      resetRequestId: "req_123",
      expiresInMinutes: 30,
    },
    referenceId: "req_123",
  },
  {
    headers: { "Idempotency-Key": "password_reset.requested: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:
FieldUse forTemplate state
data in emails.sendOne-send payload such as order totals, reset links, or invite links/data/*
profile.propertiesDurable Profile data in Profile and Event APIs, such as first name, plan, locale, or account tier/profile/*
data in events.trackOne-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 payloademails.batchSend
One campaign to a computed audience or segmentBroadcasts
One issue in a recurring editorial seriesNewsletter 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.