Skip to main content
SegmentFlow.ai is a customer engagement platform for sending email, tracking backend business events, and managing the content, assets, brand data, and Profiles that power those workflows. The unified v1 API is for backend integrations, CRM syncs, e-commerce workflows, and self-hosted MCP tools that need a scoped API Key instead of a dashboard session.

​
What you can do

The v1 launch surface covers these resources:
  • Profiles - list Profiles, retrieve one Profile, read subscription status, and perform scoped write operations.
  • Templates - list, read, create, update, duplicate, archive, and unarchive email Templates.
  • Assets - list image asset metadata, create asset records, request upload sessions, finalize uploads, update metadata, and delete assets.
  • Brand Kit - list and manage brand kits, start extraction jobs, read extraction progress, and update brand defaults.
  • Email sending - call emails.send to send one expected email, or emails.batchSend to create many independent expected emails, then retrieve each durable EmailSend status.
  • Events - call events.track to record one identified backend business event and trigger any matching active Journeys.
Segments, direct Journey management, Broadcasts, anonymous web routes, and the WriteKey Ingest API are not part of the v1 SDK/MCP launch surface documented here.

​
Core concepts

SegmentFlow.aiWhat it is
ProfileAn identified contact owned by your Organization.
TemplateA reusable email body with merge fields and purpose metadata.
AssetImage metadata and upload state for media used inside Templates and Brand Kit.
Brand KitLogos, colors, and sender profile defaults applied to outgoing email.
EmailSendOne expected email to one Profile from a saved Email Template.
UserEventOne tracked event, optionally used to trigger active Journeys.
Use Emails when your application already knows the recipient and business event, and you need expected email. In the SDK, emails.send creates one EmailSend; emails.batchSend creates many independent EmailSend records without turning the work into a Broadcast or Newsletter Issue. Use Events when your backend wants to report a fact and let Journey configuration decide what happens next. In the SDK, this job is events.track; the durable event record is a UserEvent. Use Which API should I use? when you are choosing between one email, batch email, event-triggered Journeys, direct Journey trigger, Broadcasts, and Newsletter Issues.

​
Quickstart

The shortest path from zero to a working request:
Sending email also requires a verified sending domain (SPF + DKIM). Read-only API calls such as Profiles, Templates, Assets, and Brand Kit reads work without one. See Sending domain for the DNS setup before you create your first EmailSend.
1

Mint an API key

In the dashboard, open Settings → API Keys, create a key with the scopes you need, and copy the value. Use the scope table in Authentication to choose the narrowest set.
2

Make your first call

List the templates in your organization:
curl https://api.segmentflow.ai/api/v1/templates \
  -H "x-api-key: sk_live_..."
3

Send an email

Send one expected email from a saved Email Template:
curl https://api.segmentflow.ai/api/v1/emails \
  -H "x-api-key: sk_live_..." \
  -H "content-type: application/json" \
  -H "Idempotency-Key: order-confirmation:ord_9421" \
  -d '{
    "templateKey": "receipt-default",
    "from": "Acme Receipts <receipts@example.com>",
    "to": {
      "email": "alex@example.com",
      "externalId": "shopify:customer_123"
    },
    "subject": "Receipt for order ord_9421",
    "replyTo": "Acme Support <support@example.com>",
    "data": {
      "orderId": "ord_9421",
      "firstName": "Alex",
      "orderTotal": "49.00"
    }
  }'
4

Track a business event

Record one backend event that may trigger matching Journeys:
curl https://api.segmentflow.ai/api/v1/events \
  -H "x-api-key: sk_live_..." \
  -H "content-type: application/json" \
  -H "Idempotency-Key: order.created:ord_9421" \
  -d '{
    "event": "order.created",
    "profile": {
      "email": "alex@example.com",
      "properties": { "firstName": "Alex" }
    },
    "data": {
      "orderId": "ord_9421",
      "orderTotal": "49.00"
    },
    "referenceId": "ord_9421"
  }'

​
Common use cases

  • Replace email from another provider. Point existing order, account, receipt, reset, and invite events at POST /emails. Use Idempotency-Key to dedupe webhook and job retries.
  • Trigger Journeys from backend events. Point backend facts at POST /events. Unknown event names are accepted and return zero Journey matches until a Journey listens for them.
  • Sync Profile context to another system. Use the Profiles endpoints with profiles:read for CRM, support, enrichment, or BI workflows that need contact data.
  • Manage reusable email content. Use Templates, Assets, and Brand Kit endpoints to let internal tools or an MCP host prepare content without sharing a dashboard session.
  • Drive approved workflows from an AI host. Run the self-hosted MCP Server with an API Key limited to the resources the host needs. The MCP Server wraps the same external routes and does not add a new auth model.

​
Base URL

https://api.segmentflow.ai
Customer-facing launch endpoints are root external routes under /api/v1/, such as /api/v1/profiles, /api/v1/templates, /api/v1/assets, /api/v1/brand-kit, /api/v1/emails, and /api/v1/events.

​
Authentication

Every request authenticates with an API Key sent in the x-api-key header. See Authentication for the key minting flow, scopes, and idempotency.

​
SDKs

A typed TypeScript client is generated from the same OpenAPI spec that powers this documentation: 
npm install @segmentflow/segmentflow-typescript
The OpenAPI spec is published at the bottom of this site, so you can generate a client for any language with openapi-generator or Kubb.

​
Versioning

The unified API is versioned in the URL (/api/v1/...). Breaking changes ship under a new prefix; additive changes (new fields, new endpoints, new optional query params) ship into the existing version without a version bump.

​
Next steps

Sending domain

Verify SPF, DKIM, and DMARC so SegmentFlow.ai can send on your domain.

Which API?

Choose between email sending, event tracking, Journeys, Broadcasts, and Newsletter Issues.

Emails

Send one expected email to one Profile from your backend.

Events

Track one backend business event and trigger matching Journeys.

Authentication

Mint a key and pick the narrowest launch scopes for your integration.

Errors

Status codes, the error envelope, and stable errorCode values to switch on.

API Reference

Every endpoint, request shape, and response shape — with an interactive playground.