Mailosaur and Cypress - Quickstart

What you'll need

A Mailosaur account. If you don't already have one, create a free trial account.
An API key. Log into your account and generate one in order to run automated tests.
Knowledge of how to send emails (or SMS) into your account.

Express: Generate a sample project

If you have npm installed, you can generate a basic starter project for Cypress via the command line:

npm create mailosaur@latest

This will give you a simple Cypress project with Mailosaur already configured, along with some basic tests that show how a project would typically work. You can also see similar sample code on GitHub.

Integrate with an existing Cypress project

If you have an existing Cypress project, or have just created one, you'll need to install and configure Mailosaur's API client library:

Install the Mailosaur plugin

Mailosaur provides an official set of custom commands for automating email testing in Cypress.

Extend Cypress by installing Mailosaur’s custom commands package: cypress-mailosaur.

Install the plugin via npm:

npm install cypress-mailosaur

Open cypress/support/e2e.js in your project folder, and add the following line of code to it:

import "cypress-mailosaur";

Add your Mailosaur API key to cypress.config.js, in your project folder:

module.exports = defineConfig({
  env: {
    MAILOSAUR_API_KEY: "YOUR_API_KEY",
  },

  // ...
});

Note: We strongly recommend against storing API keys in source control. Therefore you can also set your API key using the environment variable CYPRESS_MAILOSAUR_API_KEY.

Make your first API call

// Make a simple API call to find the name of your inbox
cy.mailosaurListServers().then((result) => {
  cy.log(`Inbox name is ${result.items[0].name}`);
});

Start testing

Now that you have a project connected to the Mailosaur API, you can start creating a variety of tests: