Temp Mail API for Cypress

Where Cypress email tests usually fail

Email verification touches more systems than the browser: app code, background jobs, SMTP routing, template rendering, link generation, and mailbox delivery. A fake inbox can miss those failures, while a shared real inbox creates test collisions.

The safer pattern is one temporary inbox per Cypress spec or per test. TempMailGrab keeps the mailbox private to your API key and returns structured fields for OTP codes and verification links.

Cypress command pattern

// cypress/support/commands.js
Cypress.Commands.add("createTempInbox", () => {
  return cy.request({
    method: "POST",
    url: "https://tempmailgrab.com/api/v1/inbox",
    headers: { Authorization: "Bearer " + Cypress.env("TMG_API_KEY") },
  }).then((res) => res.body);
});

Cypress.Commands.add("waitForTempMailOtp", (inboxId) => {
  const poll = (attempt = 0) => {
    expect(attempt, "OTP polling attempts").to.be.lessThan(30);
    return cy.request({
      url: "https://tempmailgrab.com/api/v1/inbox/" + inboxId + "/messages",
      headers: { Authorization: "Bearer " + Cypress.env("TMG_API_KEY") },
    }).then((res) => {
      const otp = res.body.messages?.find((m) => m.extracted_otp)?.extracted_otp;
      if (otp) return otp;
      return cy.wait(2000).then(() => poll(attempt + 1));
    });
  };
  return poll();
});

Example spec

it("verifies a signup code", () => {
  cy.createTempInbox().then((inbox) => {
    cy.visit("/signup");
    cy.findByLabelText("Email").type(inbox.address);
    cy.findByRole("button", { name: "Create account" }).click();

    cy.waitForTempMailOtp(inbox.id).then((otp) => {
      cy.findByLabelText("Verification code").type(otp);
      cy.findByRole("button", { name: "Verify" }).click();
      cy.contains("Account verified").should("be.visible");
    });
  });
});

CI recommendations

• Store TMG_API_KEY as a CI secret, never in the repo.
• Create a unique inbox for each parallel Cypress worker.
• Use a 30-60 second polling window for real email systems.
• Delete inboxes in cleanup when a spec creates unusually large attachments.

Useful companion links

• Full API documentation
• OpenAPI specification
• Email testing API overview
• Long-form Cypress tutorial
• TempMailGrab package on npm

Last verified: August 2026. Cypress and endpoint examples may change; check the API docs before copying into production CI.