ShazaMail
Cypress Email Verification Testing
Keep API secrets in the Node task process, create an isolated test inbox, and wait for the verification message without arbitrary delays.
Product documentation last reviewed: 2026-09-28
Keep the mail API key out of browser-side Cypress code
Cypress commands executed in the browser context should not expose a long-lived developer API key. A safer pattern is to create cy.task handlers in cypress.config that run in the Node process, read SHAZAMAIL_API_KEY from the environment, and call the ShazaMail REST API there. The test receives only the temporary inbox details or message result it needs.
Create one inbox per test or logical run
Use POST /api/v1/test-inboxes at the beginning of a signup or password-reset scenario and store the returned inbox ID and email address in the test state. The create endpoint accepts run_id, tags, purpose, and a bounded TTL, which makes it easier to identify resources created by parallel Cypress jobs and clean them up after a run.
Wait in Node and return the matched email to the test
A second task can call POST /api/v1/test-inboxes/:id/wait with a matcher such as subject_contains or has_verification_code. This keeps Cypress command chains readable and avoids repeated browser-origin requests to an external API. The wait request is bounded, so a missing email fails explicitly instead of leaving the test runner stuck.
Primary references
Common questions
Why use cy.task instead of calling the API directly from the page?
cy.task keeps the API credential in Cypress Node configuration rather than exposing it to application browser code or client-side network inspection.
Can Cypress wait for a specific email subject?
Yes. The wait endpoint supports subject_contains and subject_equals matchers, along with sender, recipient, verification-code, category, and time-based matching.
Should I reuse one inbox across the entire test suite?
Usually no. Isolated inboxes reduce cross-test contamination and make parallel runs easier to debug.