Related: how to read OTP codes and magic links from email in Selenium, Playwright, Cypress and Python tests.

Login failures lock users out of your app. From forgotten passwords to broken authentication flows, a bad login experience is a nightmare for both users and support teams.

While a simple login screen seems easy to test, complexity grows fast when you introduce two-factor authentication (2FA), magic links, SSO, or team-based accounts. Can your tests keep up?

In this guide, we’ll show you how to automate 2FA email verification using Selenium and Mailsac. You’ll send a real email, extract the one-time password (OTP) programmatically, and validate authentication—ensuring your app’s login works flawlessly.

New to Selenium email testing? Start with our Selenium email testing guide. It covers headless Chrome setup, a unique test address for every run, waiting only for mail that arrives after the test acts, and running the suite in CI. This post goes deeper on the 2FA login flow.

Selenium & Mailsac Prep

You’re already familiar with Selenium—after all, it’s a core tool for browser automation. (Fun fact: we’re a proud Selenium sponsor!)

Have you worked directly with WebDriver? WebDriver is what allows Selenium to control a browser just like a real user—clicking buttons, filling out forms, and navigating pages. For our automated 2FA test, we’ll use WebDriver to interact with the login flow, retrieve the OTP from an email, and complete authentication.

Step 1: Install Selenium for Javascript

Let’s start by installing Selenium via npm:

npm init
npm install selenium-webdriver chromedriver dotenv

You’ll also need to install chromedriver by manually downloading it from Google or from your package manager. For example for macOS:

brew install chromedriver

Step 2: Sign Up At Mailsac for Email Testing

Mailsac provides disposable email addresses and an API to fetch incoming emails. We’ll use it to verify that a 2FA email is received and contains the correct code.

Why Use Mailsac?

• Eliminate reliance on real email accounts → No need to clutter your inbox with test emails or use shared email accounts.
• Prevents rate-limiting & spam issues → Disposable email addresses is the core feature and is extremely quick.
• Automates email verification → You can fetch emails instantly via API or receive them over web sockets.

Setting Up Mailsac API Access

1. Create a Free Mailsac Account:

• Go to mailsac.com and sign up.
• Navigate to your Dashboard then Credentials and API Keys to generate an API key.

2. Install Mailsac’s API Client

Install the official mailsac API client:

npm install @mailsac/api dotenv

3. Store Your API Key Securely

Never hardcode your API key. Use environment variables by creating a .env file:

MAILSAC_API_KEY=your-api-key-here

Now that we’ve installed Selenium and set up our Mailsac account, we can start writing our test script to automatically log in, retrieve the 2FA code, and verify it in our application.

Our Sample App

Let’s introduce our sample application that we’re going to test, called “Active Forums”.
It’s an early version of a forum application. It’s got the basic logic of Sign In, the landing page that shows you all your posts, and the Admin Panel

Pages We’re Interested In Testing

Sign In

One Time Password

Landing Page

Automating The Entire Login Process

Let’s automate the process of logging in, retrieving the 2FA code, and verifying it.

Step 1: Automate the Login Process

Our first task is to navigate to the login page, enter the username and password, and submit the form.

1.1 Initialize Selenium WebDriver

const { Builder, By, until } = require('selenium-webdriver');
require('dotenv').config();
const { Mailsac } = require('@mailsac/api');

async function login(emailAddress,accountPassword) {
    let driver = await new Builder().forBrowser('chrome').build();
    try {
        await driver.get("http://localhost:3000/users/sign_in");
        await driver.findElement(By.id("email")).sendKeys(emailAddress);
        await driver.findElement(By.id("password")).sendKeys(accountPassword);
        await driver.findElement(By.id("sign-in")).click();

    } catch (error) {
        console.error("Login test failed:", error);
    }
    return driver;
}

Here we:

• Open the login page.
• Enter the incorrect username and password into the form fields.
• Click the login button.
• Enter the correct login details
• Return the driver back for the 2FA check.

Step 2: Retrieve the 2FA Code via Mailsac API

Once the user is on the 2FA screen, we need to fetch the one-time code from the email inbox.

Load the API in the script:

require('dotenv').config();
const { Mailsac } = require('@mailsac/api');

Now, we write a function to check the inbox and extract the 6-digit code from the email.

async function get2FACode(emailAddress) {
    try {
        console.log(`Checking inbox for: ${emailAddress}`);

        // Fetch the latest messages from the inbox
        const mailsac = new Mailsac({ headers: { "Mailsac-Key": process.env.MAILSAC_API_KEY } });
        const results = await mailsac.messages.listMessages(emailAddress);
        const messages = results.data;

        if (!messages.length) {
            console.log("No 2FA email received yet.");
            return null;
        }

        // Get the latest message ID
        const latestMessageId = messages[0]._id;

        // Fetch email body
        // const emailBody = await mailsac.messages.getMessage(latestMessageId);
        const emailBody = await mailsac.messages.getBodyPlainText(emailAddress,latestMessageId,{ download : true });
        // Extract 6-digit 2FA code using regex
        const match = emailBody.data.match(/\b\d{6}\b/);
        if (match) {
            console.log(`2FA Code found: ${match[0]}`);
            return match[0];
        } else {
            console.log("No 2FA code found in email.");
            return null;
        }
    } catch (error) {
        console.error("Error retrieving 2FA email:", error);
    }
}

What This Does:

• Checks the Mailsac inbox for a new email.
• Extracts the latest email’s content.
• Uses a regex pattern to find the 6-digit 2FA code inside the email body.

Step 3: Input the 2FA Code in the Login Form

Now that we have the 2FA code, we return to Selenium to enter it into the form.

async function enter2FACode(driver, emailAddress) {
    let attempts = 0;
    let otpCode = null;

    // Polling for 2FA code with a maximum of 5 attempts
    while (!otpCode && attempts < 5) {
        otpCode = await get2FACode(emailAddress);
        if (!otpCode) {
            console.log("Waiting for 2FA code...");
            await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds before retrying
            attempts++;
        }
    }

    if (!otpCode) {
        console.error("Failed to retrieve 2FA code after multiple attempts.");
        return;
    }

    try {
        // Enter the 2FA code into the form
        await driver.findElement(By.id("otp_code")).sendKeys(otpCode);

        // Submit the form
        await driver.findElement(By.name("commit")).click();
        console.log("2FA code submitted, verifying login...");

        // Wait for successful login redirect
        await driver.wait(until.urlContains("/"), 10000);
        console.log("Login successful!");
    } catch (error) {
        console.error("2FA verification failed:", error);
    }
}

What This Does:

• Retries up to 5 times to fetch the 2FA code from the email inbox.
• If no code is found, waits 5 seconds before trying again.
• Once the code is found, inputs it into the form and submits it.
• Waits for the dashboard page to confirm successful login.

Step 4: Run the Full Automated Test

Now, we combine everything into a single test flow.

(async function testLogin2FA() {
    const testEmail = "[email protected]";
    const testCreds = "password123";

    // Step 1: Log in
    const driver = await login(testEmail,testCreds);

    // Step 2: Retrieve and enter 2FA code
    if (driver) {
        await enter2FACode(driver, testEmail);
        await driver.quit();
    }
})();

Full main.js File

Here’s what our full file now looks like:

const { Builder, By, until } = require('selenium-webdriver');

require('dotenv').config();
const { Mailsac } = require('@mailsac/api');

async function login(emailAddress,accountPassword) {
    let driver = await new Builder().forBrowser('chrome').build();

    try {
        await driver.get("http://localhost:3000/users/sign_in");
        await driver.findElement(By.id("email")).sendKeys(emailAddress);
        await driver.findElement(By.id("password")).sendKeys(accountPassword);
        await driver.findElement(By.id("sign-in")).click();

    } catch (error) {
        console.error("Login test failed:", error);
    }
    return driver;
}

async function get2FACode(emailAddress) {
    try {
        console.log(`Checking inbox for: ${emailAddress}`);

        // Fetch the latest messages from the inbox
        const mailsac = new Mailsac({ headers: { "Mailsac-Key": process.env.MAILSAC_API_KEY } });
        const results = await mailsac.messages.listMessages(emailAddress);
        const messages = results.data;

        if (!messages.length) {
            console.log("No 2FA email received yet.");
            return null;
        }

        // Get the latest message ID
        const latestMessageId = messages[0]._id;

        // Fetch email body
        // const emailBody = await mailsac.messages.getMessage(latestMessageId);
        const emailBody = await mailsac.messages.getBodyPlainText(emailAddress,latestMessageId,{ download : true });
        // Extract 6-digit 2FA code using regex
        const match = emailBody.data.match(/\b\d{6}\b/);
        if (match) {
            console.log(`2FA Code found: ${match[0]}`);
            return match[0];
        } else {
            console.log("No 2FA code found in email.");
            return null;
        }
    } catch (error) {
        console.error("Error retrieving 2FA email:", error);
    }
}

async function enter2FACode(driver, emailAddress) {
    let attempts = 0;
    let otpCode = null;

    // Polling for 2FA code with a maximum of 5 attempts
    while (!otpCode && attempts < 5) {
        otpCode = await get2FACode(emailAddress);
        if (!otpCode) {
            console.log("Waiting for 2FA code...");
            await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds before retrying
            attempts++;
        }
    }

    if (!otpCode) {
        console.error("Failed to retrieve 2FA code after multiple attempts.");
        return;
    }

    try {
        // Enter the 2FA code into the form
        await driver.findElement(By.id("otp_code")).sendKeys(otpCode);

        // Submit the form
        await driver.findElement(By.name("commit")).click();
        console.log("2FA code submitted, verifying login...");

        // Wait for successful login redirect
        await driver.wait(until.urlContains("/"), 10000);
        console.log("Login successful!");
    } catch (error) {
        console.error("2FA verification failed:", error);
    }
}

// Main Test Logic
(async function testLogin2FA() {
    const testEmail = "[email protected]";
    const testCreds = "password123";

    // Step 1: Log in
    const driver = await login(testEmail,testCreds);

    // Step 2: Retrieve and enter 2FA code
    if (driver) {
        await enter2FACode(driver, testEmail);
        await driver.quit();
    }
})();

Now try running the whole login test:

node main.js

And just like that we now have an automated way to test outbound emails, logins, one time passwords and correct landing page location!

Automate Your 2FA Testing with Confidence

Login authentication is a critical part of any web application, and failing to test it properly can lead to frustrated users and costly support issues. By combining Selenium for browser automation and Mailsac for email-based 2FA verification, we’ve built a fully automated test that ensures your app’s login process works smoothly.

With this setup, your testing team can:

• Programmatically retrieve real one-time passwords (OTPs) from email
• Automate the entire login flow, including 2FA verification
• Reduce reliance on manual testing and catch authentication issues early

This approach not only saves time but also improves the reliability of your authentication system. You can now integrate this script into your CI/CD pipeline to ensure every update maintains seamless login functionality.

Visit our forums if you have any questions. Now it’s your turn—try running the script, tweak it for your specific use case, and start automating your login tests today!

Developing and testing an application is difficult enough without the stress of GDPR, CAN-SPAM, accidental information leak, etc. But it doesn’t have to be.

In this article I’ll walk you through how our email platform could’ve helped prevent Running Warehouse from exposing thousands of their customer’s emails.

Background on the Running Warehouse Incident

Now, this isn’t meant to poke fun at a company’s mistake but really to highlight just how easy these mistakes are to miss. Last month, I received two emails from “Running Warehouse” about an update to their terms of service. Nothing really unusual at first glance… Until you notice that about 1000 other customer’s email addresses had been sent along in the CC field. And to add even more insult to injury, they did this TWICE. So now I have a list of about 2000 of Running Warehouse’s customers that I’m sure the customers themselves are not happy about.

Really not a good look for a company who could be facing a class action lawsuit for a previous data breach back in 2021. 

So let’s look at the implications of this easy to do mistake:

1. Potential GDPR violations
2. Loss of customer trust
3. Company reputation lost via social media, youtube videos about you, forums, etc.

Prevent these errors with Mailsac

Obviously no company wants that! This is where mailsac steps in. We help prevent these kinds of easy mistakes, but at the application level. We have a set of features where you can hook up your continuous integration with our API to ensure the email you want to send is the one the recipient actually received.

So let’s walk through how we’d prevent this if this email was coming from our application.

Technical Deep-Dive

Here’s what we’ll do:

1. Setup a sample application that is meant to simulate sending emails.
2. Setup our Mailsac API Key.
3. Send a sample email.
4. Use the API to ensure our cc and email fields match what we sent.

Let’s get started.

Sample Application

• To stand in place of your application, we’ll use this dead simple node app whose sole purpose is to just send an email based on what you place in a form. 
• To simulate our email service API key, we’ll use our Application Key we generated for our gmail account. You can do this too if you want to step through this part. You can find it under your Google account -> security -> 2 FA -> App Password or just search for app passwords.
• Add your credentials in the config.js file directly.
  • Again, while we embed the code here, you should really use a dot-env library.
• Most importantly, for our example here, let’s use a mailsac temporary address. We have ad hoc inbox creation abilities so for now, let’s say we’ll send it to [email protected]
• Fire up the app

Setup our Mailsac API Key

Before we fire off an email, let’s add some quick code to check whether what we send is the same or not once it’s received.

• Head to your Mailsac dashboard
• Generate a new key if you don’t have one
• Grab our api library (npm install @mailsac/api)
  • https://www.npmjs.com/package/@mailsac/api
• Write a test checker after a 1 second wait

The Email CC Checker Snippet

  await setTimeout( async () => {
        const mailsac = new Mailsac({ headers: { "Mailsac-Key":  process.env.MAILSAC_API } })
        const results = await mailsac.messages.listMessages("[email protected]")
        const messages = results.data;
        if (messages[0].cc.length <= 0){
            console.error("This email has no CC. That's Good!")
        } 
        if (messages[0].subject === req.body.subject){
            console.error("This has the correct subject. That's Good!")
        }
      }, 1000);

Normally we’d place it in an .env file, but for our purposes here, we’ll just place it directly in the headers.

Send Sample Email

Alright now let’s fire this up and fire off an email

• Let’s make the content and subject something specific like:
  • Subject: This email is intended only for emailcontentcheck
  • Content: Hey, this email is strictly for [email protected]. No others on cc field.
• Fire it off
• Wait for the check to fire off and print out comparison / success

Use the API to ensure our cc and email fields match what we sent

Right after our code fires off, it should print out the message comparison result. But now, let’s make sure our CC fields are also empty

      await setTimeout( async () => {
        const mailsac = new Mailsac({ headers: { "Mailsac-Key": process.env.MAILSAC_KEY } })
        const results = await mailsac.messages.listMessages("[email protected]")
        const messages = results.data;
        if (messages[0].cc.length <= 0){
            console.error("This email has no CC. That's Good!")
        } 
        if (messages[0].subject === req.body.subject){
            console.error("This has the correct subject. That's Good!")
        }
      }, 1000);

We’re even throwing in a subject line check. You can check out the full API documentation to see how you can check for empty BCCs, content checks, and more.

Fire it off again and enjoy having an automated way test your email content, cc fields, and more!

Wrap Up

Finding the right words to use in an email is already hard enough, don’t complicate it by worrying about whether the email went through,  if it works right, if it accidentally cc’s people, etc. 

Just let mailsac handle the double checking for you.

And if you want to dive even deeper into email testing, we have a full set of articles on integrating with Cypress or integrating other testing tools like Selenium with GitHub Actions for a fully automated testing pipeline.

Related: test email OTP codes and magic links in Playwright.

Testing signup or password-reset emails? See Playwright email testing with Mailsac: a tested helper that waits for the right email, reads its code or link, and runs in parallel workers and GitHub Actions.

These days, we have better options than writing our test specs by hand.

The open source community has released a variety of frameworks to relieve us from that particular tedium: Cypress, Selenium and Pupeteer. And in this video companion guide, I’ll focus on Playwright. Specifically, how playwright can help automate a lot of the boilerplate involved in writing test specs with CodePen.

The video will do a quick walk you through playwright in itself. This article will provide the core login.spec.ts file I used and where to go from next.

But before we do that, it’s worth mentioning that efficient testing isn’t just about the right tools; it’s also about the seamless integration of these tools into your existing systems. That’s where Mailsac comes in. Our platform offers unique capabilities for email testing within your automated workflows, making it an excellent complement to Playwright for end-to-end testing solutions.

With Mailsac, you can ensure not just the functionality but also the integrity of email interactions in your applications, all within the automation framework you’ll establish with Playwright.

So, What Is Playwright?

Playwright is an open-source automation library created by Microsoft. It’s designed to enable developers and testers to write reliable and efficient tests for web applications.

It’s cross platform and officially compatible with the major browsers.

Diving Into Codegen

Start by installing playwright inside your project

npm init playwright@latest

I’ll be using the defaults for this guide. After installation you’ll have these files generated in your project:

Putting Codegen Through Its Paces

First Run

Fire up codegen via the built in console

npx playwright codegen

As you click around your application you’ll see codegen record each click based on its css class.

It will build each line as you go about your test. In our video, we perform a login with an incorrect set of credentials and a correct set.

Our login.spec.ts file

Before our manual edits, this is what codegen generated for us:

import { test, expect } from '@playwright/test';

test('test', async ({ page }) => {
  await page.goto('http://localhost:3000/');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.getByLabel('Email Address').click();
  await page.locator('form div').filter({ hasText: 'Email AddressEmail Address' }).getByRole('paragraph').click();
  await page.getByLabel('Email Address').click();
  await page.getByLabel('Email Address').fill('[email protected]');
  await page.getByLabel('Email Address').press('Tab');
  await page.getByLabel('Password').fill('password');
  await page.getByLabel('Password').press('Enter');
  await page.getByLabel('Email Address').click();
  await page.getByLabel('Email Address').fill('[email protected]');
  await page.getByLabel('Email Address').press('Tab');
  await page.getByLabel('Password').fill('password123');
  await page.getByLabel('Password').press('Enter');
  await page.getByRole('button', { name: 'Settings' }).click();
  await page.getByText('Note: Your email mailsac.demo').click({
    button: 'middle'
  });
  await page.getByRole('button', { name: 'Next boilerplate' }).click();
});

All we had to do was manually add was the highlighted lines (13 and 19) to turn it into a real test:

import { test, expect } from '@playwright/test';

test('test', async ({ page }) => {
  await page.goto('http://localhost:3000/');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.getByLabel('Email Address').click();
  await page.locator('form div').filter({ hasText: 'Email AddressEmail Address' }).getByRole('paragraph').click();
  await page.getByLabel('Email Address').click();
  await page.getByLabel('Email Address').fill('[email protected]');
  await page.getByLabel('Email Address').press('Tab');
  await page.getByLabel('Password').fill('password');
  await page.getByLabel('Password').press('Enter');
  await expect(page).toHaveURL('http://localhost:3000/login');
  await page.getByLabel('Email Address').click();
  await page.getByLabel('Email Address').fill('[email protected]');
  await page.getByLabel('Email Address').press('Tab');
  await page.getByLabel('Password').fill('password123');
  await page.getByLabel('Password').press('Enter');
  await expect(page).toHaveURL('http://localhost:3000/home');
  await page.getByRole('button', { name: 'Settings' }).click();
  await page.getByText('Note: Your email mailsac.demo').click({
    button: 'middle'
  });
  await page.getByRole('button', { name: 'Next boilerplate' }).click();
});

Running the Test

Running the test by default shows no visual progress. But if you’d like to see the browser run through your steps visually, you’ll need to issue the command:

npx playwright test --headed

Where to go next

The most natural next step is integrating playwright tests with a continuous integration platform like Travis or Github Actions. Plugging playwright into a CI system like Github Actions is fully supprted by playwright natively.

Another possible progression is using playwright to test critical paths in your application like user registration or password reset flows. We have a full guide on how to do that with another framework, Cypress.

If you want us to explore how you can integrate playwright with email testing and Github Actions or any other potential playwright integrations, let us know on our forums. We’ve only scratched the very surface of what playwright can do.

Until next time.

Updated September 23, 2026 by Mailsac Engineering. Examples use Cypress 16 and @mailsac/cypress 0.1.0.

New: the complete Cypress email testing guide covers signup codes, password reset links, magic links, GitHub Actions and parallel runs, with tested examples.

Cypress email testing can cover the whole password-reset journey: request an email, receive it, open the correct link, set a new password, and sign in. The difficult part is making sure your test reads the message it just requested, rather than an older reset email or an unrelated notification.

The Mailsac Cypress integration handles that wait in Cypress’s Node process. Your application sends mail through its usual email provider; Mailsac receives it, and the integration reads the matching message through the Mailsac API. The API key stays out of the browser.

Start with the runnable example below, then connect the same pattern to your application. For real delivery, create a Mailsac account and use a test inbox whose message bodies your API key can read.

Run a complete password-reset test first

Use Node.js 22 or 24, the versions exercised in the package’s CI. Clone the published release and run:

git clone --branch v0.1.0 https://github.com/mailsac/cypress-mailsac.git
cd cypress-mailsac
npm ci
npm run test:e2e

The runner starts a small example app and a local Mailsac API fixture, runs Cypress headlessly, then stops the app. This default run needs no account, API key, or SMTP credentials. It sends no email and does not test delivery to the real Mailsac service.

The fixture deliberately contains an old password-reset email and a newer unrelated message. The correct email arrives after a delay. The test waits for it, follows its reset link, changes the password, verifies that the old password fails and the new password works, and checks that the reset link cannot be reused.

The example’s README also documents a separate SMTP mode. That mode sends a real message through your SMTP provider to a Mailsac inbox you control. Copy its .env.smtp.example to the ignored .env.smtp file, supply your SMTP settings and Mailsac key, then follow the two-terminal instructions. The app is a learning example with in-memory accounts, not a production authentication service.

Add Mailsac to your Cypress project

For the versions used in this guide:

npm install --save-dev cypress@16.1.0 @mailsac/cypress@0.1.0

Set MAILSAC_API_KEY in your local process environment or CI secret store. Do not prefix it with CYPRESS_, put it in Cypress.env() or config.env, or commit it.

Register the Node tasks in cypress.config.js. This example uses CommonJS configuration; merge these settings into your existing configuration and adjust baseUrl to your running app.

const { defineConfig } = require('cypress');
const { createMailsacTasks } = require('@mailsac/cypress/node');

module.exports = defineConfig({
  video: false,
  screenshotOnRunFailure: false,
  e2e: {
    baseUrl: 'http://localhost:3000',
    setupNodeEvents(on, config) {
      on('task', createMailsacTasks());
      return config;
    },
  },
});

Then add the command registration to cypress/support/e2e.js or cypress/support/e2e.ts:

import '@mailsac/cypress/commands';

The command passes message criteria to a Node task; only the resulting message data comes back to the test. Automatic failure screenshots and video are disabled here because password-reset tokens appear in URLs. Also avoid logging message bodies, links, or codes.

Wait for the right email and follow its reset link

Save this spec as cypress/e2e/password-reset.cy.js. It uses the routes, button labels, and subject from the example app. When applying it to your own app, change the inbox, subject, reset path, selectors, and assertions to match your implementation. Start your app before running Cypress and configure it to send to the chosen test inbox.

import { extractLink } from '@mailsac/cypress';

it('resets a password and signs in', () => {
  const email = 'your-private-test-inbox@mailsac.com';
  const newPassword = 'my-new-demo-password';
  let receivedAfter;

  cy.visit('/forgot-password');
  cy.get('input[name=email]').type(email);

  // Capture immediately before requesting the email.
  cy.then(() => { receivedAfter = new Date().toISOString(); });
  cy.contains('button', 'Send reset email').click();

  cy.then(() => cy.mailsacWaitForMessage({
    email,
    receivedAfter,
    subject: 'Reset your Example App password',
    timeoutMs: 60_000,
    pollIntervalMs: 1_000,
  })).then((message) => {
    const resetUrl = extractLink(message, {
      origin: new URL(Cypress.config('baseUrl')).origin,
      pathname: '/reset',
    });
    cy.visit(resetUrl, { log: false });
  });

  cy.get('input[name=password]').type(newPassword, { log: false });
  cy.contains('button', 'Update password').click();
  cy.contains('h1', 'Password updated').should('be.visible');
  cy.contains('a', 'Sign in').click();
  cy.get('input[name=email]').type(email);
  cy.get('input[name=password]').type(newPassword, { log: false });
  cy.contains('button', 'Sign in').click();
  cy.get('[role=status]').should('contain', 'signed in successfully');
});

With your app running and the test adapted to it, run:

npx cypress run --spec cypress/e2e/password-reset.cy.js

receivedAfter excludes older mail. Capturing it before the click also prevents a fast-arriving message from being excluded. An exact subject narrows the result; you can additionally match a sender with from, or use subjectIncludes for a subject substring. All supplied filters must match.

extractLink requires one distinct link with your app’s exact origin and reset path. It fails if the email has no matching link or several different matching links. That keeps a test from accidentally following a footer, help page, or unrelated website. If your sender wraps links in a tracking URL, disable tracking for these test messages or explicitly test that redirect flow.

Keep email tests reliable in CI

• Bound the wait. The default is 30 seconds; the example allows 60. The maximum is 120 seconds, including requests and retries. A timeout should fail the test rather than wait indefinitely.
• Separate parallel tests. Use a distinct inbox or a unique subject per test. A timestamp alone cannot distinguish simultaneous requests to one inbox. Keep the runner’s clock synchronized.
• Use dedicated inboxes. Each poll checks the latest 100 messages. Avoid a busy shared catch-all. Polls and message reads consume Mailsac API operations; choose your interval and concurrency accordingly.
• Protect reset links. Use a private inbox or owned domain for sensitive messages. The integration reads mail; it does not delete messages or change retention settings.

To run the cloned repository’s fixture example in GitHub Actions, no service secrets are needed:

name: Email test example
on: [push, pull_request]
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run test:e2e

For your own app’s live-delivery CI test, start the app and its mail sender, provide MAILSAC_API_KEY through the CI secret store, and run your adapted Cypress spec. Keep that explicit live test separate from the local fixture run.

Testing verification codes too

For an OTP flow, use extractCode(message) on the matching message to return one distinct standalone six-digit code, then enter it with { log: false }. The helper rejects missing or ambiguous codes and supports custom patterns. See the OTP example and API reference.

Cypress email testing FAQ

Can Cypress read emails?

Not on its own: Cypress drives the browser, and email arrives outside it. A Cypress task running in Node can call an inbox API, though. That’s what @mailsac/cypress does: cy.mailsacWaitForMessage() polls Mailsac from Node until the matching message arrives and returns its content to your test.

How do I test email OTP or verification codes in Cypress?

Wait for the message as in the reset example, then call extractCode(message) and type the result with { log: false }. It returns one distinct six-digit code by default and fails if the code is missing or ambiguous; you can pass a custom pattern for other formats.

Do I need my own email server or domain?

No. Any @mailsac.com address can receive mail without setup, which is fine for made-up test accounts. Public inboxes are readable by anyone, so for reset links and codes on realistic accounts use a private address or a custom domain. Mailsac can host a test subdomain for you, with no DNS changes needed.

Will this work in CI with parallel runs?

Yes. Give each test its own address (or a unique subject), capture receivedAfter just before triggering the email, and supply MAILSAC_API_KEY from your CI secret store. Each poll and message read counts as an API operation, so set the poll interval to match your plan.

The original 2023 video remains available for historical reference. It predates this integration; use the package and code above for the current workflow.

Create your Mailsac account, install the Cypress integration, or explore the complete password-reset example.