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](/docs/ai-integration/mcp-claude) instead              |
| Any language other than TypeScript or JavaScript  | Use the [Tools API](/docs/ai-integration/tools-api) or REST API |

## Install

```bash
pnpm add lumail
```

## Web App Integration Pattern

```typescript
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

```typescript
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

```typescript
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:

```typescript
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](/docs/ai-integration/mcp-claude) or the [Tools API](/docs/ai-integration/tools-api).

## Related

- [SDK Introduction](/docs/sdk/introduction)
- [SDK Configuration](/docs/sdk/configuration)
- [SDK Resources](/docs/sdk/resources)
- [Tools API with SDK](/docs/sdk/tools)
- [TypeScript SDK Reference](/docs/api-reference/sdk)