> ## 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. # Batch send emails > Create or replay many independent EmailSend records. Each item has its own recipient identity, one-send data, idempotency key, and result; this is not a Broadcast, Bulk Operation, Carrier, or NewsletterIssue. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/emails/batch openapi: 3.0.3 info: title: SegmentFlow.ai API description: Unified SegmentFlow.ai API documentation version: 1.0.0 servers: - url: http://localhost:3001 description: Local development - url: https://api-staging.segmentflow.ai description: Staging - url: https://api.segmentflow.ai description: Production security: - apiKeyAuth: [] tags: - name: Profiles description: Profiles (Contacts) - name: Events description: Server-side business event tracking - name: Assets description: Assets - name: BackgroundJobs description: Background job progress - name: Brand-Kit description: Brand kits - name: Catalog-Products description: Catalog products - name: Templates description: Templates - name: Broadcasts description: Broadcasts - name: Segments description: Segments - name: Journeys description: Journeys - name: Emails description: Email sends paths: /api/v1/emails/batch: post: tags: - Emails summary: Batch send emails description: >- Create or replay many independent EmailSend records. Each item has its own recipient identity, one-send data, idempotency key, and result; this is not a Broadcast, Bulk Operation, Carrier, or NewsletterIssue. operationId: Emails_BatchSend requestBody: content: application/json: schema: type: object properties: defaults: type: object properties: templateId: description: >- Advanced fallback saved Email Template id to snapshot and render. Prefer templateKey for SDK integrations. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ templateKey: description: Stable developer key for the saved Email Template. type: string minLength: 1 maxLength: 120 content: description: >- Rendered content. Mutually exclusive with templateId and templateKey. type: object properties: type: type: string enum: - rendered description: >- Rendered-source discriminator. V1 accepts content wrappers with HTML prepared before the API call. renderer: type: string enum: - jsx-email description: >- Renderer identifier for HTML produced by the official TypeScript SDK JSX Email helper or compatible clients. html: type: string minLength: 1 description: >- Rendered HTML body. Segmentflow validates byte limits, injects marketing/newsletter compliance from purpose, and applies tracking at send time. Limit: 1 MiB UTF-8. text: description: >- Optional rendered plain-text body. Segmentflow generates a fallback from HTML when omitted. type: string minLength: 1 metadata: description: >- Optional renderer/helper metadata included in idempotency and frozen source history. type: object additionalProperties: description: Any JSON value. nullable: true x-stainless-any: true required: - type - renderer - html additionalProperties: false title: EmailSendRenderedContent purpose: type: string enum: - transactional - marketing - newsletter description: >- Purpose for rendered content. Required for rendered content. transactional sends do not receive a marketing footer; marketing and newsletter sends receive Segmentflow compliance automatically. Saved template sends continue to use the saved Template purpose. senderProfileId: description: >- Optional SenderProfile override. Must be compatible with the Email Template purpose policy. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ from: type: string minLength: 1 maxLength: 320 description: >- Optional sender override. Accepts a bare email or "Name " and must match a verified SenderProfile email. replyTo: type: string minLength: 1 maxLength: 320 description: >- Optional reply-to override. Accepts a single bare email or "Name " and must use a verified sender domain owned by the organization. subject: type: string minLength: 1 maxLength: 998 description: >- Final subject for rendered sends, or an optional override for saved Template sends. When omitted for a saved Template send, the Template subject is frozen onto the EmailSend. subscriptionGroupId: description: >- SubscriptionGroup gate. Required for marketing-class Email Template purposes; if supplied, the send is skipped when the recipient is not subscribed according to the group's OptIn/OptOut policy. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ tracking: description: Per-send tracking preferences. type: object properties: clicks: description: Enable or disable click tracking for this send. type: boolean additionalProperties: false additionalProperties: false description: >- Shared batch defaults applied to each item before item validation. Recipient, data, cc, and bcc fields are not allowed here. items: minItems: 1 maxItems: 100 type: array items: type: object properties: templateId: description: >- Exact saved Email Template id to snapshot and render. May be supplied by batch defaults and is mutually exclusive with content/templateKey after defaults merge. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ templateKey: description: Stable developer key for the saved Email Template. type: string minLength: 1 maxLength: 120 content: description: >- Rendered content. Mutually exclusive with templateId and templateKey. type: object properties: type: type: string enum: - rendered description: >- Rendered-source discriminator. V1 accepts content wrappers with HTML prepared before the API call. renderer: type: string enum: - jsx-email description: >- Renderer identifier for HTML produced by the official TypeScript SDK JSX Email helper or compatible clients. html: type: string minLength: 1 description: >- Rendered HTML body. Segmentflow validates byte limits, injects marketing/newsletter compliance from purpose, and applies tracking at send time. Limit: 1 MiB UTF-8. text: description: >- Optional rendered plain-text body. Segmentflow generates a fallback from HTML when omitted. type: string minLength: 1 metadata: description: >- Optional renderer/helper metadata included in idempotency and frozen source history. type: object additionalProperties: description: Any JSON value. nullable: true x-stainless-any: true required: - type - renderer - html additionalProperties: false title: EmailSendRenderedContent purpose: type: string enum: - transactional - marketing - newsletter description: >- Purpose for rendered content. Required for rendered content. transactional sends do not receive a marketing footer; marketing and newsletter sends receive Segmentflow compliance automatically. Saved template sends continue to use the saved Template purpose. profileId: description: >- Optional primary recipient Profile id. When to.email is absent, the Profile canonical email is used for delivery. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ senderProfileId: description: >- Optional SenderProfile override. Must be compatible with the Email Template purpose policy. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ from: type: string minLength: 1 maxLength: 320 description: >- Optional sender override. Accepts a bare email or "Name " and must match a verified SenderProfile email. replyTo: type: string minLength: 1 maxLength: 320 description: >- Optional reply-to override. Accepts a single bare email or "Name " and must use a verified sender domain owned by the organization. subject: type: string minLength: 1 maxLength: 998 description: >- Final subject for rendered sends, or an optional override for saved Template sends. When omitted for a saved Template send, the Template subject is frozen onto the EmailSend. subscriptionGroupId: description: >- SubscriptionGroup gate. Required for marketing-class Email Template purposes; if supplied, the send is skipped when the recipient is not subscribed according to the group's OptIn/OptOut policy. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ to: type: object properties: email: description: >- Recipient email address. Stored normalized in the send record. type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ externalId: description: >- Safe caller-owned recipient identifier used to link or create the Profile. type: string minLength: 1 maxLength: 255 additionalProperties: false description: >- Recipient identity. This identifies or creates a Profile but does not update durable Profile Properties. cc: description: >- Visible copied recipients. Persisted and handed to the email provider. anyOf: - type: string minLength: 1 maxLength: 320 description: >- Copied recipient address. Accepts a bare email or "Name ". - maxItems: 50 type: array items: type: string minLength: 1 maxLength: 320 description: >- Copied recipient address. Accepts a bare email or "Name ". bcc: description: >- Hidden copied recipients. Persisted for retry/provider handoff but never returned by public responses. anyOf: - type: string minLength: 1 maxLength: 320 description: >- Copied recipient address. Accepts a bare email or "Name ". - maxItems: 50 type: array items: type: string minLength: 1 maxLength: 320 description: >- Copied recipient address. Accepts a bare email or "Name ". data: description: >- One-send email payload exposed to templates under /data/*. type: object additionalProperties: description: Any JSON value. nullable: true x-stainless-any: true tracking: description: Per-send tracking preferences. type: object properties: clicks: description: Enable or disable click tracking for this send. type: boolean additionalProperties: false idempotencyKey: type: string minLength: 1 maxLength: 255 description: >- Required idempotency key for this independent EmailSend item. required: - idempotencyKey additionalProperties: false description: >- One independent email send item. Each item creates or replays its own EmailSend. description: >- Independent email sends. Items are processed in order and each item has its own idempotency key and result. required: - items additionalProperties: false required: true responses: '202': description: Default Response content: application/json: schema: type: object properties: total: type: integer minimum: 0 maximum: 9007199254740991 description: Total items submitted. accepted: type: integer minimum: 0 maximum: 9007199254740991 description: Items that created or replayed an EmailSend. rejected: type: integer minimum: 0 maximum: 9007199254740991 description: Items rejected before creating an EmailSend. items: type: array items: anyOf: - type: object properties: index: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based item index. idempotencyKey: type: string description: Item idempotency key. status: type: string enum: - Accepted send: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: EmailSend id. status: type: string enum: - Queued - Processing - Sent - Failed - Skipped - DeliveryUnknown description: Lifecycle status for an EmailSend. templateId: nullable: true description: >- Source saved Template id. Null when the send was created from rendered JSX Email content. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ source: anyOf: - type: object properties: type: type: string enum: - template templateId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - type - templateId additionalProperties: false title: EmailSendTemplateSource x-stainless-variantName: Template - type: object properties: type: type: string enum: - rendered renderer: type: string enum: - jsx-email metadata: type: object additionalProperties: description: Any JSON value. nullable: true x-stainless-any: true required: - type - renderer additionalProperties: false title: EmailSendRenderedSource x-stainless-variantName: Rendered description: >- Content source used to create this EmailSend. Rendered sends never create fake Templates. frozenEmailInstanceId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- Immutable Email Instance rendered for this send. senderProfileId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: SenderProfile used for the send. from: type: object properties: email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ name: type: string nullable: true required: - email - name additionalProperties: false description: >- Frozen sender envelope used for provider handoff. replyTo: nullable: true description: >- Frozen reply-to envelope used for provider handoff. type: object properties: email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ name: type: string nullable: true required: - email - name additionalProperties: false subject: type: string description: Frozen subject used for provider handoff. subscriptionGroupId: nullable: true description: >- SubscriptionGroup gate used for the send, if supplied. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ profileId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Organization-scoped recipient Profile id. to: type: object properties: email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ required: - email additionalProperties: false description: >- Redacted-safe recipient handle returned by the API. cc: type: array items: type: object properties: email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ name: type: string nullable: true required: - email - name additionalProperties: false description: >- Visible copied recipients returned for operational visibility. messageId: nullable: true description: >- Underlying Message id after worker processing creates one. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ skippedReason: nullable: true type: string enum: - ProfileErased - ProfileSuppressed - ProfileUnsubscribed - MissingRecipientEmail - InvalidTemplate - InvalidSenderProfile - SendAdmissionBlocked - RateLimited description: >- Reason delivery was intentionally skipped before provider send. failureReason: nullable: true type: string enum: - WorkerFailed - ProviderRejected - RenderFailed - Unknown description: >- Reason delivery failed after a send was accepted for processing. failureMessage: nullable: true description: >- Operational failure message suitable for logs and support. type: string createdAt: description: Send creation timestamp. type: string format: date-time updatedAt: description: Last send update timestamp. type: string format: date-time required: - id - status - templateId - source - frozenEmailInstanceId - senderProfileId - from - replyTo - subject - subscriptionGroupId - profileId - to - cc - messageId - skippedReason - failureReason - failureMessage - createdAt - updatedAt additionalProperties: false required: - index - idempotencyKey - status - send additionalProperties: false title: EmailBatchSendAcceptedItem x-stainless-variantName: Accepted - type: object properties: index: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based item index. idempotencyKey: type: string description: Item idempotency key. status: type: string enum: - Rejected error: type: object properties: statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- HTTP status code that would apply to this item on its own. errorCode: nullable: true description: >- Stable error code for the item, when available. type: string message: type: string description: Human-readable item error message. details: description: >- Additional machine-readable item error details. type: object additionalProperties: description: Any JSON value. nullable: true x-stainless-any: true required: - statusCode - errorCode - message additionalProperties: false required: - index - idempotencyKey - status - error additionalProperties: false title: EmailBatchSendRejectedItem x-stainless-variantName: Rejected description: Ordered per-item results. required: - total - accepted - rejected - items additionalProperties: false '400': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ErrorResponse: type: object properties: errorCode: $ref: '#/components/schemas/SegmentflowErrorCode' description: >- Stable machine-readable error code. SDKs map this to typed exception classes. example: TEMPLATE_NAME_EXISTS message: type: string description: >- Human-readable error message. May change between releases; do not parse. example: Template name 'Hello' already exists in this organization. details: description: >- Optional structured detail. `issues` carries per-field validation problems; other keys are reserved. type: object properties: issues: type: array items: $ref: '#/components/schemas/ErrorIssue' additionalProperties: description: Any JSON value. nullable: true x-stainless-any: true required: - errorCode - message additionalProperties: false description: 'Canonical error envelope (ADR-0008): `{ errorCode, message, details? }`.' SegmentflowErrorCode: type: string enum: - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - GONE - UNPROCESSABLE_ENTITY - TOO_MANY_REQUESTS - VALIDATION_ERROR - INTERNAL_ERROR - NOT_IMPLEMENTED - SERVICE_UNAVAILABLE - DATABASE_ERROR - IDEMPOTENCY_KEY_TOO_LONG - IDEMPOTENCY_KEY_REUSED - IDEMPOTENCY_IN_FLIGHT - JOURNEY_NOT_FOUND - JOURNEY_WRONG_ENTRY_NODE - JOURNEY_MISSING_RECIPIENT_EMAIL - JOURNEY_MISSING_REQUIRED_VARIABLES - JOURNEY_RECIPIENT_ERASED - JOURNEY_RUN_NOT_FOUND - BROADCAST_NOT_FOUND - BROADCAST_SCHEDULING_NOT_IMPLEMENTED - BROADCAST_INVALID_STATE - BROADCAST_SEND_NOT_ALLOWED - PREPARED_SEND_NOT_FOUND - PREPARED_SEND_EXPIRED - PREPARED_SEND_CROSS_USER - PREPARED_SEND_CORRUPT - PREPARED_SEND_CONCURRENT_REDEEM - PREPARED_SEND_VALIDATION_FAILED - TEMPLATE_NOT_FOUND - TEMPLATE_NAME_EXISTS - PROFILE_NOT_FOUND - PROFILE_SUBSCRIPTION_GROUP_NOT_FOUND - PROFILE_TRAITS_WRITE_UNSUPPORTED - MISSING_CREDENTIAL - INVALID_API_KEY - INVALID_OAUTH_TOKEN - AMBIGUOUS_CREDENTIAL - INSUFFICIENT_SCOPE - MULTIPLE_CREDENTIALS_PRESENT - BEARER_CREDENTIAL_REMOVED - SESSION_ROLE_INSUFFICIENT - API_KEY_SCOPE_INSUFFICIENT - BILLING_DISABLED - BILLING_NOT_CONFIGURED description: >- Stable machine-readable error code. SDK codegen maps these to typed exception classes. ErrorIssue: type: object properties: path: anyOf: - type: string - type: array items: anyOf: - type: string - type: number description: >- Where in the request the issue occurred. String for simple paths; array for nested paths. example: name code: type: string description: >- Stable, machine-readable kind of issue (e.g. 'required', 'invalid_type'). example: duplicate message: type: string description: Human-readable description of the issue. example: Template name already exists in this organization. required: - path - code - message additionalProperties: false description: A single validation issue inside an error response's `details.issues[]`. securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: Unified API key for server-side SDK and API integrations ````