Guide · Playwright

Waiting for an OTP in Playwright

A Playwright test that fills a signup form with a mailsocket inbox address, then waits for the OTP using the TypeScript SDK.

Before you start

  • Create an inbox and an API key. Sign up, verify your email, and open the dashboard. Your first inbox is created automatically, and you can create an API key in one click. Or use the 60-second path with no signup.
  • Copy your inbox address. It is <routing_key>@in.inboxpipe.net. The inbox id (inbox_…) is not the routing key, so copy the full address from the dashboard.
  • Point your signup form at that address. Replace https://app.example.com/signup and the selectors below with your real form.

The flow

  1. Submit the signup form with the mailsocket inbox address.
  2. Call GET /api/v1/inboxes/{id}/messages/wait with require=otp. It returns the OTP as soon as it arrives, or 204 after 25 seconds; on 204, call again.
  3. Assert the OTP is present and has the expected shape (for example 4 to 8 digits).

Copy-paste example

Read your API key from the environment; never hardcode it. Set MAILSOCKET_API_KEY, MAILSOCKET_INBOX_ID and MAILSOCKET_INBOX_ADDRESS before running.

Playwright
// otp-signup.spec.ts
//
// Fill a signup form with a mailsocket inbox address, then block on the wait
// endpoint until the OTP arrives, using the TypeScript SDK. See the full
// reference spec (no SDK, raw APIRequestContext calls) at
// examples/playwright/otp-signup.spec.ts in the mailsocket-sdk repo.
//
// Required environment variables (never hardcode a secret here):
//   MAILSOCKET_API_KEY       a Bearer API key minted in the dashboard
//   MAILSOCKET_INBOX_ID      the inbox public id (e.g. "inbox_abc123")
//   MAILSOCKET_INBOX_ADDRESS the full inbox address shown in the dashboard
//                            (e.g. "ab12cd34@in.inboxpipe.net")
//
// npm i mailsocket-sdk, then: npx playwright test

import { test, expect } from "@playwright/test";
import { MailsocketClient } from "mailsocket-sdk";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

test("signup delivers an OTP to the mailsocket inbox", async ({ page }) => {
  const client = new MailsocketClient(requiredEnv("MAILSOCKET_API_KEY"));
  const inboxId = requiredEnv("MAILSOCKET_INBOX_ID");
  const email = requiredEnv("MAILSOCKET_INBOX_ADDRESS");

  // 1. Kick off the signup with a mailsocket inbox address.
  await page.goto("https://app.example.com/signup");
  await page.fill('input[name="email"]', email);
  await page.click('button[type="submit"]');

  // 2. Wait for the OTP. waitForOtp repeats the call on 204 until the code
  //    arrives or its own timeout elapses (default 60s).
  const result = await client.waitForOtp(inboxId);

  // 3. Assert the code arrived.
  expect(result.otp).not.toBeNull();
  expect(result.otp!).toMatch(/^\d{4,8}$/);
});

Prefer the raw REST calls?

A version with no SDK, calling the wait endpoint directly with Playwright's APIRequestContext, is at examples/playwright/otp-signup.spec.ts. All guides are listed in Guides.