This guide shows how to use AgentMailr from Node.js and TypeScript. All examples use the built-in fetch API available in Node 18+.

Setup

const API_KEY = process.env.AGENTMAILR_API_KEY;
const BASE = "https://api.agentmailr.com";

const headers = {
  "X-API-Key": API_KEY!,
  "Content-Type": "application/json",
};

Create an Inbox

async function createInbox(name?: string) {
  const res = await fetch(`${BASE}/v1/inboxes`, {
    method: "POST",
    headers,
    body: JSON.stringify({ name }),
  });
  return res.json() as Promise<{ id: string; address: string }>;
}

const inbox = await createInbox("my-agent");
console.log(inbox.address); // my-agent@agentmailr.com

Wait for OTP

async function waitForOtp(inboxId: string, timeout = 60) {
  const res = await fetch(
    `${BASE}/v1/inboxes/${inboxId}/otp?timeout=${timeout}`,
    { headers, signal: AbortSignal.timeout((timeout + 5) * 1000) }
  );
  const data = await res.json() as { code: string };
  return data.code;
}

const code = await waitForOtp(inbox.id);
console.log("OTP:", code);

Send Email

async function sendEmail(inboxId: string, to: string, subject: string, text: string) {
  const res = await fetch(`${BASE}/v1/inboxes/${inboxId}/send`, {
    method: "POST",
    headers,
    body: JSON.stringify({ to, subject, text }),
  });
  return res.json();
}

await sendEmail(inbox.id, "recipient@example.com", "Hello", "Test");

Install the Official SDK

If you prefer a typed SDK over raw fetch:

npm install @agentmailr/sdk

The SDK wraps all endpoints with full TypeScript types and handles retries automatically.