Cypress Email Verification Testing with a Real API

Cypress is a popular end-to-end testing framework for web applications. Adding email verification to Cypress tests usually means dealing with Gmail APIs, IMAP connections, or shared test inboxes. AgentMailr simplifies this with a clean REST API.

Create a Cypress Command

Add these commands to cypress/support/commands.js:

const BASE = "https://api.agentmailr.com";
const KEY = Cypress.env("AGENTMAILR_API_KEY");
const hdrs = { "X-API-Key": KEY, "Content-Type": "application/json" };

Cypress.Commands.add("createInbox", () => {
  return cy.request({ method: "POST", url: `${BASE}/v1/inboxes`, headers: hdrs, body: {} })
    .its("body");
});

Cypress.Commands.add("waitForOtp", (inboxId) => {
  return cy.request({
    method: "GET",
    url: `${BASE}/v1/inboxes/${inboxId}/otp?timeout=60`,
    headers: hdrs,
    timeout: 65000
  }).its("body.code");
});

Use in a Test

describe("Email Verification Flow", () => {
  it("completes signup with OTP", () => {
    cy.createInbox().then((inbox) => {
      cy.visit("/signup");
      cy.get('[name="email"]').type(inbox.address);
      cy.get('[name="password"]').type("TestPass123!");
      cy.get('[type="submit"]').click();

      cy.waitForOtp(inbox.id).then((otp) => {
        cy.get('[name="otp"]').type(otp);
        cy.get("button").contains("Verify").click();
        cy.url().should("include", "/dashboard");
      });
    });
  });
});

Add to cypress.env.json

{
  "AGENTMAILR_API_KEY": "ak_your_key_here"
}

Or pass it at runtime: cypress run --env AGENTMAILR_API_KEY=ak_xxx

Why This Works Better

Each test run gets a fresh, private inbox. OTPs never mix between tests. The long-poll endpoint waits for the email to arrive instead of relying on arbitrary timeouts. Tests become deterministic and fast.