@stablyai/email

Email inbox SDK for end-to-end testing. Receive, filter, and manage test emails in your Playwright tests.

Installation

npm install @stablyai/email

Setup

Get your API key and project ID from the Stably dashboard.

Either set your Stably credentials as environment variables:

export STABLY_API_KEY="your-api-key"
export STABLY_PROJECT_ID="your-project-id"

Or pass them programmatically to Inbox.build():

const inbox = await Inbox.build({
  apiKey: "your-api-key",
  projectId: "your-project-id",
});

Usage

import { Inbox } from "@stablyai/email";

// Create an inbox with a unique suffix for test isolation
const inbox = await Inbox.build({ suffix: `test-${Date.now()}` });
console.log(inbox.address); // "[email protected]"

// Wait for an email to arrive
const email = await inbox.waitForEmail({
  subject: "Welcome",
  timeoutMs: 30000,
});

// Access email content
console.log(email.subject);
console.log(email.textBody);
console.log(email.htmlBody);

// List all emails in the inbox
const { emails } = await inbox.listEmails();

// Extract data from email using AI
const otp = await inbox.extractFromEmail({
  id: email.id,
  prompt: "Extract the OTP code",
});

// Clean up
await inbox.deleteAllEmails();

API

Inbox.build(options?)

Creates an inbox instance scoped to your organization's email address.

• suffix - Optional suffix for test isolation (e.g., creates "[email protected]")
• apiKey - Stably API key (defaults to STABLY_API_KEY env var)
• projectId - Stably project ID (defaults to STABLY_PROJECT_ID env var)

inbox.waitForEmail(options?)

Waits for an email matching the filters to arrive.

• subject - Filter by subject (substring match)
• from - Filter by sender address
• timeoutMs - Maximum wait time (default: 30000)
• pollIntervalMs - Poll interval (default: 2000)

inbox.listEmails(options?)

Lists emails in the inbox. By default, only returns emails received after the inbox was created.

inbox.getEmail(id)

Gets a specific email by ID.

inbox.deleteEmail(id)

Deletes a specific email.

inbox.deleteAllEmails()

Deletes all emails sent to this inbox's address.

inbox.extractFromEmail(args)

Extracts data from an email using AI.

• id - The email ID
• prompt - Description of what to extract
• schema - Optional Zod v4 schema for structured output

// Simple extraction
const otp = await inbox.extractFromEmail({
  id: email.id,
  prompt: "Extract the OTP code",
});

// Structured extraction with Zod schema
import { z } from "zod/v4";

const { code, expiresAt } = await inbox.extractFromEmail({
  id: email.id,
  prompt: "Extract the verification code and expiry",
  schema: z.object({ code: z.string(), expiresAt: z.string() }),
});