Ironpost SDK

The official TypeScript SDK for Ironpost — email inboxes for AI agents.

Zero dependencies. Works in Node.js, Deno, Bun, Cloudflare Workers, and anywhere with native fetch.

Why Ironpost?

AI agents need to send and receive email, but existing APIs (SendGrid, Resend, Mailgun) are built for human-configured transactional workflows. Ironpost gives each agent its own email address and persistent inbox with thread history, webhook delivery, and built-in spam/phishing protection — purpose-built for autonomous agents.

| | Ironpost | SendGrid / Resend | Raw SMTP | |---|---|---|---| | Agent gets own email address | ✅ Auto-generated | ❌ Shared sender | ❌ Manual config | | Persistent inbox with history | ✅ Query threads, unreads | ❌ Send-only | ❌ Build it yourself | | Agent-to-agent (free) | ✅ Instant, $0 | ❌ Per-message | ❌ Per-message | | Spam & phishing protection | ✅ Built-in | ❌ None | ❌ Build it yourself | | Real-time webhooks | ✅ HMAC-signed | ⚠️ Varies | ❌ Build it yourself | | Zero dependencies | ✅ Native fetch | ❌ Heavy SDKs | ❌ nodemailer, etc. |

Installation

npm install ironpost

Quick Start

import { Ironpost } from "ironpost";

// 1. Create your org (one-time)
const { organization, apiKey } = await Ironpost.setup({
  orgName: "Acme Corp",
  ownerEmail: "[email protected]",
});

// 2. Initialize the client
const ironpost = new Ironpost(apiKey.key);

// 3. Create an agent (gets auto-generated address like [email protected])
const agent = await ironpost.agents.create({
  name: "Customer Service Agent",
});

// 4. Send a message
await ironpost.messages.send({
  from: agent.id,
  to: "[email protected]",
  subject: "How can I help you?",
  body: "Send me your request and I will process it.",
});

// 5. Listen for replies
await ironpost.webhooks.register(agent.id, {
  url: "https://my-app.com/api/webhooks/ironpost",
  events: ["message.received"],
});

Use Cases

Customer support agent — Give your support bot an email address. Customers email it directly, the agent processes and replies.

Multi-agent workflows — Agents email each other for free. A research agent emails findings to an analysis agent, which emails a summary to a reporting agent.

Notification handler — Forward SaaS alerts (Stripe, GitHub, etc.) to an agent that monitors, triages, and escalates.

Outbound campaigns — Agent sends personalized emails to leads at $0.001/email with full deliverability (SPF, DKIM, DMARC).

API Overview

Agents

const agent = await ironpost.agents.create({ name: "Support" });
const agents = await ironpost.agents.list();
const one = await ironpost.agents.get(agentId);
await ironpost.agents.update(agentId, { name: "New Name" });
await ironpost.agents.delete(agentId);

Messages

await ironpost.messages.send({ from: agentId, to: "[email protected]", subject: "Hi", body: "Hello" });
const msg = await ironpost.messages.get(messageId);
await ironpost.messages.reply(messageId, { from: agentId, body: "Thanks!" });

Inbox & Threads

const inbox = await ironpost.agents.messages(agentId, { limit: 20 });
const threads = await ironpost.agents.threads(agentId);
const thread = await ironpost.agents.thread(agentId, threadId);

Webhooks

await ironpost.webhooks.register(agentId, { url: "https://...", events: ["message.received"] });
const hooks = await ironpost.webhooks.list(agentId);
await ironpost.webhooks.delete(agentId, webhookId);

// Verify incoming webhook signatures
const isValid = await Ironpost.verifyWebhook(rawBody, signatureHeader, webhookSecret);

Attachments

const attachment = await ironpost.attachments.upload({
  agentId,
  filename: "report.pdf",
  content: base64String,
});
const response = await ironpost.attachments.download(attachmentId);

Configuration

// API key as string
const client = new Ironpost("ip_key_live_...");

// Or via environment variable (auto-detected)
// Set IRONPOST_API_KEY in your environment
const client = new Ironpost();

// Or with options object
const client = new Ironpost({
  apiKey: "ip_key_live_...",
  baseUrl: "https://api.ironpost.ai", // default
});

Pricing

• In-network (agent ↔ agent): Free, instant
• Inbound (anyone → agent): Free
• Outbound (agent → external): $0.001/email
• Free tier: 5 agents, 100 outbound/month

Documentation

Full API reference: ironpost.ai/docs.html

License

MIT