---
title: "Send transactional or marketing email"
method: POST
path: "/transactional/send"
tags: ["Transactional"]
---

# Send transactional or marketing email

`POST /transactional/send`

Queues an email for sending. The default `emailType` is `transactional`. Set it to `marketing` for a consented single-recipient lifecycle or promotional message. Marketing mode creates or links a minimal subscriber, honors unsubscribe suppression, adds the standard marketing footer, and emits RFC 8058 one-click-unsubscribe headers. The caller remains responsible for having consent or another lawful basis.

You can either:
- Provide a canonical `slug` (or compatibility alias `templateId`) to use a saved template
- Provide `subject` and canonical `body` (or compatibility alias `html`) to send custom content directly

If both a canonical field and its alias are provided, `slug` must match `templateId` and `body` must match `html`.

**Recipients:**
- `to` can be a single email or an array of up to 50 emails
- Duplicate emails are automatically deduplicated
- Marketing mode requires exactly one `to` recipient and does not support `cc` or `bcc`

**Attachments:**
- Attachments can be provided as Base64-encoded content or URLs
- Maximum total attachment size: 40MB per email
- Any file type supported (PDFs, images, documents, etc.)

A successful response means the email was accepted for background processing. Transactional emails are not blocked by subscriber unsubscribe or double opt-in status. If a recipient is suppressed because of a hard bounce or spam complaint, the worker records the send as `suppressed` instead of delivering it.

Optionally set `from` (domain must be verified) and `replyTo` addresses. When reply tracking is enabled, Sequenzy uses a unique trackable `Reply-To` header and treats the resolved reply destination as the forwarding destination for captured replies.
When `replyTo` is omitted, direct-content sends inherit the company's default reply profile and saved-template sends prefer the template reply profile before the company default. Both fall back to the first company reply profile. The resolved destination is retained whether or not reply tracking is enabled; it is sent as the Reply-To header only when reply tracking is disabled.
Variables can be passed to customize the email content. Nested objects and arrays are supported for repeat blocks, such as `items`. `{{viewInBrowserUrl}}` is generated automatically for a hosted copy link. For a single recipient, Sequenzy matches an existing subscriber by `subscriberExternalId` or email and backfills stored first and last names when the corresponding request variables are omitted; explicit variables take precedence. Returns immediately with a durable `emailSendId` and the accepted `emailType`. If Sequenzy detects likely missing or unused variables before queueing, the successful response includes a non-blocking `diagnostics` warning object. Missing values do not block queueing or sending; a required variable that is not provided and has no default renders as an empty string.

## Request body

- object
  - `to` union, required — Recipient email address(es). Can be a single email string or an array of up to 50 emails.
    - string, email
    - string[]
  - `cc` union — Visible carbon-copy recipient email address(es). Duplicates already present in `to` are removed.
    - string, email
    - string[]
  - `bcc` union — Blind-carbon-copy recipient email address(es). Duplicates already present in `to` or `cc` are removed.
    - string, email
    - string[]
  - `slug` string — Canonical slug of the transactional email template to use (mutually exclusive with direct content).
  - `templateId` string — Compatibility alias for `slug`. Despite the field name, pass the saved transactional email API slug, not its database ID. Must match `slug` when both are provided.
  - `subscriberExternalId` string — Customer-owned subscriber ID for single-recipient sends. If it matches an existing subscriber, analytics and localization use that subscriber; the value is also stored on the send and emitted as external_id in outbound email webhooks even when no subscriber exists. Maximum length is 255 characters.
  - `emailType` 'transactional' | 'marketing' — Delivery policy. Marketing mode requires one recipient, creates or links a minimal subscriber, honors unsubscribe suppression, adds the standard footer, and emits RFC 8058 List-Unsubscribe and List-Unsubscribe-Post headers.
  - `subject` string — Email subject (required if not using slug)
  - `body` string — Canonical email body HTML content (required if not using a template slug).
  - `html` string — Compatibility alias for `body`. Accepted with `subject` for direct sends and must match `body` when both are provided.
  - `preview` string — Preview text for the email (only used with direct content)
  - `variables` object — Variables for template replacement (works with both modes). Values can be scalars, nested objects, or arrays used by repeat blocks. For a single recipient, stored subscriber first and last names fill missing name variables; explicit request variables take precedence. Raw HTML templates can use simple subscriber/custom-attribute conditionals such as `{{#if subscriber.plan}}...{{else}}...{{/if}}` and `{{#unless subscriber.plan}}...{{/unless}}`. Variables are always HTML-escaped; a template can prefix a tag with `html.` (`{{html.prerenderedHtml}}`) to insert a trusted HTML value unescaped. Injected HTML is sanitized (scripts, event handlers, and dangerous URLs are stripped), only applies in HTML text position, and must not contain end-user input. Likely variable issues are returned as non-blocking diagnostics when possible; missing required variables without defaults render as empty strings and do not block sending.
  - `from` string — Custom from address. Format: "Name <email>" or just "email". The domain must be verified for your account. If not verified, this field is silently ignored.
  - `replyTo` string — Reply-to address. Format: "Name <email>" or just "email". Can be any valid email address. When reply tracking is disabled, this value is sent as the email's `Reply-To` header. When reply tracking is enabled, Sequenzy sends a unique trackable `Reply-To` header and stores this value as the forwarding destination for replies. When omitted, direct-content sends inherit the company default and saved-template sends prefer the template reply profile before the company default. Both fall back to the first company reply profile. The resolved destination is retained whether or not reply tracking is enabled; it is sent directly only when reply tracking is disabled.
  - `attachments` Attachment[] — File attachments for the email. Each attachment must have a filename and either: - `content`: Base64-encoded file content - `path`: URL to fetch the file from Maximum total size: 40MB per email.
    - `filename` string, required — The filename for the attachment (including extension)
    - `content` string — Base64-encoded file content (mutually exclusive with path)
    - `path` string, uri — URL to fetch the file from (mutually exclusive with content)
    - `contentType` string — MIME type of the attachment (optional, auto-detected if not provided)
  - `trackingSettings` object — Per-send tracking opt-outs. Each field defaults to `true`, meaning your account's tracking settings apply; set a field to `false` to disable that tracking for this send only. These fields can only opt out; they cannot enable tracking that is disabled for your account.
    - `clickTracking` boolean — Set `false` to skip link rewriting so the original URLs are delivered unchanged. Useful when the click-tracking redirect domain breaks iOS/Android universal links or deep links in transactional emails.
    - `openTracking` boolean — Set `false` to skip the open-tracking pixel for this send only.

## Response `200`

Email queued successfully

- union
  - object
    - `success` boolean
    - `emailSendId` string — Durable email delivery ID. Use this with GET /email-sends/{emailSendId}.
    - `emailType` 'marketing' | 'transactional' — Delivery policy accepted for the queued email.
    - `jobId` string — Legacy queue identifier retained for response compatibility.
    - `to` union
      - string
      - string[]
    - `transactional` object
      - `id` string
      - `slug` string
      - `name` string
    - `diagnostics` TransactionalSendDiagnostics — Non-blocking warnings about template variable issues. The send is still queued when this object is present, and missing values without defaults render as empty strings.
      - `status` 'warning', required
      - `message` string, required
      - `missingRequiredVariables` object[], required
        - `name` string
        - `lookupName` string
        - `message` string
        - `usedIn` object[]
          - `surface` 'subject' | 'previewText' | 'body' | 'block'
          - `field` string
          - `blockId` string
          - `blockType` string
        - `suggestions` string[]
      - `unusedVariables` object[], required
        - `name` string
        - `message` string
        - `suggestions` string[]
  - object
    - `success` boolean
    - `emailSendId` string — Durable email delivery ID. Use this with GET /email-sends/{emailSendId}.
    - `emailType` 'marketing' | 'transactional' — Delivery policy accepted for the queued email.
    - `jobId` string — Legacy queue identifier retained for response compatibility.
    - `to` union
      - string
      - string[]
    - `diagnostics` TransactionalSendDiagnostics — Non-blocking warnings about template variable issues. The send is still queued when this object is present, and missing values without defaults render as empty strings.
      - `status` 'warning', required
      - `message` string, required
      - `missingRequiredVariables` object[], required
        - `name` string
        - `lookupName` string
        - `message` string
        - `usedIn` object[]
          - `surface` 'subject' | 'previewText' | 'body' | 'block'
          - `field` string
          - `blockId` string
          - `blockType` string
        - `suggestions` string[]
      - `unusedVariables` object[], required
        - `name` string
        - `message` string
        - `suggestions` string[]

## Other responses

- `400` — Bad request (validation error, disabled template, attachment errors, etc.)
- `401` — Unauthorized
- `404` — Template not found
- `500` — Internal server error

---

[API](https://skmtc.net/sequenzy/apis/sequenzy-api.md) · [All operations](https://skmtc.net/sequenzy/apis/sequenzy-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sequenzy/sequenzy-api/versions/af1cf9620482/schema)