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.ccFree 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
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
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
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
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.
webhooks.cc vs Mailtrap
A fake SMTP server with HTML and spam checks, against real addresses with codes and links picked out.
webhooks.cc vs Mailosaur
The same wait-and-extract workflow with SMS and device previews, on paid plans from $20 a month.
webhooks.cc vs MailSlurp
An email and SMS API whose inboxes also send, against a receive-only endpoint that catches webhooks too.
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 webhookLimits
- 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
Install @webhooks-cc/sdk, create an endpoint, and fill your form with client.emails.address(slug, tag), which gives slug+tag@mailhooks.cc. After the app sends its email, client.emails.waitFor(slug, { tag }) polls until it arrives (60 seconds by default) and returns the subject, sender, text, HTML and attachments. extractCode(email) and extractLink(email) return the one-time code and the link, so the test can finish the flow in the browser.
Ask for the link with a tagged address, wait for the email with client.emails.waitFor(slug, { tag }), and call extractLink(email, { actionOnly: true }). It returns the link the email asks you to click (sign in, confirm, verify or reset) and null when there is none, so a broken template fails the test. Open the link with page.goto() in the same browser context and check that you are signed in.
The same way. For a reset, wait for the email and follow extractLink(email, { actionOnly: true }) to the reset form. For a one-time code, extractCode(email) returns the code when a word such as code, verification or PIN sits next to it, so order numbers and years are not mistaken for one.
Yes. The TypeScript SDK runs in Node, so in Cypress call it from a task (cy.task) and return the code or link to the test. The Python SDK has client.emails.wait_for and extract_code, and the Go SDK client.Emails.WaitFor and ExtractCode. From any other language, poll the requests API with kind=email and extracts=true; each email comes back as JSON with the codes and links found in it.
Yes. Store the API key and the endpoint's slug as CI secrets. One endpoint serves the whole suite: each test uses its own +tag, and waitFor only matches mail sent to that tag, so parallel workers and concurrent pipeline runs do not see each other's email. Nothing has to be reachable from the internet, because the test fetches the email over HTTPS.
No. There are no SMTP credentials to swap in. The address is a real one, so your app sends through whatever it uses (Resend, Postmark, SES, SendGrid, plain SMTP), and the email is captured as it really arrived, with SPF, DKIM and DMARC results. The provider has to really send: a sandbox mode that drops mail delivers nothing.
No. Email capture is on every plan, Free included. Each email counts as one request against the same quota as your webhooks: 50 a day on Free, 100,000 a month on Pro and 250,000 a month on Business.
Mailtrap Email Sandbox traps mail on a fake SMTP server and checks its HTML; webhooks.cc receives at real addresses and hands the test the code or link. Mailosaur and MailSlurp work like webhooks.cc for email and add SMS, device previews and sending, at higher prices. webhooks.cc adds webhook capture on the same endpoint, a free plan with 50 emails a day and open-source code. Each has its own comparison page.
No. Guest endpoints on the landing page receive HTTP requests only, because anyone who knows a guest slug can read what it captured. Every endpoint on a free account receives email.
No. mailhooks.cc only receives. It never sends mail, replies or bounces, so the addresses cannot be used to send spam.
Your test inbox is one signup away
Sign up free, create an endpoint, and send your first email to it.
No credit card