Skip to content

Email testing for developers

Test signup, magic link and password reset emails end to end in Playwright, Cypress and CI. Every endpoint on a webhooks.cc account has a real email address: your test signs up with it, the SDK waits for the email your app sends, and hands back the one-time code or the link inside.

# Your endpoint's address
my-app@mailhooks.cc

# One per test run, same endpoint, nothing to create
my-app+run-42@mailhooks.cc
Start free:
or sign up with email

Free for 50 emails a day, no credit card. Read the Playwright email testing guide or the email capture docs.

Test a magic link email in Playwright

The whole test: sign up with a tagged address, wait for the email, open the link. The SDK finds the link with the same finder the dashboard uses, and actionOnly makes a template without a sign-in link fail the test.

import { test, expect } from "@playwright/test";
import { WebhooksCC, extractLink } from "@webhooks-cc/sdk";

const client = new WebhooksCC({ apiKey: process.env.WHK_API_KEY! });
const SLUG = process.env.WHK_EMAIL_ENDPOINT!; // your endpoint's slug

test("sign up and follow the magic link", async ({ page }, testInfo) => {
  // A tag per test: my-app+w0-1791450602000@mailhooks.cc
  const tag = `w${testInfo.workerIndex}-${Date.now()}`;

  await page.goto("/signup");
  await page.getByLabel("Email").fill(client.emails.address(SLUG, tag));
  await page.getByRole("button", { name: "Sign up" }).click();

  // Waits up to 60 seconds for the email sent to this test's address.
  const email = await client.emails.waitFor(SLUG, { tag });
  expect(email.email.subject).toContain("Sign in");

  // The confirm, verify, reset or sign-in link, or null when there is none.
  const link = extractLink(email, { actionOnly: true });
  expect(link).not.toBeNull();

  await page.goto(link!);
  await expect(page).toHaveURL(/\/dashboard/);
});

Install with npm install --save-dev @webhooks-cc/sdk and create the API key on your account page. Step by step, with a fixture per test, password resets and CI: how to test emails in Playwright.

The email flows it covers

Signup confirmation

Fill the signup form with a tagged address, wait for the confirmation email, and enter its code or open its link.

Magic link sign-in

Ask for a sign-in link, read it with extractLink(), and open it in the same browser context so the session lands where a user's would.

One-time codes

extractCode() returns the 4 to 8 digit code (or short letter and digit code) that sits next to a word like code, verification or PIN.

Password reset

Request a reset, follow the reset link, set a new password, and sign in with it, all in one test.

One-time codes, Cypress and other runners

For a verification code, wait the same way and read it with extractCode():

import { extractCode } from "@webhooks-cc/sdk";

const email = await client.emails.waitFor(SLUG, { tag, subject: "verification code" });
const code = extractCode(email); // "482913", or null when the email has none
await page.getByLabel("Verification code").fill(code!);

In Cypress the SDK runs in Node, so put the wait in a task and hand the link to the test:

// cypress.config.ts: the SDK runs in Node, behind a task
import { defineConfig } from "cypress";
import { WebhooksCC, extractLink } from "@webhooks-cc/sdk";

const client = new WebhooksCC({ apiKey: process.env.WHK_API_KEY! });

export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      on("task", {
        async emailLink({ slug, tag }: { slug: string; tag: string }) {
          const email = await client.emails.waitFor(slug, { tag, timeout: "45s" });
          return extractLink(email, { actionOnly: true });
        },
      });
    },
  },
});

// In a test
cy.task("emailLink", { slug, tag }).then((link) => cy.visit(link as string));

The Python and Go SDKs have the same waits and finders for pytest and Go tests, and the REST API returns the same emails with kind=email and extracts=true, so Selenium or any runner that can make an HTTP call works too. AI coding agents get the same through the MCP server: wait_for_email returns the email with its code and link. More patterns: testing emails with the SDK.

How it works

  1. 1

    Create an endpoint

    Sign up free and create an endpoint. Next to its webhook URL it has an email address: the endpoint's slug at mailhooks.cc.

  2. 2

    Give each test run its own address

    Add a tag after a plus sign, like my-app+run-42@mailhooks.cc. Tagged mail lands on the same endpoint, so there are no inboxes to create or clean up, and parallel tests never read each other's mail.

  3. 3

    Run the flow in your app

    Sign up, ask for a magic link or reset a password with that address. Your app sends the email through its real provider; nothing in its mail settings changes.

  4. 4

    Wait for the email and use what is in it

    The SDK waits until the email for that tag arrives and returns the one-time code or the link, so the test can type the code or open the link and finish the flow.

Check the email by hand before you ship

Every captured email also opens in the dashboard, next to the endpoint's webhooks.

Codes and links, picked out

The one-time code and the link the email asks you to click sit at the top, each with a copy button. Unsubscribe and tracking links stay out of the way.

A preview that cannot bite

The HTML renders in a sandboxed frame with no scripts. Remote images wait until you load them, so opening an email tells the sender nothing.

Sender checks

SPF, DKIM, DMARC, reverse DNS and TLS for every message, with what each result means, so you see what an inbox provider would think of your mail.

The email as JSON

Every email opens on a JSON view of the parsed message: sender, recipients, subject, text, HTML, codes, links and attachments. Copy it as a test fixture.

Emails next to your webhooks

Mail lands in the same list as the endpoint's HTTP requests, so a signup that fires a webhook and a confirmation email can be checked in one place.

Headers, raw source and .eml

Every header as it arrived, the raw message, the attachment list, and a download of the original .eml file.

Compared with other email testing tools

What each tool is better at, with prices and limits from its own site.

Need the email in your own app?

Add a destination and every email the endpoint receives is posted to your server as signed JSON, retried until your server accepts it. No mail server to run and no MIME to parse.

Email to webhook

Limits

  • Every plan, Free included; an email counts as one request
  • Messages up to 10 MB, up to 20 recipients each
  • Text and HTML stored up to 256 KB each
  • The original .eml kept whole
  • Attachments kept and downloadable
  • Same retention as your HTTP requests

Email testing questions

Your test inbox is one signup away

Sign up free, create an endpoint, and send your first email to it.

or sign up with email

No credit card