mailpit-api

A zero-dependency TypeScript client for interacting with Mailpit's REST API. Ideal for automating your email testing. Works in Node.js, browser, and any modern JS runtime.

For real-time WebSocket events, see mailpit-ws.

Installation

npm install mailpit-api
Copy

Documentation

Detailed documentation covering all available methods and type definitions.

Upgrading from v1? See the upgrade guide.

Usage

Prerequisites: These examples require a Mailpit installation. See the Mailpit installation guide.

Example

import { MailpitClient } from "mailpit-api";

// Initialize the API client
const mailpit = new MailpitClient("http://localhost:8025");

// Send a message
await mailpit.sendMessage({
  From: { Email: "user@example.test" },
  To: [{ Email: "rec@example.test" }],
  Subject: "Test Email",
});

// Get a summary of all messages
const messages = await mailpit.listMessages();

// Delete all messages
await mailpit.deleteMessages();
Copy

Using with Playwright Tests

Use mailpit-api with Playwright as a custom test fixture to handle email testing.

// fixtures.ts
import { test as base } from "@playwright/test";
import { MailpitClient } from "mailpit-api";

type MyFixtures = {
  mailpit: MailpitClient;
};

export const test = base.extend<MyFixtures>({
  mailpit: async ({}, use) => {
    const mailpit = new MailpitClient("http://localhost:8025");
    await mailpit.deleteMessages();
    await use(mailpit);
  },
});

export { expect } from "@playwright/test";
Copy

// tests/register.spec.ts
import { test, expect } from "../fixtures";

test("should receive welcome email after registration", async ({
  page,
  mailpit,
}) => {
  await page.goto("/register");
  await page.getByTestId("email").fill("test@example.test");
  await page.getByTestId("password").fill("password123");
  await page.getByTestId("submit").click();

  await expect(page.getByTestId("success-message")).toBeVisible();

  // Wait for the welcome email (up to 5 seconds by default)
  const message = await mailpit.waitForMessage({
    query: "subject:Welcome to Our App",
  });

  expect(message.To[0].Address).toBe("test@example.test");
  expect(message.From.Address).toBe("no-reply@your-app.test");
  expect(message.Subject).toBe("Welcome to Our App");
});
Copy

Waiting for Emails

Using in the Browser

mailpit-api is also fully compatible with browser environments. See the Mailpit CORS configuration documentation to allow requests from your app's origin.