Transactional Email API

Authenticate with Authorization: Bearer apex_tx_… or X-Api-Key: apex_tx_….

Headers

Body

The endpoint accepts two mutually exclusive shapes: provide either the inline fields (subject + html/text) or a commId reference, not both.

Inline shape

Caller supplies the email body verbatim. Available since the API launched.

Template shape (Wave 44)

Reference a workspace TenantCommunication (must have commType === "transactional") by id and pass a flat variables map. The server resolves the template, applies your variables as slot overrides (when keys match named slots like headline, ctaUrl, body) and as {{key}} substitutions in subject + html + text, and renders the result through the same pipeline as Adaptive Journey sends. Unknown placeholders are left as-is so test sends surface bugs instead of silently dropping them.

HTML output escapes special characters in substituted values; the subject and text outputs are not escaped (so curly quotes etc. render correctly).

Always pass URLs as variables. Email clients can't resolve relative paths — /dashboard becomes http://dashboard and fails. Build the absolute URL in your code (${process.env.APP_URL}/invite/accept?token=…) and pass it as a variable; the template references it as {{acceptUrl}} etc. The catalog templates ship with {{variable}} defaults out of the box for this reason.

Catalog template variable reference

When activating a built-in catalog template, here's what its slots expect. The variables your code passes must match these names (or the template falls back to its {{variable}} placeholder rendering as literal text in the email).

You can override any slot at send time by passing a key matching the slot id (e.g. subject, headline, body, ctaLabel, ctaUrl). Anything else flows through {{key}} substitution.

Transactional emails must not be unsubscribable. When commType === "transactional", the brand-footer block automatically suppresses the Unsubscribe link. This is required by CAN-SPAM § 7704(a)(5)(B), preserves the SES reputation partition between transactional and marketing traffic, and prevents recipients from accidentally opting out of password-reset emails. Don't override this — change the comm's type to marketing instead if you actually want unsubscribe behavior.

Errors specific to the template shape:

Strict mode example

// Request
{
  "to": "alex@customer.com",
  "commId": "invite",
  "variables": { "inviterName": "Chris" },
  "strict": true
}

// 400 response
{
  "error": {
    "code": "missing_variables",
    "message": "Strict mode: template \"invite\" requires variables you didn't provide.",
    "missing": ["acceptUrl", "orgName", "role"]
  }
}

Pair strict: true with the Data dictionary (Settings → Workspace → Data dictionary) so the composer surfaces required variables as you author templates and your code surfaces them as 400s before they reach an inbox.

Auth codes (verification / MFA / OTP / password-reset code) [#auth-codes]

Apex ships a first-class Code block in the composer for auth-code emails. The block renders a styled monospace value (your workspace's primary brand color) with an editable caption beneath ("Verification Code", "Sign-in Code", "Recovery Code" — whatever fits the flow). Use it for any email that delivers a short numeric or alphanumeric code to the recipient — Cognito email verification, Auth0 MFA challenges, password-reset codes, WorkOS magic codes, custom OTP flows.

1. Author the template

1. Open the composer for the comm (e.g. verification-code, which ships pre-wired).
2. Drop a Code block from the content palette where you want the code to appear (between the intro paragraph and the brand-footer reads well).
3. The block defaults to {{code}} as the value. Rename the placeholder (e.g. {{otp}}, {{recovery_code}}) if your code-generation pipeline uses a different name. Edit the caption to fit the use case.
4. Save. The block participates in the same {{variable}} substitution as every other text-bearing block — you don't need a special field, hook, or webhook.

2. Call from your auth provider

The code-generation half of the flow stays on your side (your auth provider mints the code). Apex renders and delivers.

3. Validate the code on the user's response

Apex never sees or stores the code value beyond the render-and-deliver pass. Validation stays on your side — your auth provider knows the expected value and the expiration window. Pair the send with whatever short-lived store you already use for OTP state (Cognito's built-in code, Auth0's MFA cache, your own Redis row).

Anti-patterns

• Don't pass the code in tags. Tags are metadata for the COMM record (analytics, idempotency, audit). Variables are what the renderer substitutes. Putting the code in tags will leak it to the analytics tab and won't substitute.
• Don't store the code on the template. The block's {{code}} placeholder is not the code itself — it's the binding. The actual value comes from the caller every send.
• Don't reuse the same Idempotency-Key across attempts. Auth flows often retry on user-typed wrong-code attempts; each attempt is a distinct send and needs a distinct key. Use <flow>-<userId>-<attemptId>.
• Don't put the code in a generic Text block. The Code block gives you the monospace + brand-color treatment, owns its own <table> wrapper for email-client compatibility, and signals intent to anyone editing the template later.

Sandbox helpers

Combine X-Apex-Mode: sandbox or send to anything@sandbox.apex.inc:

• Local-part contains bounce → deterministic simulated bounce (422).
• Contains suppress → suppression outcome (422).
• Otherwise → synthetic SES success (message_id prefixed sbx_).

Rate limits

Per-key throughput inherits the workspace organization plan mapping used elsewhere (free → starter → pro → growth → scale). Responses include X-RateLimit-* headers.

Errors

Comparison notes

Official SDKs:

• TypeScript / Node 18+ → @apex-inc/transactional on npm (retries, sandbox helpers, typed errors).
• Python 3.10+ → reference client in-repo (stdlib-only; install from git or vendor).
• Ruby 3.0+ → reference client in-repo (stdlib-only; install from git or vendor).