Zero to Hero: Email Automation with Cypress & Mailosaur

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. Install the plugin: Run this command to install the package in your Cypress project npm install — save-dev cypress-mailosaur 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() 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

Mar 29, 2025 - 14:44

Zero to Hero: Email Automation with Cypress & Mailosaur

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.

Install the plugin:

Run this command to install the package in your Cypress project

npm install — save-dev cypress-mailosaur
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()
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: