Node SDK

The official AgentInbox SDK for TypeScript and JavaScript. It wraps the REST API with typed methods so you can create inboxes, read messages, and wait for verification emails from any Node.js runtime.

Published on npm

The package is published as agentinbox.in. It ships with full TypeScript types — no separate @types package needed.

Installation

bash

npm install agentinbox.in

Initialize the client

Create a single client and reuse it across your app. Store your key in the AGENTINBOX_API_KEY environment variable rather than hard-coding it.

client.ts

import { AgentInboxClient } from "agentinbox.in";
 
const client = new AgentInboxClient({
  apiKey: process.env.AGENTINBOX_API_KEY!,
});

Create an inbox

Every inbox gets a unique address and expires after ttlSeconds.

create-inbox.ts

const inbox = await client.inboxes.create({ ttlSeconds: 3600 });
 
console.log(inbox.emailAddress); // "k3v9x2m4q7tz@agentinbox.in"
console.log(inbox.id);           // "inb_123"

List inboxes

list-inboxes.ts

const inboxes = await client.inboxes.list({ limit: 10 });
 
for (const inbox of inboxes.data) {
  console.log(inbox.emailAddress, inbox.status);
}

Read messages

Once an email arrives, fetch the messages for an inbox. For OTP and magic-link flows, use waits to block until the email lands instead of polling.

read-messages.ts

// Fetch messages received by an inbox
const messages = await client.messages.list("00000000-0000-4000-8000-000000000001", 20);
 
for (const message of messages.data) {
  console.log(message.subject, message.fromEmail);
}

Clean up

Delete an inbox when you are done to free up quota.

cleanup.ts

await client.inboxes.delete("inb_123");

Error handling

Failed requests throw an AgentInboxError that carries the HTTP status and an error code so you can branch on rate limits, quota, or authentication failures.

errors.ts

import { AgentInboxClient, AgentInboxError } from "agentinbox.in";
 
const client = new AgentInboxClient({ apiKey: process.env.AGENTINBOX_API_KEY! });
 
try {
  const inbox = await client.inboxes.create({ ttlSeconds: 3600 });
  console.log(inbox.emailAddress);
} catch (err) {
  if (err instanceof AgentInboxError) {
    // err.status, err.code, err.message
    console.error(`AgentInbox ${err.status}: ${err.message}`);
  } else {
    throw err;
  }
}

Next Steps

Waits

Block until an OTP or magic link arrives

Learn more

Webhooks

Receive real-time events instead of polling

Learn more

API Reference

Complete endpoints and schemas

Learn more

Python SDK

Use AgentInbox from Python

Learn more