TypeScript SDK

npm install @deadsimple/email

import { DeadSimple } from "@deadsimple/email";

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.",
});

// 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);

// authorizationUrl is the app's "Sign in with Dead Simple" link
// (its /authorize URL with PKCE, state and scopes already set).
const result = await client.identity.signIn(inbox.inboxId, authorizationUrl)
console.log(result.redirectTo, result.finalUrl, result.status)

// Agents that should not hold a full API key: enrol a P-256 public key once,
// then sign a short-lived ES256 assertion at sign-in time.
const key = await client.identity.enrollKey(inbox.inboxId, { publicKey: agentPublicKeyPem, name: "worker-7" })
await client.identity.listKeys(inbox.inboxId)        // shows lastUsedAt per key
await client.identity.deleteKey(inbox.inboxId, key.kid)

// Every app the inbox has signed in to, with scope and sign-in counts
await client.identity.connections(inbox.inboxId)

// Create, then invite. Nothing is sent until invite.
const event = await client.calendar.create(inboxId, {
  title: "Kickoff",
  start: "2026-09-22T11:00:00", timezone: "America/New_York",
  duration_minutes: 30,
  attendees: ["dana@example.com"],
})
const sent = await client.calendar.invite(inboxId, event.event_id, { textBody: "Agenda to follow." })

// Reschedule: update raises sequence, invite again sends a revision, not a duplicate
await client.calendar.update(inboxId, event.event_id, { start: "2026-09-23T11:00:00", timezone: "America/New_York" })
await client.calendar.invite(inboxId, event.event_id)

// Invitations that arrived by email are already on the calendar (source === "inbound")
const { events } = await client.calendar.list(inboxId, { status: "confirmed" })
for (const ev of events) {
  if (ev.source === "inbound") await client.calendar.rsvp(inboxId, ev.event_id, "accepted", { comment: "See you then." })
}

// Subscription URLs for Google Calendar, Apple Calendar or Outlook; rotate if the URL leaks
const feed = await client.calendar.feed(inboxId)   // feed.feed_url, feed.webcal_url
await client.calendar.rotateFeed(inboxId)

// Every event on every inbox the key can see
await client.calendar.listAll({ from: "2026-09-21", to: "2026-09-27" })

// Last 30 days, daily buckets (the defaults)
const m = await client.metrics.get()
console.log(m.totals.sent, m.totals.received, m.totals.bounced)

// One week, hourly, for two inboxes
const week = await client.metrics.get({
  from: "2026-09-10", to: "2026-09-17", interval: "hour",
  inboxIds: [supportId, billingId],
})
for (const bucket of week.series) {
  if (bucket.webhook_failures || bucket.injection_flagged) console.log(bucket.start, bucket)
}

// A key for one agent, limited to its own inbox
const key = await client.apiKeys.create({
  name: "support-agent", permissions: ["read", "write"], inboxIds: [supportId],
})
console.log(key.key)   // shown once

// A webhook that only hears that inbox
const hook = await client.webhooks.create({
  url: "https://agents.example.com/hooks/support",
  events: ["message.received", "calendar.event.created"],
  inboxIds: [supportId],
})

// Change the scope later; inboxIds: [] makes it account-wide again
await client.webhooks.update(hook.webhook_id, { inboxIds: [supportId, billingId] })
await client.webhooks.get(hook.webhook_id)

import { verifyWebhook } from "@deadsimple/email";

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");
}

import { getTools } from "@deadsimple/email/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",
});

// 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",
});