AgenticEmail TypeScript SDK

The official TypeScript library for the AgenticEmail API — programmatic inboxes, send and receive email, webhooks, and real-time events for AI agents.

Installation

npm install agenticemail

Usage

import { AgenticEmail } from "agenticemail";

const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY! });

// Give your agent an inbox in one call
const inbox = await client.inboxes.create({ username: "support", domain: "acme.io" });

// Send
await client.messages.send(inbox.id, {
  to: ["customer@example.com"],
  subject: "Hello",
  text: "Sent from an agent.",
});

// Read
const threads = await client.threads.list(inbox.id);

Requests and responses are converted between camelCase (SDK) and snake_case (API) automatically. Get an API key from the dashboard.

Real-time events

const stream = client.events.connect({ eventTypes: ["message.received"] });
const unsubscribe = stream.on((event) => {
  console.log(event.type, event.data);
});
// later: unsubscribe(); stream.close();

Webhook verification

Verify webhook signatures (HMAC-SHA256, webhook-id / webhook-timestamp / webhook-signature headers):

import { verifyWebhook } from "agenticemail";

const event = verifyWebhook(rawBody, req.headers, process.env.WEBHOOK_SECRET!);
if (event.type === "message.received") {
  // ...
}

verifyWebhook throws AgenticEmailError when the signature is invalid.

Error handling

All non-2xx responses throw AgenticEmailError with .status, .code, and .message:

import { AgenticEmailError } from "agenticemail";

try {
  await client.inboxes.get("missing");
} catch (err) {
  if (err instanceof AgenticEmailError) {
    console.error(err.status, err.code, err.message);
  }
}

Self-hosted

Point the client at your own deployment:

const client = new AgenticEmail({
  apiKey: "am_...",
  baseUrl: "https://your-agenticemail-host",
});

API surface

See api.md for every resource and method: inboxes, messages, threads, drafts, lists, webhooks, domains, apiKeys, events.

Requirements

Node.js 18+ (Node 22+, Bun, or a browser for the WebSocket event stream). TypeScript types are bundled.

Contributing

See CONTRIBUTING.md. This repo is an exported snapshot of the SDK developed in the AgenticEmail monorepo.

Related

• CLI: the same API as JSON-first shell commands — npm install -g agenticemail-cli, including wait-for-message for agent loops
• Python SDK: pip install agenticemail
• Docs: guides, CLI, MCP server, and the interactive API reference

License

Apache-2.0