Skip to main content

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.

Segmentflow EmailSend accepts familiar envelope fields, but it is not a raw email provider API. Every EmailSend is template-backed, resolves one primary Profile, freezes the effective envelope, and returns a durable status handle. Use this guide when you are moving existing server-side send calls to emails.send or emails.batchSend.

​
Field mapping

Resend-style fieldSegmentflow EmailSend fieldNotes
fromfromMust match an exact SenderProfile email on a verified sending domain. Friendly names are supported.
toto.emailOne primary recipient per EmailSend. Use emails.batchSend for multiple primary recipients.
Customer id or user idto.externalIdOptional caller-owned Profile identity. Include to.email when a new Profile may need to be created.
Segmentflow Profile idprofileIdUse when you already know the primary recipient Profile. to is optional when profileId is present.
subjectsubjectFinal frozen subject text. If omitted, Segmentflow uses the saved Template subject.
reply_to or replyToreplyToSingle friendly-address value. Must use a verified sender domain owned by your Organization.
ccccVisible copied recipients. Envelope-only; does not create Profiles or Messages.
bccbccHidden copied recipients. Envelope-only and not returned by ordinary API responses.
Template variablesdataOne-send payload available to templates under /data/*.
Provider idempotency headerIdempotency-KeyRequired for emails.send. Batch uses item-level idempotencyKey.
Provider response idEmailSend.idStore this durable status handle and retrieve it with emails.retrieve.
Raw html, text, or reactSaved Email TemplateCreate and publish the Template first, then pass its exact templateId.

​
Single send

const send = await client.v1.emails.send(
  {
    templateId: "2c2f9e13-7d0a-4b10-9f4b-35f6d96d7a70",
    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>",
    cc: "Billing <billing@example.com>",
    bcc: ["audit@example.com"],
    data: {
      orderId: "ord_9421",
      orderTotal: "49.00",
      receiptUrl: "https://app.example.com/orders/ord_9421/receipt",
    },
  },
  {
    headers: { "Idempotency-Key": "order-confirmation:ord_9421" },
  },
);
The response is not a provider-only delivery id. It is an EmailSend status handle with lifecycle status, the source templateId, the immutable templateSnapshotId, the resolved primary profileId, and the safe effective envelope.

​
Batch sends

Resend-style provider batches usually send an array of complete email envelopes. Segmentflow batch creates many independent EmailSends and lets you put shared fields in defaults. 
const batch = await client.v1.emails.batchSend({
  defaults: {
    templateId: "2c2f9e13-7d0a-4b10-9f4b-35f6d96d7a70",
    from: "Acme Receipts <receipts@example.com>",
    subject: "Your receipt is ready",
    replyTo: "Acme Support <support@example.com>",
    tracking: { clicks: false },
  },
  items: [
    {
      idempotencyKey: "order-confirmation:ord_9421",
      to: {
        email: "alex@example.com",
        externalId: "shopify:customer_123",
      },
      data: {
        orderId: "ord_9421",
        orderTotal: "49.00",
      },
    },
    {
      idempotencyKey: "order-confirmation:ord_9422",
      to: { email: "sam@example.com" },
      subject: "Receipt for order ord_9422",
      data: {
        orderId: "ord_9422",
        orderTotal: "129.00",
      },
      bcc: "audit@example.com",
    },
  ],
});
Batch defaults can include templateId, from, senderProfileId, subject, replyTo, subscriptionGroupId, and tracking. They cannot include profileId, to, data, cc, or bcc. Each item has an ordered result. A valid item can be accepted while another item is returned as Rejected.

​
Differences to plan for

BehaviorSegmentflow EmailSend
ContentTemplate-backed only. Create a saved Email Template and send with exact templateId.
Primary recipientsExactly one primary recipient per EmailSend. Use batch for multiple primary recipients.
Profile resolutionprofileId, to.email, and to.externalId resolve one primary Profile. EmailSend does not update Profile properties.
Sender authorizationfrom must resolve to an exact SenderProfile email on a verified sending domain.
Reply handlingreplyTo can differ from from, but must use an Organization-owned verified sender domain.
Copied recipientscc and bcc are envelope-only. They do not create Profiles, Messages, or separate Delivery Events.
Blind-copy visibilitybcc is stored for delivery and retry behavior, but ordinary create and retrieve responses do not echo it.
IdempotencyThe key is compared against the full effective request, including sender, subject, recipients, tracking, and data.
StatusCreate returns a durable EmailSend status handle. Delivery outcomes are tracked separately from lifecycle status.
Raw provider optionsRaw content, inline templates, arbitrary headers, attachments, and provider-specific render options are out of scope.

​
Idempotency differences

For emails.send, pass an Idempotency-Key header. For emails.batchSend, pass idempotencyKey on every item. Segmentflow compares the key against the full effective request after defaults and resolution. Reusing the same key with the same effective request returns the existing EmailSend. Reusing the key with a changed sender, subject, recipient, copied recipient, tracking setting, subscription gate, or data returns a conflict for single send or a Rejected item in batch.

​
Next steps

Emails

Read the full EmailSend request model and lifecycle guide.

Sending domain

Verify the sender domain before production EmailSends.