Sign in
Transactional

Send transactional email

Queues a transactional email for sending. 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

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 provided replyTo as the forwarding destination for captured replies. For direct-content sends with reply tracking and reply forwarding enabled, omitting replyTo forwards replies to the company's default reply profile, then falls back to the first reply profile in the company. If no reply profile exists, replies are captured in Sequenzy but are not forwarded externally. Variables can be passed to customize the email content. Nested objects and arrays are supported for repeat blocks, such as items. Returns immediately with a job ID. 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.

post/transactional/send

Request body

slugstring

Canonical slug of the transactional email template to use (mutually exclusive with direct content).

templateIdstring

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.

subscriberExternalIdstring

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.

subjectstring

Email subject (required if not using slug)

bodystring

Canonical email body HTML content (required if not using a template slug).

htmlstring

Compatibility alias for body. Accepted with subject for direct sends and must match body when both are provided.

previewstring

Preview text for the email (only used with direct content)

variablesobject

Variables for template replacement (works with both modes). Values can be scalars, nested objects, or arrays used by repeat blocks. Raw HTML templates can use simple subscriber/custom-attribute conditionals such as {{#if subscriber.plan}}...{{else}}...{{/if}} and {{#unless subscriber.plan}}...{{/unless}}. 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.

fromstring

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.

replyTostring

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. For direct-content sends with reply tracking and reply forwarding enabled, omitting this field forwards replies to the company's default reply profile, then falls back to the first reply profile in the company. If no reply profile exists, replies are captured in Sequenzy but are not forwarded externally.

Example request

{
  "slug": "welcome-email",
  "templateId": "welcome-email",
  "subscriberExternalId": "user_123",
  "subject": "Welcome to our platform!",
  "body": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  "preview": "Welcome to our platform",
  "variables": {
    "NAME": "John",
    "event": {
      "items": [
        {
          "title": "Pro plan",
          "description": "Monthly subscription"
        }
      ]
    }
  },
  "from": "Notifications <notifications@example.com>",
  "replyTo": "Support <support@example.com>",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "path": "https://example.com/invoices/123.pdf"
    }
  ]
}

Response

Email queued successfully

OR

Example response

{
  "success": true,
  "emailSendId": "send_abc123",
  "jobId": "job_abc123",
  "diagnostics": {
    "status": "warning",
    "message": "Email was queued. A required variable is missing and will render as an empty string.",
    "missingRequiredVariables": [
      {
        "name": "RESET_URL",
        "lookupName": "reset_url",
        "message": "Email was queued. Required variable \"RESET_URL\" is missing and will render as an empty string.",
        "usedIn": [
          {
            "surface": "block",
            "field": "url",
            "blockId": "reset-button",
            "blockType": "button"
          }
        ],
        "suggestions": [
          "resetpasswordlink"
        ]
      }
    ],
    "unusedVariables": [
      {
        "name": "resetpasswordlink",
        "message": "Variable \"resetpasswordlink\" was provided but is not used by the email template.",
        "suggestions": [
          "reset_url"
        ]
      }
    ]
  }
}

Changes