Transactional Emails

Transactional emails are triggered programmatically for individual users—order confirmations, password resets, account notifications, and other time-sensitive communications.

Transactional vs Marketing

Transactional	Marketing
Triggered by user action	Sent to segments
One recipient at a time	Multiple recipients
Time-sensitive	Can be scheduled
Expected by user	Promotional
Higher deliverability	May be filtered

Examples of transactional emails:

Order confirmation
Shipping notification
Password reset
Account verification
Payment receipt
Security alert

Sending Modes

1. Template Mode (Recommended)

Create reusable templates in the dashboard, send via API using the template slug.

curl -X POST "https://api.sequenzy.com/api/v1/transactional/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "slug": "order-confirmation",
    "variables": {
      "orderNumber": "ORD-12345",
      "total": "$99.99",
      "deliveryDate": "January 20, 2024"
    }
  }'

Benefits:

Non-developers can edit templates
Consistent branding
Version control in dashboard
Analytics per template
Template blocks can include conditional display rules based on recipient variables
Repeat blocks can render one child block set per item in an array variable

Dynamic Array Data

Transactional templates can repeat blocks over arrays passed in variables. For example, a repeat block with source items and item alias item renders its child blocks once per item. Inside those children, use scoped merge tags like {{item.title}}, {{item.description}}, and {{item.number}}.

curl -X POST "https://api.sequenzy.com/api/v1/transactional/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "slug": "order-confirmation",
    "variables": {
      "items": [
        { "title": "Pro plan", "description": "Monthly subscription" },
        { "title": "Priority support", "description": "Account add-on" }
      ]
    }
  }'

Nested Repeats

Repeat blocks can be nested. Point the inner repeat block’s source at an array inside each parent item using the parent’s item alias - it does not need a separate top-level array. For example, with an outer repeat over orders (alias order), an inner repeat with source order.lineItems (alias line) renders once per line item of the current order, and its children can use merge tags like {{line.title}}.

curl -X POST "https://api.sequenzy.com/api/v1/transactional/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "slug": "order-confirmation",
    "variables": {
      "orders": [
        {
          "number": "ORD-12345",
          "lineItems": [
            { "title": "Pro plan" },
            { "title": "Priority support" }
          ]
        }
      ]
    }
  }'

Conditional Blocks

Conditional (if/else) blocks show one set of blocks when a rule matches and an optional fallback otherwise. In the editor, add a condition and pick the Custom variable field to branch on a value passed in your request variables or an automation event payload - not just stored subscriber data. The variable name is the same reference you would use in a {{merge tag}}, so nested paths work too (for example order.total or event.plan). You can match with equals, contains, numeric comparisons (>=, <=, >, <), or check whether the variable is present with “is empty” / “is not empty”. For example, sending with "variables": { "plan": "pro" } will render the IF branch of a condition like plan equals pro, and the OTHERWISE branch for any other value. Conditions can also target stored subscriber data - segment membership, custom events, tags, lists, status, engagement, and purchases. These rules are checked against the recipient’s subscriber profile at send time; if the recipient is not a stored subscriber, they see the OTHERWISE branch.

2. Direct Mode

Send email content directly without a pre-created template.

curl -X POST "https://api.sequenzy.com/api/v1/transactional/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your Order #{{orderNumber}}",
    "body": "<h1>Thank you for your order!</h1><p>Order: {{orderNumber}}</p>",
    "variables": {
      "orderNumber": "ORD-12345"
    }
  }'

Use cases:

Dynamic content generated by your app
One-off emails that don’t need templates
Testing and development
React Email templates (see below)

3. React Email Mode

Build type-safe, responsive email templates using React Email components and render them to HTML.

import { render } from "@react-email/render";
import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Preview,
  Text,
} from "@react-email/components";

// Create your email component
function OrderConfirmation({ orderNumber, total }: { orderNumber: string; total: string }) {
  return (
    <Html>
      <Head />
      <Preview>Your order #{orderNumber} is confirmed</Preview>
      <Body style={{ fontFamily: "sans-serif" }}>
        <Container>
          <Heading>Thank you for your order!</Heading>
          <Text>Order: #{orderNumber}</Text>
          <Text>Total: {total}</Text>
          <Button href="https://example.com/orders">View Order</Button>
        </Container>
      </Body>
    </Html>
  );
}

// Render and send
const html = await render(OrderConfirmation({ orderNumber: "ORD-12345", total: "$99.99" }));

await fetch("https://api.sequenzy.com/api/v1/transactional/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "customer@example.com",
    subject: "Your Order #ORD-12345",
    body: html,
  }),
});

Benefits:

Type-safe templates with TypeScript
Reusable components
Responsive design built-in
Preview emails during development

4. SMTP Template Payloads

If another product can send through SMTP but lets you control the message body, you can point it at Sequenzy SMTP and send a JSON payload that references one of your existing transactional emails. This is useful for products such as Supabase Auth, where Supabase still triggers the email but Sequenzy renders and sends the final template. Requirements:

A Sequenzy API key for SMTP authentication
At least one sender profile on a verified sending domain
A transactional email with a sender profile assigned

{
  "slug": "supabase-magic-link",
  "dataVariables": {
    "confirmation_url": "https://app.example.com/auth/verify?token=123",
    "email": "user@example.com"
  }
}

You can also use transactionalId instead of slug. If Sequenzy receives a JSON body in this format over SMTP, it ignores the raw email subject/body and sends the saved transactional template instead. For the full Supabase setup, including variable mapping, see the Supabase integration guide.

Framework Quickstarts

See our quickstart guides for Bun, Next.js, and Express.

Creating Templates

In the Dashboard

Go to Transactional in your dashboard
Click Create Template
Enter a slug (URL-friendly identifier)
Design your email with the visual editor
Add variable placeholders where needed
Save and activate

Template Slugs

Slugs are unique identifiers for your templates:

order-confirmation
password-reset
welcome-email
invoice-reminder
shipping-update

Slugs are auto-generated from the template name but can be customized. They cannot be changed after creation.

Variables

Variables let you personalize transactional emails.

Syntax

<p>Hello {{FIRST_NAME}},</p>
<p>Your order {{orderNumber}} has shipped!</p>

With Defaults

Provide fallback values for missing variables:

<p>Hello {{FIRST_NAME|Customer}},</p>
<p>Hello {{ firstName | default: "Customer" }},</p>

If FIRST_NAME or firstName is empty, “Customer” is used. If a variable has no default and no value is provided, it renders as an empty string. The transactional email is still sent.

Conditional HTML Sections

Use {{#if variable}}, {{else}}, and {{/if}} to render simple conditional sections in raw HTML. This is most useful with subscriber custom attributes:

{{#if subscriber.plan}}
<p>Your {{subscriber.plan}} workspace is ready.</p>
{{else}}
<p>Your workspace is ready.</p>
{{/if}}

{{#unless variable}}...{{/unless}} is also supported. Conditions check whether the resolved variable is present and truthy. Nested if/unless sections are supported, but helpers, comparisons, loops, and arbitrary Handlebars expressions are not.

System Variables

These variables are resolved at send time:

Variable	Source
`{{EMAIL}}`	Recipient email address
`{{FIRST_NAME}}`	`firstName`, `first_name`, or `FIRST_NAME` from request `variables`
`{{LAST_NAME}}`	`lastName`, `last_name`, or `LAST_NAME` from request `variables`
`{{NAME}}`	`name`, `NAME`, `fullName`, or a full name built from `FIRST_NAME` and `LAST_NAME` variables

For REST API sends, pass name values in variables when you want to use them. Saved subscriber names are not automatically backfilled into FIRST_NAME, LAST_NAME, or NAME.

Custom Attributes

Any subscriber custom attributes are available:

<p>Your plan: {{plan}}</p>
<p>Account ID: {{userId}}</p>

Passed Variables

Variables passed in the API request:

{
  "variables": {
    "orderNumber": "ORD-123",
    "total": "$99.99"
  }
}

<p>Order: {{orderNumber}}</p>
<p>Total: {{total}}</p>

API Reference

Send Email

POST /api/v1/transactional/send

Template mode:

{
  "to": "user@example.com",
  "slug": "template-slug",
  "variables": {
    "key": "value"
  }
}

Direct mode:

{
  "to": "user@example.com",
  "subject": "Email Subject",
  "body": "<html>Email content</html>",
  "variables": {
    "key": "value"
  }
}

The REST API keeps slug and body as the canonical fields. For compatibility with MCP-style callers, templateId is accepted as an alias for the transactional API slug and html is accepted as an alias for body. If both a canonical field and its alias are provided, their values must match. Response:

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "email": "user@example.com"
  }
}

List Templates

GET /api/v1/transactional

Response:

{
  "success": true,
  "transactional": [
    {
      "id": "trans_abc123",
      "slug": "order-confirmation",
      "name": "Order Confirmation",
      "emailId": "email_abc123",
      "enabled": true
    }
  ]
}

Get Template Details

GET /api/v1/transactional/:idOrSlug

Response:

{
  "success": true,
  "transactional": {
    "id": "trans_abc123",
    "slug": "order-confirmation",
    "name": "Order Confirmation",
    "emailId": "email_abc123",
    "subject": "Your Order #{{orderNumber}}",
    "blocks": [],
    "enabled": true,
    "variables": ["orderNumber", "total", "items"]
  }
}

Auto-Creation

When you send to an email that doesn’t exist:

A new subscriber is created automatically
Status is set to active
Custom attributes from variables are saved (if applicable)

This makes integration seamless—no need to create subscribers first.

Error Handling

Common Errors

Error	Cause	Solution
`Template not found`	Invalid slug	Check slug spelling
`Template disabled`	Template is deactivated	Enable in dashboard
`Missing required fields`	No `to`, `slug`/`subject`	Include required fields
`No sender configured`	No sender profile	Set up sender in dashboard
`Sending paused`	Account sending is paused	Check sending status

Response Codes

Code	Description
`200`	Email queued successfully
`400`	Validation error
`401`	Invalid API key
`404`	Template not found
`500`	Server error

Best Practices

1. Use Templates

Templates are easier to maintain and update:

✓ Template: Update once, affects all future sends
✗ Direct: Must update every code path that sends email

2. Handle Variables Gracefully

Always provide defaults for optional variables, or guard larger optional sections with conditionals:

<!-- Compact default syntax -->
<p>Hi {{FIRST_NAME|there}},</p>

<!-- Liquid-style default filter syntax -->
<p>Hi {{ firstName | default: "there" }},</p>

<!-- Conditional section syntax -->
{{#if subscriber.plan}}
<p>Your {{subscriber.plan}} workspace is ready.</p>
{{else}}
<p>Your workspace is ready.</p>
{{/if}}

Conditional sections support if, unless, and else. They do not support comparisons or custom helpers.

3. Log Job IDs

Save the returned job ID for debugging:

const response = await sendTransactional({
  to: user.email,
  slug: "order-confirmation",
  variables: { orderNumber: order.id },
});

await saveToDatabase({
  orderId: order.id,
  emailJobId: response.data.jobId,
});

4. Use Meaningful Slugs

✓ "order-confirmation"
✓ "password-reset"
✓ "trial-expiring-reminder"

✗ "email1"
✗ "template_2024_01"

5. Test in Development

Use test emails before production:

const to =
  process.env.NODE_ENV === "development" ? "test@yourdomain.com" : user.email;

Integration Examples

Order Confirmation

async function sendOrderConfirmation(order) {
  await fetch("https://api.sequenzy.com/api/v1/transactional/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: order.customerEmail,
      slug: "order-confirmation",
      variables: {
        orderNumber: order.id,
        total: formatCurrency(order.total),
        items: order.items.map((i) => i.name).join(", "),
        shippingAddress: formatAddress(order.shippingAddress),
        estimatedDelivery: formatDate(order.estimatedDelivery),
      },
    }),
  });
}

Password Reset

async function sendPasswordReset(email, resetToken) {
  const resetUrl = `${APP_URL}/reset-password?token=${resetToken}`;

  await fetch("https://api.sequenzy.com/api/v1/transactional/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: email,
      slug: "password-reset",
      variables: {
        resetUrl,
        expiresIn: "24 hours",
      },
    }),
  });
}

Welcome Email

async function sendWelcome(user) {
  await fetch("https://api.sequenzy.com/api/v1/transactional/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: user.email,
      slug: "welcome",
      variables: {
        firstName: user.firstName,
        dashboardUrl: `${APP_URL}/dashboard`,
        docsUrl: `${APP_URL}/docs`,
      },
    }),
  });
}

API Reference

Full API documentation

Subscribers

Auto-creation and attributes

Campaigns

Broadcast marketing emails

Sequences

Automated email workflows

​Transactional Emails

​Transactional vs Marketing

​Sending Modes

​1. Template Mode (Recommended)

​Dynamic Array Data

​Nested Repeats

​Conditional Blocks

​2. Direct Mode

​3. React Email Mode

​4. SMTP Template Payloads

Framework Quickstarts

​Creating Templates

​In the Dashboard

​Template Slugs

​Variables

​Syntax

​With Defaults

​Conditional HTML Sections

​System Variables

​Custom Attributes

​Passed Variables

​API Reference

​Send Email

​List Templates

​Get Template Details

​Auto-Creation

​Error Handling

​Common Errors

​Response Codes

​Best Practices

​1. Use Templates

​2. Handle Variables Gracefully

​3. Log Job IDs

​4. Use Meaningful Slugs

​5. Test in Development

​Integration Examples

​Order Confirmation

​Password Reset

​Welcome Email

​Related

API Reference

Subscribers

Campaigns

Sequences

Transactional Emails

Transactional vs Marketing

Sending Modes

1. Template Mode (Recommended)

Dynamic Array Data

Nested Repeats

Conditional Blocks

2. Direct Mode

3. React Email Mode

4. SMTP Template Payloads

Creating Templates

In the Dashboard

Template Slugs

Variables

Syntax

With Defaults

Conditional HTML Sections

System Variables

Custom Attributes

Passed Variables

API Reference

Send Email

List Templates

Get Template Details

Auto-Creation

Error Handling

Common Errors

Response Codes

Best Practices

1. Use Templates

2. Handle Variables Gracefully

3. Log Job IDs

4. Use Meaningful Slugs

5. Test in Development

Integration Examples

Order Confirmation

Password Reset

Welcome Email

Related