Transactional Email Setup

Transactional emails are triggered by a user action — a password reset, an order confirmation, a welcome message after signup. Unlike marketing campaigns, they're sent to a single recipient at a specific moment, and recipients expect them immediately. This guide walks through creating a transactional email, generating an API key, and sending from your application.

For the conceptual overview (transactional vs. marketing, slugs, attachments, monitoring), see Transactional Emails. This page focuses on the integration steps.

Common examples:

• Password reset links
• Welcome emails after registration
• Order confirmations and receipts
• Shipping notifications
• Account verification emails

Create a transactional email

Transactional emails are a distinct entity from marketing templates — each one has a unique slug your application references at send time.

Generate an API key

You need an API key to authenticate transactional sends.

Send via the TypeScript SDK

Install the Owlat SDK and send your first transactional email:

import { Owlat } from '@owlat/sdk-js'

const owlat = new Owlat('lm_live_...')

const result = await owlat.transactional.send({
  email: 'user@example.com',
  slug: 'order-confirmation',
  dataVariables: {
    orderNumber: '#12345',
    customerName: 'Jane',
    total: '$49.99',
  },
})

// result.transactionalEmailId — the send-record id, use it to track delivery

The SDK handles authentication, serialization, and error handling for you. Pass any data variables your email expects in the dataVariables object. You can target an email by slug or by transactionalId.

Send via the Java SDK

Owlat owlat = new Owlat("lm_live_...");

owlat.transactional().send(
    SendTransactionalParams.builder("user@example.com")
        .slug("order-confirmation")
        .dataVariables(Map.of(
            "orderNumber", "#12345",
            "customerName", "Jane",
            "total", "$49.99"
        ))
        .build()
);

The builder takes the recipient email as its only positional argument; set the slug with .slug(...) and pass all variables at once with .dataVariables(Map).

Send via cURL

If you prefer to call the API directly:

curl -X POST https://your-deployment.convex.site/api/v1/transactional \
  -H "Authorization: Bearer lm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "order-confirmation",
    "email": "user@example.com",
    "dataVariables": {
      "orderNumber": "#12345",
      "customerName": "Jane",
      "total": "$49.99"
    }
  }'

A successful request returns a 202 Accepted status — the email is queued for delivery, not sent synchronously. The response body includes:

View API code in the dashboard

You don't have to hand-write the call. On the Transactional list, each email has a View API Code action (the < > icon, also in the row's menu) that opens a ready-made send snippet in cURL, JavaScript, and Python — pre-filled with the email's slug. Copy it, drop in your API key, and you're sending.

Error handling

When a transactional send fails, the API returns one of the categorized statuses below. Map your retry logic to the status code, not the message text.

For 429 and 500 errors, implement exponential backoff in your retry logic. Transactional emails are important to your users, so build resilience into your sending code.

Next steps

• Transactional API — full endpoint and field reference
• TypeScript SDK — complete SDK reference
• Java SDK — Java SDK reference
• Webhooks — get notified about delivery events in real time