Owlat Docs

Transactional Email Setup

Set up and send transactional emails like password resets and order confirmations via the Owlat API.

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.

Common examples:

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

Create a Transactional Template

Start by building the template your transactional emails will use.

  1. Go to Templates in your Owlat dashboard
  2. Click New Template and give it a clear name (e.g., "Order Confirmation")
  3. Design your email in the visual editor
  4. Add data variables wherever you need dynamic content using {{variableName}} syntax -- for example, {{customerName}}, {{orderNumber}}, or {{total}}
  5. Save the template and note its slug (e.g., order-confirmation). You'll use this slug when sending via the API.

Use descriptive variable names like {{orderNumber}} instead of generic ones like {{var1}}. It makes your API calls self-documenting and easier to debug.

Generate an API Key

You need an API key to authenticate transactional sends.

  1. Go to Settings > API Keys in your dashboard
  2. Click Create API Key
  3. Give it a name (e.g., "Production Transactional")
  4. Select transactional send permissions
  5. Copy the generated key -- it starts with lm_live_

Your API key is shown only once. Store it in a secure location like an environment variable or a secrets manager. Never commit API keys to version control or expose them in client-side code.

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_...')

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

The SDK handles authentication, serialization, and error handling for you. Pass any data variables your template expects in the dataVariables object.

Send via the Java SDK

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

owlat.transactional().send(
    SendParams.builder("user@example.com", "order-confirmation")
        .dataVariable("orderNumber", "#12345")
        .dataVariable("customerName", "Jane")
        .dataVariable("total", "$49.99")
        .build()
);

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 200 status with a message ID you can use to track delivery.

Testing Transactional Emails

You don't need to write code to test your transactional templates:

  1. Open your template in the Owlat dashboard
  2. Click Send Test
  3. Fill in sample values for your data variables
  4. Enter your email address and send

This lets you verify formatting, variable substitution, and rendering before wiring up your application.

Send test emails to multiple email clients (Gmail, Outlook, Apple Mail) to catch rendering differences before going live.

Error Handling

When a transactional send fails, the API returns an error with a descriptive status code:

Status CodeMeaning
400Bad request -- check your payload for missing or invalid fields
401Unauthorized -- your API key is invalid or missing
404Template not found -- verify the slug matches an existing template
422Validation error -- a required data variable is missing
429Rate limited -- you're sending too many requests; back off and retry
500Server error -- retry after a short delay

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.

Don't silently swallow send errors. Log failures and set up alerts so your team knows when transactional emails aren't being delivered. A failed password reset email means a locked-out user.

Next Steps

Next Deliverability