TypeScript SDK

Installation

          
          terminal
        
npm install deadsimple

Quick Start

Create a client, make an inbox, and send your first email:

          
          quickstart.ts
        
import { DeadSimple } from "deadsimple";

const client = new DeadSimple("dse_your_api_key");
const inbox = await client.inboxes.create({ displayName: "My Agent" });

await client.messages.send({
  inboxId: inbox.inbox_id,
  to: "user@example.com",
  subject: "Hello from my agent",
  textBody: "This email was sent by an AI agent.",
});

Resources

Every API endpoint is available as a typed method on the client:

Resource	Methods
`client.inboxes`	`create`, `list`, `get`, `delete`, `bulkCreate`, `bulkDelete`
`client.messages`	`send`, `list`, `get`, `reply`, `forward`
`client.threads`	`list`, `get`
`client.webhooks`	`create`, `list`, `delete`
`client.domains`	`add`, `list`, `verify`, `delete`
`client.usage`	`get`

Reading Messages

List messages in an inbox and read individual message content:

          
          
          
          read-messages.ts
        

// List recent messages
const messages = await client.messages.list({
  inboxId: "inb_abc123",
  limit: 10,
});

// Read full content of a specific message
const message = await client.messages.get({
  inboxId: "inb_abc123",
  messageId: messages.data[0].message_id,
});

console.log(message.subject, message.text_body);
        

Webhook Verification

The SDK includes a helper to verify webhook signatures in your Express or Next.js routes:

          
          webhook.ts
        
import { verifyWebhook } from "deadsimple";

export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get("x-dse-signature");

  const event = verifyWebhook(body, signature, process.env.DSE_WEBHOOK_SECRET);

  if (event.type === "message.received") {
    console.log("New email from:", event.data.from);
  }

  return new Response("ok");
}

Vercel AI SDK Integration

The package includes a deadsimple/ai subpath export with Zod-validated tool definitions for the Vercel AI SDK. This lets you give any AI model email capabilities in one line:

          
          ai-tools.ts
        
import { getTools } from "deadsimple/ai";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const tools = getTools("dse_your_api_key");

const result = await generateText({
  model: openai("gpt-4o"),
  tools,
  prompt: "Send a welcome email to new-user@example.com",
});

See the full Vercel AI SDK integration docs for streaming, multi-step agents, and raw function definitions.

Configuration

The client accepts the API key directly, or reads it from the DSE_API_KEY environment variable:

          
          config.ts
        
// Explicit key
const client = new DeadSimple("dse_your_api_key");

// Or from environment (reads DSE_API_KEY automatically)
const client = new DeadSimple();

// Custom base URL (for self-hosted or testing)
const client = new DeadSimple("dse_key", {
  baseUrl: "https://api.your-domain.com",
});