@yup.email/sdk

Receive and inspect email in automated tests. Node.js 22+, ESM and CommonJS.

The npm package includes the SDK's TypeScript source in src/ for inspection. Imports use the compiled JavaScript and type declarations in dist/.

npm install @yup.email/sdk

import { YupEmail } from "@yup.email/sdk";

const yup = new YupEmail({ apiKey: process.env.YUP_EMAIL_API_KEY! });
const inbox = await yup.inboxes.create();

try {
  // Trigger your application's email flow using inbox.address.
  const message = await yup.messages.waitFor({
    inboxId: inbox.id,
    subjectContains: "Verify",
    timeoutMs: 30_000,
  });
  console.log(message.artifacts.otpCodes, message.artifacts.links);
} finally {
  await yup.inboxes.delete(inbox.id);
}

For reused inboxes, capture await yup.inboxes.checkpoint(inbox.id) before triggering email and pass the result as after to messages.waitFor or messages.list. Without after, already-arrived mail is eligible. Messages are ordered by storage sequence, oldest first. Waiting does not consume mail.

Resources: inboxes.create/get/list/delete/checkpoint, messages.list/get/delete/waitFor, mailDomains.list, usage.get. Lists return { data, nextCursor }; pass nextCursor as cursor on the next call, preserving filters. Single-resource methods unwrap { data }.

Client options: apiKey, baseUrl (defaults to https://yup.email/api/v1), fetch, timeoutMs (10 seconds), maxRetries (2). Operations accept { signal, timeoutMs }. waitFor accepts these alongside its filters and pollIntervalMs (1 second); its default overall deadline is 30 seconds.

Only GET requests retry, with backoff and Retry-After, within the operation deadline. Writes never retry automatically. A timed-out create may have succeeded; inspect inboxes before retrying. Create requests do not yet support idempotency keys.

YupEmailError includes status, code, requestId, and retryAfterMs. WaitTimeoutError includes timeoutMs and filters. Cancellation preserves the supplied signal's reason. Request deadlines throw TimeoutError.

Keep API keys in server/CI secrets, never browser bundles. Documentation: https://yup.email/docs