Email Verification Testing in Cypress

Two custom commands

The first creates an inbox. The second waits for a message to land in it. Everything else is your normal test.

// cypress/support/commands.js
const API = 'https://emptyinbox.me/api';

const auth = () => ({
  Authorization: `Bearer ${Cypress.env('EMPTYINBOX_API_KEY')}`,
});

Cypress.Commands.add('createInbox', () => {
  return cy
    .request({ method: 'POST', url: `${API}/inbox`, headers: auth() })
    .then((res) => res.body.trim()); // plain text, not JSON
});

// Recursive retry: each attempt re-queries, so a fast delivery returns fast
// and a slow one still gets the full budget.
Cypress.Commands.add('waitForEmail', (address, attempts = 15) => {
  const poll = (left) =>
    cy.request({ url: `${API}/messages`, headers: auth() }).then((res) => {
      const hit = res.body.find((m) => m.inbox === address);
      if (hit) return hit;
      if (left === 0) throw new Error(`no email for ${address} in time`);
      return cy.wait(2000).then(() => poll(left - 1));
    });

  return poll(attempts);
});

Using them in a signup test

describe('signup', () => {
  it('verifies a new account with a real email', () => {
    cy.createInbox().then((address) => {
      cy.visit('/signup');
      cy.get('[name=email]').type(address);
      cy.get('[name=password]').type('correct horse battery staple');
      cy.contains('button', 'Create account').click();

      cy.waitForEmail(address).then((message) => {
        expect(message.subject).to.contain('Verify');

        const code = message.text_body.match(/\b\d{6}\b/)[0];
        cy.get('[name=code]').type(code);
        cy.contains('button', 'Confirm').click();
      });

      cy.contains('Welcome').should('be.visible');
    });
  });
});

If the mail carries a link instead of a code, extract the URL from text_body and pass it to cy.visit. Use html_body when the link only exists in the HTML part of the message.

Why not cy.wait with a fixed delay

A fixed wait is a guess about the slowest delivery you will ever see. Set it low and the suite is flaky; set it high and every run pays the worst case even when the mail arrived in two seconds. The recursive retry above returns as soon as the message exists and only spends the full budget when something is genuinely wrong.

Configuration

Register once and put the key in the environment. Cypress picks up any variable prefixed with CYPRESS_, so CYPRESS_EMPTYINBOX_API_KEY is readable as Cypress.env('EMPTYINBOX_API_KEY') with no config file change.

curl -X POST https://emptyinbox.me/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "ci-cypress"}'

# {"api_key": "ei...", "inbox_quota": 5}

One credit is spent per inbox, and messages delete themselves after 7 days, so there is no teardown step and no storage to manage.

Frequently asked questions