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 poll the PNTR API, avoiding a shared mailbox UI and reducing cross-test collisions.

Explore PNTR's disposable email for developers
Create the Cypress inbox

Cypress polling helper

function waitForEmail(recipient, attempts = 20) {
  return cy.request({
    url: `https://api.pntr.dev/api/subdomains/${Cypress.env("PNTR_SUBDOMAIN_ID")}/emails`,
    headers: { Authorization: `Bearer ${Cypress.env("PNTR_TOKEN")}` },
  }).then(({ body }) => {
    const email = body.find((item) => item.recipient === recipient);
    if (email) return email;
    if (attempts === 0) throw new Error(`No email for ${recipient}`);
    return cy.wait(1000).then(() => waitForEmail(recipient, attempts - 1));
  });
}

Setup

  1. 1

    Create an API-backed test inbox

    Create a PNTR subdomain with email enabled, generate an API token in dashboard settings, and store the token and subdomain ID in Cypress environment secrets.

  2. 2

    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.

  3. 3

    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.

  4. 4

    Poll with cy.request

    Call the PNTR email-list endpoint recursively until a message with the exact recipient appears. Bound the number of attempts so a missing email fails with a useful error instead of hanging the suite.

  5. 5

    Fetch the message you matched

    Use the returned email ID to request the full body, then assert the subject or extract the code or link. Do not assume the newest message belongs to the current test.

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