npm package: @stablyai/email
Description: Email inbox SDK for end-to-end testing
Latest version: 0.1.2

<p align="center">
  <a href="https://stably.ai">
    <h3 align="center">Stably</h3>
  </a>
</p>

<p align="center">
  Code. Ship. 
Test.

</p>

<p align="center">
  <a href="https://docs.stably.ai/"><strong>Documentation</strong></a> ·
  <a href="https://stably.ai/"><strong>Homepage</strong></a>
</p>
<br/>

# @stablyai/email

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

## Installation

```bash
npm install @stablyai/email
```

## Setup

Get your [API key](https://auth.stably.ai/account/api_keys) and project ID from the Stably dashboard.

Either set your Stably credentials as environment variables:

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

Or pass them programmatically to `Inbox.build()`:

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

## Usage

```ts
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); // "your-org+test-1234567890@mail.stably.ai"

// 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 "org+suffix@mail.stably.ai")
- `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

```ts
// 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() }),
});
```