TypeScript SDK Integrations

Use the Lumail TypeScript SDK in web apps, backend services, scripts, and product automations.

The Lumail TypeScript SDK is not an AI-agent framework. It is a typed wrapper around the Lumail API that makes common email marketing operations easier to integrate in your own application.

Use it when you want to create subscribers from signup flows, send transactional email from your backend, trigger campaigns from product events, or call Lumail tools from server-side code.

When to Use the SDK

Use case	Recommended
Web app or SaaS backend integration	Yes
Checkout, onboarding, or product-event automation	Yes
Serverless functions and internal scripts	Yes
Claude, Cursor, or another MCP client	Use MCP instead
Any language other than TypeScript or JavaScript	Use the Tools API or REST API

Install

pnpm add lumail

Web App Integration Pattern

import { Lumail } from "lumail";

const lumail = new Lumail({ apiKey: process.env.LUMAIL_API_KEY! });

export async function registerLead(input: {
  email: string;
  name?: string;
  plan: string;
}) {
  const { subscriber } = await lumail.subscribers.create({
    email: input.email,
    name: input.name,
    tags: ["product-signup", input.plan],
    fields: {
      plan: input.plan,
      signupDate: new Date().toISOString(),
    },
    triggerWorkflows: true,
  });

  await lumail.events.create({
    eventType: "SUBSCRIBED",
    subscriber: input.email,
    data: { plan: input.plan, source: "app-signup" },
  });

  return subscriber;
}

Backend Automation Pattern

import { Lumail, LumailNotFoundError, LumailRateLimitError } from "lumail";

const lumail = new Lumail({ apiKey: process.env.LUMAIL_API_KEY! });

export async function syncCustomerProfile(
  email: string,
  fields: Record<string, string>,
) {
  try {
    return await lumail.subscribers.update(email, { fields });
  } catch (error) {
    if (error instanceof LumailNotFoundError) {
      return lumail.subscribers.create({ email, fields });
    }

    if (error instanceof LumailRateLimitError) {
      const delay = error.retryAfter ?? 5000;
      await new Promise((resolve) => setTimeout(resolve, delay));
      return syncCustomerProfile(email, fields);
    }

    throw error;
  }
}

Campaign Workflow Pattern

export async function scheduleWeeklyDigest(scheduledAt: Date) {
  const { campaignId } = await lumail.campaigns.create({
    subject: `Weekly digest - ${scheduledAt.toLocaleDateString()}`,
    name: "Weekly Digest",
    contentType: "MARKDOWN",
  });

  await lumail.campaigns.send(campaignId, {
    scheduledAt: scheduledAt.toISOString(),
    timezone: "Europe/Paris",
  });

  return campaignId;
}

Tools from Your App

For operations that are exposed as Lumail tools, call the V2 tools API through the SDK:

const stats = await lumail.tools.run("get_dashboard_stats", {
  period: "30d",
});

const { tools } = await lumail.tools.list();
console.log(`${tools.length} tools available`);

These calls are still regular API integrations. If you want an AI assistant to discover and call tools directly, use MCP or the Tools API.

PreviousCursor (MCP)NextTools API (v2)