Node.js SDK

The official TypeScript/JavaScript SDK provides type-safe access to the AgentInbox API with automatic retries and error handling.

TypeScript First

The SDK is written in TypeScript and provides full type definitions out of the box. No additional @types package needed.

Installation

Install the SDK via npm, yarn, or pnpm.

bash

npm install AgentInbox

Configuration

Initialize the client with your API key. You can find your API key in the dashboard.

typescript

import { AgentInboxClient } from "AgentInbox";
 
const client = new AgentInboxClient({
  apiKey: process.env.AgentInbox_API_KEY!,
  // Optional: override base URL
  baseUrl: "https://agentinbox.in",
  // Optional: configure retries
  maxRetries: 3,
});

Creating an Inbox

Creating an inbox

const inbox = await client.inboxes.create({
  ttlSeconds: 3600,
  metadata: { workflow: "signup" },
});
 
console.log(inbox.id);           // "inb_123"
console.log(inbox.emailAddress); // "k3v9x2m4q7tz@agentinbox.in"
console.log(inbox.expiresAt);    // ISO timestamp

Waiting for Emails

Waiting for an OTP

const wait = await client.waits.create({
  inboxId: inbox.id,
  type: "otp",
  timeoutSeconds: 120,
});
 
if (wait.status === "completed") {
  console.log(wait.result?.value); // "123456"
} else if (wait.status === "timed_out") {
  console.log("No OTP received within timeout");
}

Error Handling

The SDK throws typed errors for different failure modes. Always wrap API calls in try/catch.

Error handling

import { AgentInboxError, RateLimitError, AuthenticationError } from "AgentInbox";
 
try {
  const inbox = await client.inboxes.create({ ttlSeconds: 3600 });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log("Rate limited, retry after:", err.retryAfter);
  } else if (err instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (err instanceof AgentInboxError) {
    console.log("API error:", err.message, err.statusCode);
  } else {
    console.log("Unexpected error:", err);
  }
}

Error Types

AuthenticationError — Invalid or missing API key
RateLimitError — Rate limit exceeded, includes retryAfter
NotFoundError — Resource does not exist
ValidationError — Invalid request parameters
AgentInboxError — Base class for all API errors

Advanced Usage

Sessions and workflows

// Create a session
const session = await client.sessions.create({ name: "signup-flow" });
 
// Run a workflow
const workflow = await client.workflows.createInboxAndWait({
  waitType: "otp",
  timeoutSeconds: 120,
  sessionId: session.id,
});
 
console.log(workflow.inbox.emailAddress);
console.log(workflow.wait.result?.value);

Next Steps

Python SDK

Python client library

Learn more

CLI Tool

Command-line interface

Learn more

MCP Server

Connect to AI agents

Learn more

API Reference

Complete endpoints and schemas

Learn more