InboxTap

https://inboxtap.dev/docs
Admin
InboxTap is a local-only SMTP capture server and test SDK that allows applications to send real...
Tokens:7,896
Snippets:111
Trust Score:3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run Example Tests

Source: https://inboxtap.dev/docs/guides/nodemailer

Commands to install dependencies and execute the test suite for the express-nodemailer example.

```bash
cd examples/express-nodemailer
npm install
npm test
```

--------------------------------

### Run Example Commands

Source: https://inboxtap.dev/docs/guides/better-auth

Commands to install dependencies and execute the test suite.

```bash
cd examples/better-auth-nextjs
npm install
npx playwright install chromium
npm test
```

--------------------------------

### Start programmatic server with ephemeral ports

Source: https://inboxtap.dev/docs/configuration

Use port 0 to request ephemeral ports for the server, then access the assigned ports after start.

```javascript
import { InboxTapServer } from "inboxtap";

const server = await new InboxTapServer({
  apiPort: 0,
  smtpPort: 0,
  maxMessages: 50,
}).start();

console.log(server.apiUrl);
await server.stop();
```

--------------------------------

### Start Services for Cypress

Source: https://inboxtap.dev/docs/guides/cypress

Run the InboxTap server, the application, and the Cypress test runner in your local or CI environment.

```bash
npx inboxtap &
npm run dev &
npx cypress run
```

--------------------------------

### Run multiple InboxTap instances

Source: https://inboxtap.dev/docs/configuration

Example command to launch an instance on custom ports with a specific domain.

```bash
inboxtap --smtp-port 2025 --api-port 9025 --domain mail.local.test
```

--------------------------------

### Start the InboxTap server

Source: https://inboxtap.dev/docs/quick-start

Run the InboxTap server in a separate terminal to begin capturing emails.

```bash
npx inboxtap
```

--------------------------------

### Install InboxTap SDK

Source: https://inboxtap.dev/docs/installation

Add the InboxTap package as a development dependency to your test suite project.

```shell
bun add --dev inboxtap
```

```shell
npm install --save-dev inboxtap
```

--------------------------------

### Start InboxTap and Application Services

Source: https://inboxtap.dev/docs/guides/playwright

Run the InboxTap server and your application concurrently before executing Playwright tests.

```bash
npx inboxtap &
npm run dev &
npx playwright test
```

--------------------------------

### Initialize InboxTap Server and Client in Vitest

Source: https://inboxtap.dev/docs/guides/nodemailer

Start an ephemeral InboxTap server and initialize the client and mailer for isolated test environments.

```javascript
const server = await new InboxTapServer({ apiPort: 0, smtpPort: 0 }).start();
const inboxTap = new InboxTapClient({ baseUrl: server.apiUrl, domain: server.domain });
const mailer = createMailer({ host: server.smtpHost, port: server.smtpPort });
```

--------------------------------

### GitHub Actions workflow integration

Source: https://inboxtap.dev/docs/guides/ci

Example workflow configuration for running tests with InboxTap as a background process.

```yaml
name: e2e

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Start InboxTap
        run: |
          npx inboxtap &
          timeout 10 bash -c 'until curl -fsS http://localhost:8025/health > /dev/null; do sleep 0.1; done'
      - name: Run tests
        run: npm test
        env:
          SMTP_HOST: localhost
          SMTP_PORT: "1025"
```

--------------------------------

### GET /api/emails/latest

Source: https://inboxtap.dev/docs/reference/http-api

Returns the newest matching message.

```APIDOC
## GET /api/emails/latest

### Description
Returns the newest matching message. Returns 404 when no match exists.

### Method
GET

### Endpoint
/api/emails/latest

### Parameters
#### Query Parameters
- **to** (string) - Optional - Match any recipient address
- **subject** (string) - Optional - Case-insensitive subject substring
- **subjectPattern** (string) - Optional - JavaScript regular-expression source
- **subjectFlags** (string) - Optional - Flags for subjectPattern
- **afterId** (string) - Optional - Return only messages received after this stored message

### Response
#### Success Response (200)
- **email** (object) - The newest matching CapturedEmail
```

--------------------------------

### Implement Playwright Verification Test

Source: https://inboxtap.dev/docs/guides/better-auth

Example test case that creates an inbox, performs a sign-up, and extracts the verification link from the email.

```javascript
test("signs up, verifies via the emailed link, and lands signed in", async ({ page }) => {
  const inbox = await inboxTap.createInbox({ alias: "signup" });

  await page.goto("/signup");
  await page.getByLabel("Email").fill(inbox.address);
  await page.getByLabel("Password").fill(password);
  await page.getByRole("button", { name: "Create account" }).click();

  const verificationUrl = await inbox.waitForLink({
    subject: /verify your email/i,
    timeoutMs: 20_000,
  });
  await page.goto(verificationUrl);

  await page.goto("/");
  await expect(page.getByText(`Signed in as ${inbox.address} (verified: true)`)).toBeVisible();
});
```

--------------------------------

### GET /api/emails

Source: https://inboxtap.dev/docs/reference/http-api

Returns matching messages in receive order.

```APIDOC
## GET /api/emails

### Description
Returns matching messages in receive order.

### Method
GET

### Endpoint
/api/emails

### Parameters
#### Query Parameters
- **to** (string) - Optional - Match any recipient address, case-insensitively
- **subject** (string) - Optional - Case-insensitive subject substring
- **subjectPattern** (string) - Optional - JavaScript regular-expression source for the subject
- **subjectFlags** (string) - Optional - Flags used with subjectPattern
- **afterId** (string) - Optional - Return only messages received after this stored message
- **limit** (number) - Optional - Must be from 1–100

### Response
#### Success Response (200)
- **emails** (array) - List of CapturedEmail objects
```

--------------------------------

### GET /api/emails/wait

Source: https://inboxtap.dev/docs/reference/http-api

Long-polls until a matching message is available.

```APIDOC
## GET /api/emails/wait

### Description
Long-polls until a matching message is available. The default wait is 10 seconds and the maximum is 60 seconds.

### Method
GET

### Endpoint
/api/emails/wait

### Parameters
#### Query Parameters
- **to** (string) - Optional - Match any recipient address
- **subject** (string) - Optional - Case-insensitive subject substring
- **subjectPattern** (string) - Optional - JavaScript regular-expression source
- **subjectFlags** (string) - Optional - Flags for subjectPattern
- **afterId** (string) - Optional - Return only messages received after this stored message
- **timeoutMs** (number) - Optional - Must be from 1–60,000

### Response
#### Success Response (200)
- **email** (object) - The matching CapturedEmail
```

--------------------------------

### GET /api/emails/:id

Source: https://inboxtap.dev/docs/reference/http-api

Returns one stored identifier.

```APIDOC
## GET /api/emails/:id

### Description
Returns one stored identifier, or 404 when it is not present.

### Method
GET

### Endpoint
/api/emails/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the email

### Response
#### Success Response (200)
- **email** (object) - The requested CapturedEmail
```

--------------------------------

### Wait for a verification code

Source: https://inboxtap.dev/docs/reference/client-sdk

Use waitForCode to extract a specific pattern from an email. This example searches for a 4-digit code in emails with a matching subject.

```typescript
const code = await inbox.waitForCode({
  pattern: /\b\d{4}\b/,
  subject: /sign in/i,
  timeoutMs: 20_000,
});
```

--------------------------------

### GET /health

Source: https://inboxtap.dev/docs/reference/http-api

Returns the bound SMTP and HTTP addresses plus the recipient domain.

```APIDOC
## GET /health

### Description
Returns the bound SMTP and HTTP addresses plus the recipient domain.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Status of the service
- **api** (object) - API host and port details
- **smtp** (object) - SMTP host and port details
- **domain** (string) - Recipient domain
```

--------------------------------

### Get Latest Email via cURL

Source: https://inboxtap.dev/docs/reference/http-api

Retrieves the newest matching message, returning a 404 status if no match is found.

```bash
curl "http://localhost:8025/api/emails/latest?subject=verify"
```

--------------------------------

### View CLI configuration options

Source: https://inboxtap.dev/docs/configuration

List of available command-line flags for configuring SMTP and API settings.

```bash
--smtp-host <host>          SMTP host
--smtp-port <port>          SMTP port, 0–65535
--api-host <host>           HTTP API host
--api-port <port>           HTTP API port, 0–65535
--domain <domain>           Test recipient domain
--max-messages <count>      Messages retained in memory
--max-message-size <bytes>  Maximum accepted SMTP message size
```

--------------------------------

### Run InboxTap Server

Source: https://inboxtap.dev/docs/installation

Execute the InboxTap server directly without adding it as a project dependency.

```shell
bunx inboxtap
```

```shell
npx inboxtap
```

--------------------------------

### Initialize InboxTapClient

Source: https://inboxtap.dev/docs/reference/client-sdk

Instantiate the client to communicate with the local HTTP API. The baseUrl defaults to http://localhost:8025.

```typescript
import { InboxTapClient } from "inboxtap/client";

const inboxTap = new InboxTapClient({
  baseUrl: "http://localhost:8025",
});
```

--------------------------------

### Configure Playwright WebServer

Source: https://inboxtap.dev/docs/guides/better-auth

Set up Playwright to manage both the InboxTap server and the Next.js application during testing.

```javascript
export default defineConfig({
  testDir: "./tests",
  use: { baseURL: "http://localhost:3000" },
  webServer: [
    {
      command: "npx inboxtap",
      url: "http://localhost:8025/health",
      reuseExistingServer: !process.env.CI,
    },
    {
      command: "npm run db:migrate && npm run dev",
      url: "http://localhost:3000",
      reuseExistingServer: !process.env.CI,
      timeout: 120_000,
    },
  ],
});
```

--------------------------------

### Integrate Better Auth with Email Callbacks

Source: https://inboxtap.dev/docs/guides/better-auth

Configure Better Auth plugins to route verification, magic link, and OTP emails through the custom mailer.

```javascript
export const auth = betterAuth({
  database: new Database("./auth.db"),
  emailAndPassword: { enabled: true, requireEmailVerification: true },
  emailVerification: {
    sendOnSignUp: true,
    autoSignInAfterVerification: true,
    sendVerificationEmail: async ({ user, url }) => {
      await sendMail({ to: user.email, subject: "Verify your email", text: `Open: ${url}` });
    },
  },
  plugins: [
    magicLink({
      sendMagicLink: async ({ email, url }) => {
        await sendMail({ to: email, subject: "Your sign-in link", text: `Sign in: ${url}` });
      },
    }),
    emailOTP({
      sendVerificationOTP: async ({ email, otp }) => {
        await sendMail({ to: email, subject: "Your sign-in code", text: `Your code is ${otp}` });
      },
    }),
  ],
});
```

--------------------------------

### Initialize InboxTap client

Source: https://inboxtap.dev/docs/configuration

Connect the client to a specific API base URL.

```javascript
const inboxTap = new InboxTapClient({ baseUrl: "http://localhost:9025" });
```

--------------------------------

### Manage InboxTap server lifecycle in Vitest

Source: https://inboxtap.dev/docs/guides/test-runners

Use beforeAll and afterAll hooks to manage the InboxTap server lifecycle within a test suite.

```typescript
import { afterAll, beforeAll } from "vitest";
import { InboxTapServer } from "inboxtap";
import { InboxTapClient } from "inboxtap/client";

let server: InboxTapServer;
let inboxTap: InboxTapClient;

beforeAll(async () => {
  server = await new InboxTapServer({ apiPort: 0, smtpPort: 0 }).start();
  inboxTap = new InboxTapClient({
    baseUrl: server.apiUrl,
    domain: server.domain,
  });

  // Configure the application under test with server.smtpHost and server.smtpPort.
});

afterAll(async () => {
  await server.stop();
});
```

--------------------------------

### Configure SMTP Environment Variables

Source: https://inboxtap.dev/docs/installation

Set the application environment variables to point to the local InboxTap SMTP listener.

```text
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_SECURE=false
```

--------------------------------

### Import InboxTap Client

Source: https://inboxtap.dev/docs/installation

Import the client class from the public subpath for use in your test code.

```javascript
import { InboxTapClient } from "inboxtap/client";
```

--------------------------------

### Verify Email Link in Test

Source: https://inboxtap.dev/docs/guides/nodemailer

Use the InboxTap client to create an inbox, trigger an email, and wait for a specific link to appear.

```javascript
it("verifies a new user through the emailed link", async () => {
  const inbox = await inboxTap.createInbox({ alias: "signup" });

  await postJson(`${baseUrl}/signup`, { email: inbox.address });

  const link = await inbox.waitForLink({ subject: /welcome/i, contains: "/verify?token=" });
  const verify = await fetch(link);
  expect(verify.status).toBe(200);
});
```

--------------------------------

### Create an isolated test inbox

Source: https://inboxtap.dev/docs/quick-start

Initialize the client and create a unique inbox alias to prevent cross-test interference.

```javascript
import { InboxTapClient } from "inboxtap/client";

const inboxTap = new InboxTapClient();
const inbox = await inboxTap.createInbox({ alias: "signup" });
```

--------------------------------

### InboxTapClient

Source: https://inboxtap.dev/docs/reference/client-sdk

Initializes the client to communicate with the InboxTap HTTP API.

```APIDOC
## InboxTapClient

### Description
Initializes the client instance to interact with the InboxTap service.

### Constructor
`new InboxTapClient(options)`

### Parameters
- **baseUrl** (string) - Optional - The base URL of the InboxTap service. Defaults to "http://localhost:8025".
- **domain** (string) - Optional - The configured recipient domain to skip the initial health request.
```

--------------------------------

### Create a test inbox

Source: https://inboxtap.dev/docs/reference/client-sdk

Create a unique recipient address for testing. The alias is normalized and appended with a random suffix.

```typescript
const inbox = await inboxTap.createInbox({ alias: "password-reset" });
console.log(inbox.address);
```

--------------------------------

### Verify Account via Email Link

Source: https://inboxtap.dev/docs/guides/playwright

Use the InboxTap client to create a unique inbox, interact with the UI, and wait for a verification link sent to the generated address.

```typescript
import { test, expect } from "@playwright/test";
import { InboxTapClient } from "inboxtap/client";

const inboxTap = new InboxTapClient();

test("verifies a new account", async ({ page }) => {
  const inbox = await inboxTap.createInbox({ alias: "signup" });

  await page.goto("/signup");
  await page.getByLabel("Email").fill(inbox.address);
  await page.getByRole("button", { name: "Create account" }).click();

  const verificationUrl = await inbox.waitForLink({
    subject: /verify your email/i,
    contains: "/verify",
    timeoutMs: 20_000,
  });

  await page.goto(verificationUrl);
  await expect(page.getByText("Email verified")).toBeVisible();
});
```

--------------------------------

### List Emails via cURL

Source: https://inboxtap.dev/docs/reference/http-api

Fetches matching messages in receive order using query parameters for filtering.

```bash
curl "http://localhost:8025/api/emails?to=signup%40local.test&limit=10"
```

--------------------------------

### Await verification links

Source: https://inboxtap.dev/docs/quick-start

Wait for a specific email to arrive and extract the verification URL to continue the browser flow.

```javascript
const verificationUrl = await inbox.waitForLink({
  subject: /verify your email/i,
  contains: "/verify",
});

await page.goto(verificationUrl);
```

--------------------------------

### Write Email Verification Test

Source: https://inboxtap.dev/docs/guides/cypress

Use registered tasks to create an inbox, trigger an email, and wait for verification links or codes within a test.

```javascript
describe("sign up", () => {
  it("verifies a new account", () => {
    cy.task<string>("inboxtap:createInbox", "signup").then((address) => {
      cy.visit("/signup");
      cy.get("input[name=email]").type(address);
      cy.contains("button", "Create account").click();

      cy.task<string>(
        "inboxtap:waitForLink",
        { to: address, subject: "verify your email", contains: "/verify", timeoutMs: 20_000 },
        { timeout: 30_000 },
      ).then((url) => {
        cy.visit(url);
        cy.contains("Email verified").should("be.visible");
      });
    });
  });
});
```

--------------------------------

### createInbox

Source: https://inboxtap.dev/docs/reference/client-sdk

Creates a new unique test inbox address.

```APIDOC
## createInbox

### Description
Creates a new unique recipient address for testing purposes. The alias is normalized and appended with a random 12-character suffix.

### Parameters
- **alias** (string) - Optional - The base name for the inbox. Defaults to "test".

### Returns
- **TestInbox** - An object representing the created inbox.
```

--------------------------------

### TestInbox Methods

Source: https://inboxtap.dev/docs/reference/client-sdk

Methods available on a TestInbox instance to interact with captured messages.

```APIDOC
## TestInbox Methods

### messages()
Returns a list of `CapturedEmail[]` for this address.

### clear()
Deletes all messages for this address. Returns the number of deleted messages.

### waitForMessage(options)
Await the full matching message. Options include `subject`, `timeoutMs`, and `afterId`.

### waitForLink(options)
Await the first link in a message, optionally filtering by text.

### waitForCode(options)
Await a code matching a pattern. Defaults to six digits.

### waitForMatch(options)
Await a required string or regular-expression match.
```

--------------------------------

### Configure Nodemailer Transport for InboxTap

Source: https://inboxtap.dev/docs/guides/nodemailer

Set up the Nodemailer transport to connect to InboxTap by disabling authentication and TLS.

```javascript
import { createTransport } from "nodemailer";

const transport = createTransport({
  host: process.env.SMTP_HOST ?? "localhost",
  port: Number(process.env.SMTP_PORT ?? 1025),
  secure: false,
  ignoreTLS: true,
});
```

--------------------------------

### Register InboxTap Tasks in Cypress

Source: https://inboxtap.dev/docs/guides/cypress

Define custom tasks in the Cypress configuration to bridge the Node SDK with the browser-based test environment.

```typescript
// cypress.config.ts
import { defineConfig } from "cypress";
import { InboxTapClient, TestInbox } from "inboxtap/client";

const inboxTap = new InboxTapClient();

interface WaitArgs {
  to: string;
  subject?: string;
  contains?: string;
  pattern?: string;
  timeoutMs?: number;
}

export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      on("task", {
        "inboxtap:createInbox": async (alias: string) =>
          (await inboxTap.createInbox({ alias })).address,
        "inboxtap:waitForLink": ({ to, ...options }: WaitArgs) =>
          new TestInbox(inboxTap, to).waitForLink(options),
        "inboxtap:waitForCode": ({ to, ...options }: WaitArgs) =>
          new TestInbox(inboxTap, to).waitForCode(options),
      });
    },
  },
});
```

--------------------------------

### Extract codes and match patterns

Source: https://inboxtap.dev/docs/quick-start

Retrieve specific security codes or regex-matched values from captured emails, then clear the inbox.

```javascript
const code = await inbox.waitForCode({ subject: /security code/i });
const key = await inbox.waitForMatch({ pattern: /api_key=([A-Za-z0-9_-]+)/ });

await inbox.clear();
```

--------------------------------

### Verify API Health

Source: https://inboxtap.dev/docs/guides/troubleshooting

Use curl to confirm the InboxTap server is reachable on the default API port.

```bash
curl http://localhost:8025/health
```

--------------------------------

### Wait for health check

Source: https://inboxtap.dev/docs/guides/ci

Poll the /health endpoint to ensure the SMTP and HTTP listeners are bound before proceeding with tests.

```bash
npx inboxtap &
timeout 10 bash -c 'until curl -fsS http://localhost:8025/health > /dev/null; do sleep 0.1; done'
```

--------------------------------

### Trigger email delivery

Source: https://inboxtap.dev/docs/quick-start

Use the generated inbox address within your application's sign-up flow to trigger an email.

```javascript
await page.getByLabel("Email").fill(inbox.address);
await page.getByRole("button", { name: "Create account" }).click();
```

--------------------------------

### Direct HTTP Access for Email Checks

Source: https://inboxtap.dev/docs/guides/cypress

Perform simple email checks directly from the Cypress Node-side proxy using cy.request without task registration.

```javascript
cy.request(
  "http://localhost:8025/api/emails/wait?to=signup-1@local.test&timeoutMs=20000",
)
  .its("body.email.links")
  .should("not.be.empty");
```

--------------------------------

### List Captured Emails

Source: https://inboxtap.dev/docs/guides/troubleshooting

Retrieve an unfiltered list of all emails currently stored in the InboxTap server.

```bash
curl http://localhost:8025/api/emails
```

--------------------------------

### CapturedEmail interface definition

Source: https://inboxtap.dev/docs/reference/client-sdk

The structure of an email object returned by the SDK, containing metadata, headers, and extracted content.

```typescript
interface CapturedEmail {
  id: string;
  receivedAt: string;
  envelope: { from: string | null; to: string[] };
  from: string;
  to: string[];
  subject: string;
  headers: Record<string, string>;
  text: string;
  html: string;
  links: string[];
  codes: string[];
  raw: string;
}
```

--------------------------------

### Retrieve Health Status

Source: https://inboxtap.dev/docs/reference/http-api

Returns the bound SMTP and HTTP addresses along with the recipient domain.

```json
{
  "ok": true,
  "api": { "host": "localhost", "port": 8025 },
  "smtp": { "host": "localhost", "port": 1025 },
  "domain": "local.test"
}
```

--------------------------------

### Wait for Email via cURL

Source: https://inboxtap.dev/docs/reference/http-api

Performs a long-poll request until a matching message is available or the timeout is reached.

```bash
curl "http://localhost:8025/api/emails/wait?to=signup%40local.test&timeoutMs=30000"
```

--------------------------------

### DELETE /api/emails

Source: https://inboxtap.dev/docs/reference/http-api

Deletes every stored message.

```APIDOC
## DELETE /api/emails

### Description
Deletes every stored message. Add a to query to delete only messages addressed to one recipient.

### Method
DELETE

### Endpoint
/api/emails

### Parameters
#### Query Parameters
- **to** (string) - Optional - Delete only messages addressed to this recipient

### Response
#### Success Response (200)
- **deleted** (number) - Number of messages deleted
```

--------------------------------

### Clear Emails via cURL

Source: https://inboxtap.dev/docs/reference/http-api

Deletes stored messages, optionally filtered by recipient address.

```bash
curl -X DELETE "http://localhost:8025/api/emails?to=signup%40local.test"
```
Tokens:
Raw