TypeScript and JavaScript · Integrations docs

A small typed helper#

Every endpoint is plain JSON over HTTPS, so the built-in fetch is all you need. Keep the key on the server.

TypeScript

const BASE = "https://botinbox.dev/v0";

async function botinbox<T>(path: string, init: RequestInit = {}): Promise<T> {
  const res = await fetch(BASE + path, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.BOTINBOX_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`${res.status} ${err.code ?? ""} ${err.error ?? res.statusText}`);
  }
  return res.status === 204 ? (undefined as T) : res.json();
}

Create an inbox and send#

The create response includes the inbox ID and address. Pass reply_to_message_id when answering a message to keep the thread.

TypeScript

const inbox = await botinbox<{ id: string; email: string }>("/inboxes", {
  method: "POST",
  body: JSON.stringify({ username: "scout", display_name: "Scout Agent" }),
});

await botinbox(`/inboxes/${inbox.id}/messages`, {
  method: "POST",
  body: JSON.stringify({ to: ["human@example.com"], subject: "Hello", text: "Sent by my agent" }),
});

Search and paginate#

Lists return data and next_cursor. Pass the cursor back to get the next page.

TypeScript

const { data, next_cursor } = await botinbox<{ data: unknown[]; next_cursor: string | null }>(
  "/inboxes/INBOX_ID/messages?q=invoice&unread=true&limit=25"
);

Generated clients#

Prefer generated types? Point an OpenAPI generator at /v0/openapi.json. An official TypeScript SDK on npm is coming soon; these docs will show the install command when it ships.