TypeScript SDK

The official @owlat/sdk-js package provides a typed client for interacting with the Owlat API from Node.js, Bun, Deno, or any server-side JavaScript runtime.

Installation

bun add @owlat/sdk-js

npm install @owlat/sdk-js

pnpm add @owlat/sdk-js

Quick start

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

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

// Send a transactional email
await owlat.transactional.send({
  email: 'recipient@example.com',
  slug: 'welcome-email',
  dataVariables: { firstName: 'Mira' }
})

You can also pass a configuration object:

const owlat = new Owlat({
  apiKey: 'lm_live_...',
  baseUrl: 'https://your-deployment.convex.site',
  timeout: 30000,
})

Resources

Contacts

Manage contacts in your audience.

// Create a contact
const contact = await owlat.contacts.create({
  email: 'mira@acme.io',
  firstName: 'Mira',
  lastName: 'Chen',
  language: 'en',
})

// Get a contact by ID
const found = await owlat.contacts.get('contact_abc123')

// Update a contact
const updated = await owlat.contacts.update('contact_abc123', {
  firstName: 'Mira',
  lastName: 'Chen-Lopez',
})

// List contacts with pagination
const result = await owlat.contacts.list({
  page: 1,
  limit: 25,
})
// result.data       — Contact[]
// result.pagination  — { page, limit, totalItems, totalPages }

// Delete a contact
await owlat.contacts.delete('contact_abc123')

Transactional

Send transactional emails using pre-built templates.

const result = await owlat.transactional.send({
  // Identify the template by slug or ID
  slug: 'order-confirmation',

  // Recipient
  email: 'buyer@example.com',

  // Data variables merged into the template
  dataVariables: {
    orderId: 'ORD-7291',
    total: '$142.00',
  },

  // Optional: override language
  language: 'de',

  // Optional: add recipient to your audience
  addToAudience: true,
})
// result.data.messageId — delivery tracking ID

Attachments

You can attach files using base64-encoded content or HTTPS URLs (max 10 files, 10 MB total):

await owlat.transactional.send({
  email: 'buyer@example.com',
  slug: 'order-confirmation',
  attachments: [
    // Base64-encoded content
    {
      filename: 'invoice.pdf',
      content: base64String,
      contentType: 'application/pdf',
    },
    // URL (fetched server-side)
    {
      filename: 'receipt.pdf',
      url: 'https://your-api.com/receipts/ORD-7291.pdf',
    },
  ],
})

Events

Send custom events to trigger automations and build segments.

await owlat.events.send({
  email: 'mira@acme.io',
  eventName: 'plan_upgraded',
  eventProperties: {
    plan: 'pro',
    mrr: 49,
  },
})

Lists

Manage mailing list memberships.

// Add a contact to a list
await owlat.lists.addContact({
  listId: 'list_abc123',
  email: 'mira@acme.io',
})

// Remove a contact from a list
await owlat.lists.removeContact({
  listId: 'list_abc123',
  emailOrId: 'mira@acme.io',
})

Error handling

The SDK exports typed error classes for common failure modes:

import {
  Owlat,
  OwlatError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
  ConflictError,
} from '@owlat/sdk-js'

try {
  await owlat.contacts.create({ email: 'invalid' })
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message)
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited — retry after backoff')
  } else if (error instanceof AuthenticationError) {
    console.error('Bad API key')
  } else if (error instanceof ConflictError) {
    console.error('Contact already exists')
  } else if (error instanceof OwlatError) {
    console.error('API error:', error.message, error.statusCode)
  }
}

Types

All request and response types are exported for use in your own code:

import type {
  Contact,
  CreateContactParams,
  UpdateContactParams,
  SendTransactionalParams,
  SendTransactionalResponse,
  TransactionalAttachment,
  SendEventParams,
  AddToListParams,
  PaginatedResponse,
  ApiResponse,
} from '@owlat/sdk-js'