PNTR
All guides

Testing guide

Test signup emails with Cypress and a PNTR inbox

A PNTR catch-all inbox accepts every address on an enabled subdomain. Cypress can give each test a unique recipient and ask PNTR to wait for that exact email, avoiding a shared mailbox UI and cross-test collisions.

Explore PNTR's disposable email for developers
Create the Cypress inbox
cypress.config.ts task/TypeScript
import { defineConfig } from "cypress";import { PntrTestKit } from "@pntr/testkit";export default defineConfig({  e2e: {    setupNodeEvents(on) {      const pntr = new PntrTestKit({ token: process.env.PNTR_TOKEN! });      on("task", {        waitForEmail(input: { hostname: string; recipient: string; since: string }) {          return pntr.waitForEmail(input.hostname, {            recipient: input.recipient,            subject: "Verification code",            since: input.since,            timeoutSeconds: 20,          });        },      });    },  },});

Setup

  1. 1

    Create an API-backed test inbox

    Create a PNTR hostname with email enabled, generate an API token under MCP integration, and store PNTR_TOKEN and the full hostname as PNTR_EMAIL_HOSTNAME in CI secrets.

  2. 2

    Install TestKit in the Node process

    Install @pntr/testkit and initialize it in Cypress's setupNodeEvents callback. Keeping PNTR requests in a cy.task avoids bundling the API token into browser-side test code.

  3. 3

    Give every test a unique recipient

    Build the address from the test purpose plus a random value or run ID, for example [email protected]. The catch-all inbox receives it without pre-creating the address.

  4. 4

    Submit the real browser flow

    Use Cypress to enter the generated address and submit your application's signup, reset-password, or verification form exactly as a user would.

  5. 5

    Wait through a Node task

    Call the task with the hostname, exact recipient, start time, and bounded timeout. PNTR returns the matching message or a timeout instead of making the test scan an inbox.

Before you ship

Cypress automatically logs commands, so keep the PNTR token in Cypress secrets and avoid printing request headers. Filter by recipient and a test start time when old messages might use the same address.

Primary documentation