Guide · Cypress

Waiting for an OTP in Cypress

A Cypress test that drives a real signup form with a mailsocket address and awaits the OTP over Cypress's built-in HTTP client. The example calls the REST API directly; there is no Cypress plugin to install.

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.

Cypress
// cypress/e2e/signup.cy.js
// Set MAILSOCKET_API_KEY, MAILSOCKET_INBOX_ID and MAILSOCKET_INBOX_ADDRESS
// in your Cypress environment (cypress.env.json or process.env).
const API_BASE = Cypress.env("MAILSOCKET_API_BASE") || "https://dash.mailsocket.app";

it("signup delivers an OTP to the mailsocket inbox", () => {
  const apiKey = Cypress.env("MAILSOCKET_API_KEY");
  const inboxId = Cypress.env("MAILSOCKET_INBOX_ID");
  const address = Cypress.env("MAILSOCKET_INBOX_ADDRESS");

  // 1. Trigger the signup with a mailsocket inbox address.
  cy.visit("https://app.example.com/signup");
  cy.get('input[name="email"]').type(address);
  cy.get('button[type="submit"]').click();

  // 2. Block on the wait endpoint (up to 25s per call). A 204 means no code
  //    yet; for slower senders, repeat the request until it returns 200.
  cy.request({
    method: "GET",
    url: `${API_BASE}/api/v1/inboxes/${inboxId}/messages/wait`,
    qs: { require: "otp", timeout: 25 },
    headers: { Authorization: `Bearer ${apiKey}` },
  }).then((resp) => {
    // 3. Assert the code arrived.
    expect(resp.status).to.eq(200);
    expect(resp.body.data.otp).to.match(/^\d{4,8}$/);
  });
});

Want the Playwright version too?

A ready-to-copy Playwright spec is at examples/playwright/otp-signup.spec.ts. All guides are listed in Guides.