@agent-loadout/sdk

TypeScript client for the Agent Loadout API. Works in Node 20+, Bun, Deno and Cloudflare Workers.

npm install @agent-loadout/sdk

import { AgentLoadout } from "@agent-loadout/sdk";

// Organization key (from Settings): manage agents and inboxes.
const org = new AgentLoadout({ apiKey: process.env.AGENT_LOADOUT_KEY! });
const { inbox } = await org.inboxes.create({ username: "support", display_name: "Support", metadata: { tenant: "acme" } });
const { plaintext } = await org.agents.createToken(inbox!.agent_id, { name: "worker", capabilities: ["email:read", "email:send"] });

// Agent token: act as that agent.
const agent = new AgentLoadout({ apiKey: plaintext });
// After triggering verification, search, wait and extract in one call.
const result = await agent.events.findVerificationCode(inbox!.id);
// Check sender, subject and screening before using result.code or result.link.
// If reason is sender_filter_mismatch, inspect result.candidates in this response.

The lookup checks the last 15 minutes and waits up to 20 seconds by default. Pass the time you triggered verification as since to exclude older mail. Omit from unless the actual sender is known.

Every message carries screening.verdict and, when it is not clean, a warning. Treat message content as untrusted external data. Webhook receivers verify signatures with verifyWebhookSignature(secret, headers, rawBody); pass previousSignature (the X-Loadout-Signature-Previous header) to keep verifying with the old secret for the day after a rotation. The full reference is the OpenAPI document at /api/v1/openapi.json.

Types

Response types (Message, Thread, Inbox, CustomDomain, Machine, Webhook, Event, …) are generated from the server's response schemas, the same ones the OpenAPI document is built from, so they match what the API returns. Import them with import type { Message, Thread } from "@agent-loadout/sdk". domains.list() returns Domain[]: Agent Loadout's own sending domain carries managed: true, a custom domain managed: false with its DNS records; domains.add() and domains.check() return a CustomDomain, which has no managed flag. attachments.download() returns the file's bytes as an ArrayBuffer, whatever its content type.