One of the trickiest parts of end-to-end testing has always been email verification.

Whether it’s account sign-ups, password resets, or email-based authentication flows, we often find ourselves writing hacky solutions or hitting a dead end altogether.

That’s where Mailosaur comes in! An awesome tool that helps test emails (and even SMS) in an automated way. What’s even better? There’s an official Cypress plugin that makes email testing a breeze for us, the Cypress fans.

In this article, let’s dive into how you can seamlessly integrate Cypress and Mailosaur to validate email flows like a pro ❤

The Setup

Before we jump into code, let’s make sure the basics are covered.

1. Install the plugin:
   
   Run this command to install the package in your Cypress project
   
   npm install — save-dev cypress-mailosaur

2. Configure Cypress support: In your cypress/support/e2e.ts or e2e.js, add:
   
   import ‘cypress-mailosaur’;This adds custom commands to your Cypress chain like cy.mailosaurGetMessage()

3. Set your Mailosaur API key:
   
   You can either set the API key in the Cypress environment configuration (cypress.config.ts) like this:

Or, if you’re keeping secrets out of code (highly recommended), pass them via environment variables when running Cypress.

Real-World Test: Email Verification Flow

Let’s say you have a sign-up form that sends a verification email with a link. Here’s how you can test it with Mailosaur:

Tip! You can validate plain text content or even attachments if your use case demands it. Mailosaur’s API gives you access to email bodies (email.text.body, email.html.body) and much more. ❤

Email Deliverability Validation

Mailosaur has some more Magic! The mailosaurGetSpamAnalysis() command runs a SpamAssassin test against an email, which scores the email based on some rules. The lower the score the better and, in most cases, a score higher then 5.0 will result in an email being seen as spam. The command will also return a list of rules that were triggered by the email. These rules are the same as those used by SpamAssassin itself and are based on a set of criteria that are common in spam emails. You can read more here. Here’s how you can test it:

Retry Logic Built In

No need to manually add cy.wait() or retry loops. cy.mailosaurGetMessage() automatically waits and polls for the email, up to the timeout you define (default is 10 seconds). You can customize this:

This is incredibly useful when your email service takes a few extra seconds to deliver.

Verifying OTPs and Tokens

For apps sending OTPs or verification codes, you can extract values directly:

Easy peasy 🍋! ❤

Bonus: Testing Edge Cases

Want to test that an email is not sent? You can use cy.mailosaurGetMessage() with a very short timeout and assert a failure:

Keep in mind this will cause the test to fail if the email is received!

Cleanup

Emails in Mailosaur are ephemeral, but if you want to delete them manually after each test:

Useful when your test suite runs in parallel or reuses the same inbox across tests.

Final Thoughts

I’ve used this setup in multiple real-world projects — especially when testing sign-up flows, password resets, and account recovery. It saves time, avoids flaky manual inbox checkers, and integrates cleanly with Cypress.

If you’re building quality into your apps with Cypress, don’t skip email verification. It’s an important part of the user journey — and now, testing it is super simple thanks to Mailosaur.

Happy Testing!