Skip to main content
POST
/
api
/
v1
/
emails
Send email
curl --request POST \
  --url http://localhost:3001/api/v1/emails \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "templateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "senderProfileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "from": "<string>",
  "replyTo": "<string>",
  "subject": "<string>",
  "subscriptionGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": {
    "email": "jsmith@example.com",
    "externalId": "<string>"
  },
  "cc": "<string>",
  "bcc": "<string>",
  "data": {},
  "tracking": {
    "clicks": true
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "templateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "templateSnapshotId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "senderProfileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "from": {
    "email": "jsmith@example.com",
    "name": "<string>"
  },
  "replyTo": {
    "email": "jsmith@example.com",
    "name": "<string>"
  },
  "subject": "<string>",
  "subscriptionGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": {
    "email": "jsmith@example.com"
  },
  "cc": [
    {
      "email": "jsmith@example.com",
      "name": "<string>"
    }
  ],
  "messageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "failureMessage": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

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.

Authorizations

​
x-api-key
string
header
required

Unified API key for server-side SDK and API integrations

Headers

​
idempotency-key
string
required

Required idempotency key. Reusing it with the same request replays the original send; reusing it with a different request returns 409.

Required string length: 1 - 255

Body

application/json
​
templateId
string<uuid>
required

Exact saved Email Template id to snapshot and render.

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
string<uuid>

Optional primary recipient Profile id. When to.email is absent, the Profile canonical email is used for delivery.

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
string<uuid>

Optional transactional SenderProfile override. Defaults to the template SenderProfile.

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
string

Optional sender override. Accepts a bare email or "Name email@example.com" and must match a verified SenderProfile email.

Required string length: 1 - 320
​
replyTo
string

Optional reply-to override. Accepts a single bare email or "Name email@example.com" and must use a verified sender domain owned by the organization.

Required string length: 1 - 320
​
subject
string

Optional final subject override. When omitted, the Template subject is frozen onto the EmailSend.

Required string length: 1 - 998
​
subscriptionGroupId
string<uuid>

Optional SubscriptionGroup gate. If supplied, the send is skipped when the recipient is not subscribed according to the group's OptIn/OptOut policy.

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
object

Recipient identity. This identifies or creates a Profile but does not update durable Profile Properties.

​
cc

Visible copied recipients. Persisted and handed to the email provider.

Required string length: 1 - 320
​
bcc

Hidden copied recipients. Persisted for retry/provider handoff but never returned by public responses.

Required string length: 1 - 320
​
data
object

One-send email payload exposed to templates under /data/*.

​
tracking
object

Per-send tracking preferences.

Response

Default Response

​
id
string<uuid>
required

EmailSend id.

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)$
​
status
enum<string>
required

Lifecycle status for an EmailSend.

Available options:
Queued,
Processing,
Sent,
Failed,
Skipped
​
templateId
string<uuid>
required

Source template id.

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)$
​
templateSnapshotId
string<uuid>
required

Immutable template snapshot rendered for this send.

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
string<uuid>
required

SenderProfile used for the send.

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
object
required

Frozen sender envelope used for provider handoff.

​
replyTo
object
required

Frozen reply-to envelope used for provider handoff.

​
subject
string
required

Frozen subject used for provider handoff.

​
subscriptionGroupId
string<uuid> | null
required

SubscriptionGroup gate used for the send, if supplied.

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
string<uuid>
required

Organization-scoped recipient Profile id.

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
object
required

Redacted-safe recipient handle returned by the API.

​
cc
object[]
required

Visible copied recipients returned for operational visibility.

​
messageId
string<uuid> | null
required

Underlying Message id after worker processing creates one.

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
enum<string> | null
required

Reason delivery was intentionally skipped before provider send.

Available options:
ProfileErased,
ProfileSuppressed,
ProfileUnsubscribed,
MissingRecipientEmail,
InvalidTemplate,
InvalidSenderProfile,
SendAdmissionBlocked,
RateLimited
​
failureReason
enum<string> | null
required

Reason delivery failed after a send was accepted for processing.

Available options:
WorkerFailed,
ProviderRejected,
RenderFailed,
Unknown
​
failureMessage
string | null
required

Operational failure message suitable for logs and support.

​
createdAt
string<date-time>
required

Send creation timestamp.

​
updatedAt
string<date-time>
required

Last send update timestamp.