> ## 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.
# Introduction
> The SegmentFlow.ai unified API lets you send expected emails, track server-side business events, and manage Profiles, Templates, Catalog Products, Assets, Brand Kit resources, and EmailSends from your own systems.
SegmentFlow\.ai is a customer engagement platform for sending email, tracking backend business events, and managing the content, catalog products, 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.
* **Catalog Products** - list and retrieve synced products, including remote product image URLs.
* **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 email from a saved Email Template or rendered JSX Email content, or `emails.batchSend` to create many independent EmailSends, then retrieve each durable 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\.ai | What it is |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Profile** | An identified contact owned by your Organization. |
| **Template** | A reusable email body with merge fields and purpose metadata. |
| **Catalog Product** | A synced or manual product record used by recommendations, product blocks, and enrichment. |
| **Asset** | Image metadata and upload state for media used inside Templates and Brand Kit. |
| **Brand Kit** | Logos, colors, and sender profile defaults applied to outgoing email. |
| **EmailSend** | One email to one Profile from a saved Email Template or rendered JSX Email content. Purpose controls policy. |
| **UserEvent** | One tracked event, optionally used to trigger active Journeys. |
Use [Emails](/docs/emails) when your application already knows the recipient and needs to send one email from a saved Email Template or rendered JSX Email content. 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](/docs/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?](/docs/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](/docs/sending-domain) for the DNS setup
before you create your first EmailSend.
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](/docs/authentication) to choose the narrowest set.
List the templates in your organization:
```bash theme={null}
curl https://api.segmentflow.ai/api/v1/templates \
-H "x-api-key: sk_live_..."
```
Send one email from a saved Email Template:
```bash theme={null}
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 ",
"to": {
"email": "alex@example.com",
"externalId": "shopify:customer_123"
},
"subject": "Receipt for order ord_9421",
"replyTo": "Acme Support ",
"data": {
"orderId": "ord_9421",
"firstName": "Alex",
"orderTotal": "49.00"
}
}'
```
Record one backend event that may trigger matching Journeys:
```bash theme={null}
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.
* **Read product context.** Use Catalog Products endpoints to inspect synced Shopify, WooCommerce, and manual products. Shopify product images usually render from `primaryImageUrl`, which may be a Shopify CDN URL.
* **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/catalog-products`, `/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](/docs/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:
```bash theme={null}
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
Verify SPF, DKIM, and DMARC so SegmentFlow\.ai can send on your domain.
Choose between email sending, event tracking, Journeys, Broadcasts, and
Newsletter Issues.
Send one email to one Profile from your backend.
Track one backend business event and trigger matching Journeys.
Mint a key and pick the narrowest launch scopes for your integration.
Status codes, the error envelope, and stable `errorCode` values to switch
on.
Every endpoint, request shape, and response shape — with an interactive
playground.