@cybertemp/sdk

Official JavaScript / TypeScript SDK for CyberTemp — disposable email inboxes for testing, automation, OTP flows, and AI agents.

• Spin up a temp inbox in one call
• Poll for incoming mail with a sane timeout
• Pull a one-time code out of the body without parsing HTML yourself
• Typed errors for UpgradeRequired and RateLimited
• ESM + CJS dual build, Node 18+ (uses the global fetch)
• Zero runtime dependencies

Install

npm install @cybertemp/sdk
# or
pnpm add @cybertemp/sdk
# or
yarn add @cybertemp/sdk

You'll need an API key — get one at https://www.cybertemp.xyz/settings.

Quickstart

import { CybertempClient } from "@cybertemp/sdk";

const client = new CybertempClient("tk_...");

const inbox = await client.createInbox();
console.log("inbox:", inbox.address);

// Block until something arrives or 30s passes
const otp = await client.waitForOTP(inbox.id, { timeoutMs: 30_000 });
console.log("OTP:", otp);

await client.deleteInbox(inbox.id);

CommonJS works too:

const { CybertempClient } = require("@cybertemp/sdk");
const client = new CybertempClient("tk_...");

API

client.createInbox({ domain?, username? });          // Allocate a new inbox
client.listInboxes();                                // Inboxes owned by your key
client.readMessages(id, limit = 25, offset = 0);     // Most recent first
client.waitForMessage(id, { timeoutMs, filter });    // Polls until match or timeout
client.waitForOTP(id, { timeoutMs });                // Extracts 4–8 digit code (Pro plan)
client.deleteInbox(id);                              // Frees a slot

Constructor accepts either an API key string or an options object:

new CybertempClient("tk_...");
new CybertempClient({
  apiKey: "tk_...",
  baseUrl: "https://api.cybertemp.xyz",   // override (e.g. for self-hosted)
  fetch: customFetch,                      // inject undici / mocked fetch
  timeoutMs: 30_000,                       // per-request timeout
});

Errors

import {
  CybertempClient,
  UpgradeRequiredError,
  RateLimitError,
  APIError,
} from "@cybertemp/sdk";

try {
  const otp = await client.waitForOTP(inbox.id);
} catch (err) {
  if (err instanceof UpgradeRequiredError) {
    console.log("Upgrade to", err.requiredTier, "at", err.upgradeUrl);
    return;
  }
  if (err instanceof RateLimitError) {
    await new Promise((r) => setTimeout(r, err.retryAfterMs));
    // retry…
    return;
  }
  if (err instanceof APIError) {
    console.error("API", err.status, err.bodyText);
    return;
  }
  throw err;
}

Use cases

• Playwright / Cypress / Puppeteer — sign up a fresh user every run, intercept the verification email, extract the OTP, click through. No mailbox mocking, no flaky shared inboxes.
• AI agents (Claude / GPT) — spin up an inbox per task, let the agent sign up for services and confirm itself.
• Manual QA — burst-create 50 inboxes for a workflow demo, then deleteInbox them at the end.

Links

• Website: https://www.cybertemp.xyz
• Get an API key: https://www.cybertemp.xyz/settings
• API docs: https://www.cybertemp.xyz/api-docs
• npm: https://www.npmjs.com/package/@cybertemp/sdk

License

MIT