Set up Cypress and Mailsac

You need Cypress 16, Node.js 22, 24 or 26, and an app that sends real email (on your machine or in a test environment). Mailsac receives test email; it doesn’t send it.

1. Get an API key. Create a free account, then generate a key under API Keys & Users in the dashboard. The key is shown once, so store it like a password. The free plan includes an API key, one private address and 1,500 operations a month.
2. Install Cypress and the plugin.

Terminal

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

1. Put the key in an environment variable. Name it MAILSAC_API_KEY, with no CYPRESS_ prefix. The plugin reads it in Cypress’s Node process, so it never reaches the page under test, screenshots or your repository. Never hard-code it in a spec or in cypress.config.js.

Terminal

# Local runs (macOS/Linux shell). In CI, use your secret store instead.
export MAILSAC_API_KEY="your-api-key"
npx cypress run

1. Register the plugin’s Node task in cypress.config.js. Merge this into your existing config and set baseUrl to your app.

cypress.config.js

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

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000', // your app
    setupNodeEvents(on, config) {
      // Reads MAILSAC_API_KEY from the Node process. The key never reaches the browser.
      on('task', createMailsacTasks());
      return config;
    },
  },
});

1. Add the command to your support file.

cypress/support/e2e.js

import '@mailsac/cypress/commands';

Test a signup verification code (OTP)

This test signs up with a new address, waits for the verification email, types the six-digit code and checks that the account is verified. Change the paths, selectors, button labels and subject to match your app.

cypress/e2e/signup-code.cy.js

import { extractCode } from '@mailsac/cypress';
import { newInbox } from '../support/inbox';

describe('signup', () => {
  it('verifies a new account with the emailed code', () => {
    const email = newInbox('signup');
    let receivedAfter;

    cy.visit('/signup');
    cy.get('input[name=email]').type(email);
    cy.get('input[name=password]').type('Test-password-123', { log: false });
    // Take the timestamp just before the click that sends the email.
    cy.then(() => { receivedAfter = new Date().toISOString(); });
    cy.contains('button', 'Create account').click();

    cy.then(() => cy.mailsacWaitForMessage({
      email,
      receivedAfter,
      subject: 'Your verification code',
      timeoutMs: 60_000,
    })).then((message) => {
      const code = extractCode(message); // exactly one 6-digit code, or the test fails
      cy.get('input[name=code]').type(code, { log: false });
    });
    cy.contains('button', 'Verify email').click();
    cy.contains('h1', 'Email verified').should('be.visible');
  });
});

• Take receivedAfter just before the click. Only mail received at or after that moment counts, so an older email in the same inbox can’t fool the test. Taken after the click, it could miss an email that arrives fast.
• Wrap the wait in cy.then(). Cypress queues commands before it runs them. Without the wrapper, receivedAfter would still be undefined when the command is queued.
• extractCode() wants exactly one match. By default it looks for one standalone six-digit number in the plain-text body and fails if it finds none or two different ones. For other formats pass a pattern, for example extractCode(message, { pattern: 'Code: ([A-Z0-9]{8})', group: 1 }).
• { log: false } keeps the code out of the Cypress command log.

Test a magic link sign-in

Passwordless sign-in works the same way: request the link, wait for the email, open the link. This test also checks that the link can’t be used twice.

cypress/e2e/magic-link.cy.js

import { extractLink } from '@mailsac/cypress';
import { newInbox } from '../support/inbox';

describe('magic link', () => {
  it('signs in with the emailed link, which works only once', () => {
    const email = newInbox('magic');
    let receivedAfter;

    cy.request({ method: 'POST', url: '/signup', form: true, body: { email, password: 'Test-password-123' } });

    cy.visit('/login');
    cy.get('#magic-link input[name=email]').type(email);
    cy.then(() => { receivedAfter = new Date().toISOString(); });
    cy.contains('button', 'Email me a sign-in link').click();

    cy.then(() => cy.mailsacWaitForMessage({
      email,
      receivedAfter,
      subject: 'Your sign-in link',
      timeoutMs: 60_000,
    })).then((message) => {
      const link = extractLink(message, {
        origin: new URL(Cypress.config('baseUrl')).origin,
        pathname: '/magic',
      });
      cy.visit(link, { log: false });
      cy.contains('h1', `Signed in as ${email}`).should('be.visible');

      // The same link must not work twice.
      cy.request({ url: link, failOnStatusCode: false, log: false }).its('status').should('eq', 400);
    });
  });
});

Run all three specs with npx cypress run, or one at a time with npx cypress run --spec cypress/e2e/magic-link.cy.js.

Without the plugin: plain cy.request

The plugin needs Cypress 16. On older versions, or if you’d rather not add a dependency, call the Mailsac REST API with cy.request. Every request sends your key in the Mailsac-Key header.

cypress/support/mailsac-request.js

// Read test email with cy.request only, no plugin.
// The key comes from the CYPRESS_MAILSAC_API_KEY environment variable (cy.env needs Cypress 15.10 or later).
const API = 'https://mailsac.com/api';

function mailsac(key, path, method = 'GET') {
  return cy.request({ method, url: API + path, headers: { 'Mailsac-Key': key }, log: false });
}

// Poll the inbox until a message with this subject arrives after receivedAfter, then fetch its text.
export function waitForEmail(email, { subject, receivedAfter, timeoutMs = 60000, intervalMs = 2000 }) {
  const inbox = encodeURIComponent(email);
  const deadline = Date.now() + timeoutMs;
  return cy.env(['MAILSAC_API_KEY'], { log: false }).then(({ MAILSAC_API_KEY: key }) => {
    const poll = () => mailsac(key, `/addresses/${inbox}/messages?limit=20`).then(({ body }) => {
      const message = body.find((m) =>
        (m.subject || '').includes(subject) && Date.parse(m.received) >= Date.parse(receivedAfter));
      if (message) {
        return mailsac(key, `/text/${inbox}/${encodeURIComponent(message._id)}`)
          .then(({ body: text }) => ({ ...message, text })); // _id, subject, links, text, ...
      }
      if (Date.now() > deadline) throw new Error(`No "${subject}" email for ${email} after ${timeoutMs} ms`);
      return cy.wait(intervalMs, { log: false }).then(poll);
    });
    return poll();
  });
}

export function deleteEmail(email, messageId) {
  return cy.env(['MAILSAC_API_KEY'], { log: false }).then(({ MAILSAC_API_KEY: key }) =>
    mailsac(key, `/addresses/${encodeURIComponent(email)}/messages/${encodeURIComponent(messageId)}`, 'DELETE'));
}

cypress/e2e/signup-code-request.cy.js

import { waitForEmail, deleteEmail } from '../support/mailsac-request';
import { newInbox } from '../support/inbox';

it('verifies a new account with cy.request only', () => {
  const email = newInbox('signup');
  let receivedAfter;

  cy.visit('/signup');
  cy.get('input[name=email]').type(email);
  cy.get('input[name=password]').type('Test-password-123', { log: false });
  cy.then(() => { receivedAfter = new Date().toISOString(); });
  cy.contains('button', 'Create account').click();

  cy.then(() => waitForEmail(email, { subject: 'Your verification code', receivedAfter }))
    .then((message) => {
      const code = message.text.match(/\b\d{6}\b/)[0];
      cy.get('input[name=code]').type(code, { log: false });
      deleteEmail(email, message._id); // optional cleanup
    });
  cy.contains('button', 'Verify email').click();
  cy.contains('h1', 'Email verified').should('be.visible');
});

For a link instead of a code, use the links array that Mailsac adds to every message:

Reading a reset link with the cy.request helper

cy.then(() => waitForEmail(email, { subject: 'Reset your password', receivedAfter }))
  .then((message) => {
    const resetUrl = message.links.find((url) => url.startsWith(`${Cypress.config('baseUrl')}/reset-password`));
    cy.visit(resetUrl, { log: false });
  });

• Set the key as CYPRESS_MAILSAC_API_KEY in your shell or CI secrets; cy.env() reads it. Cypress 15.9 and older don’t have cy.env(); use Cypress.env('MAILSAC_API_KEY') there. Cypress 16 removed Cypress.env(); calling it throws an error.
• Trade-off: with this approach the key is available to your spec code. The plugin keeps it in Node only. log: false keeps the header out of the command log.
• Errors stop the test. cy.request fails on any non-2xx response, including 429. The plugin retries those.

Text, HTML and links

• GET /api/text/{email}/{messageId} returns the plain-text body. If the email only has HTML, Mailsac generates the text. This is the easiest place to find a code.
• Every message’s metadata, including the inbox list, has a links array: the HTTP(S) links Mailsac found in the text and HTML bodies, with HTML entities such as & already decoded.
• GET /api/dirty/{email}/{messageId} returns the original HTML, if you need to assert on markup. GET /api/body/{email}/{messageId} returns sanitized HTML with links removed, so don’t use it to find links.

Full details are in the API reference.

Parallel runs and private domains

Email tests break in parallel for three reasons. Each has a simple fix.

Two tests read the same inbox

If tests share an address, one test can pick up the other’s email. Call newInbox() in every test. A timestamp alone can’t tell apart two emails sent to one inbox at the same moment. If some tests must share a fixed, pre-seeded account, don’t run them at the same time, and give each a distinct subject to match.

Mail is delayed on the shared mailsac.com domain

Public @mailsac.com addresses have lower inbound throttling limits than private domains. A busy suite, or many CI jobs at once, can see mail slow down there and tests time out. Custom domains have higher limits. Move busy suites to a private domain: a zero-DNS yourteam.msdc.co subdomain, or your own domain verified with a TXT record and MX records pointing to Mailsac. Custom domains are included from the Indie plan up.

Anyone can read public inboxes

Anyone can open a public @mailsac.com inbox on the Mailsac website without an account, and public inboxes are temporary. Use them only for made-up data. Reset links, codes and anything with real personal data belong on a private address or a custom domain, where only your account and team can read the mail. On a custom domain every address receives mail with no setup, so newInbox() works unchanged.

Troubleshooting

First, check what actually arrived. This lists the newest messages in an inbox (needs curl and jq):

Terminal

curl -s -H "Mailsac-Key: $MAILSAC_API_KEY" \
  "https://mailsac.com/api/addresses/signup-123@yourteam.msdc.co/messages?limit=5" \
  | jq '.[] | {subject, received, from: .from[0].address, links}'

“Set MAILSAC_API_KEY in the Node process”

Cypress was started without the variable. Export it in the same shell, or check the secret name in CI. Remember that it has no CYPRESS_ prefix for the plugin.

“Timed out after 60000 ms waiting for a matching email”

• Compare the address your app sent to with the one in the test.
• subject must match exactly, including case. Use subjectIncludes if your subject contains a name or date.
• Take receivedAfter before the click, and keep the test machine’s clock in sync: the time is compared with Mailsac’s received time.
• Check your email provider’s logs. Some sandbox or test modes accept mail without delivering it.
• On public @mailsac.com addresses, throttling can delay a busy suite. Use a private domain.

“API access denied (HTTP 401)” or “(HTTP 403)”

401 means Mailsac didn’t accept the key: look for extra spaces or an old key. 403 usually means the address is private and belongs to a different Mailsac account; use a key from the account that owns the address or domain.

“expected one distinct matching link; found 0” (or 2)

Found 0: your email provider’s click tracking may have rewritten the link (turn it off for test mail), the link’s host doesn’t match baseUrl, or the token is part of the path, such as /reset/abc123, so pathname never matches. Found 2: the email contains two different links to that path. Fix the template or narrow the match.

“expected one distinct matching code; found 0” (or 2)

Found 0: the code is formatted differently, for example 482 913. Found 2: another six-digit number, such as an order number, is in the email. Pass a pattern that matches your wording.

HTTP 429

The plugin retries 429 responses until its deadline. If they keep coming, the account may have used its monthly operations; Mailsac emails a warning first. Operations reset on the first of each month (UTC).

Tests pass alone but fail in parallel

Two tests share an address or a fixed account. Use newInbox() in every test, and see parallel runs.

“Cypress.env() was removed in Cypress version 16.0.0”

Older snippets read the key with Cypress.env(), which now throws. Use the plugin, which keeps the key in Node, or cy.env() as in the cy.request helper.