Installation

npm install -D @mailoven/client
yarn add -D @mailoven/client
pnpm add -D @mailoven/client
bun add -D @mailoven/client

Quick start

import { MailOvenClient } from "@mailoven/client";

const client = new MailOvenClient({ apiKey: process.env.MAILOVEN_API_KEY, slug: "acme" });

// Poll until an email arrives, then read it
const email = await client.waitForEmail({ to: "signup" });
console.log(email.subject, email.bodyText);

API

| Method | Description | | --------------------------------- | ---------------------------------------------- | | getEmail(id) | Fetch a single email by ID | | listEmails(params) | List / search emails with optional filters | | waitForEmail(params, options?) | Poll until at least one matching email arrives | | waitForEmails(params, options?) | Poll until N matching emails arrive | | deleteEmail(id) | Delete a single email | | deleteInbox(to) | Delete all emails in an inbox |

// List with filters
await client.listEmails({ to: "signup", filter: { subject: "Welcome" } });

// Poll with custom timeout
await client.waitForEmail({ to: "signup" }, { timeout: 15_000 });

// Wait for multiple emails
await client.waitForEmails({ to: "signup" }, { count: 3 });

// Cleanup
await client.deleteEmail(id);
await client.deleteInbox("signup");

Error handling

import {
  MailOvenAuthError,
  MailOvenNotFoundError,
  MailOvenRateLimitError,
  MailOvenNetworkError,
  MailOvenTimeoutError,
} from "@mailoven/client";

try {
  const email = await client.waitForEmail({ to: "signup" });
} catch (error) {
  if (error instanceof MailOvenTimeoutError) {
    /* no email arrived in time */
  }
  if (error instanceof MailOvenAuthError) {
    /* invalid API key */
  }
  if (error instanceof MailOvenNetworkError) {
    /* connection failed */
  }
}

Documentation

Full API reference and framework integration guides for Jest, Vitest, Playwright, Cypress, pytest, and Cucumber at docs.mailoven.com.

License

MIT