Test Password-Reset Emails End to End with Playwright
Test password-reset emails with Playwright: receive the right link, change the password, verify login, and reject reuse in clean browser sessions.
REST API · WEBHOOKS · POP3 · IMAP
Email testing with serious muscle
Give every test its own real inbox. Capture the email your app sends, wait for it without a fixed sleep, and assert on parsed codes and links — from CI, your code, or an AI agent.
Free plan · No credit card required · 14-day trial on paid plans
import { MailhulkClient } from '@mailhulk/sdk'
const apiKey = process.env.MAILHULK_API_KEY!
const mh = new MailhulkClient({ apiKey })
// 1. A real inbox for this test only
const inbox = await mh.inboxes.create()
// 2. Trigger your app
await signUp(inbox.address)
// 3. Bounded wait — no sleep(10)
const mail = await mh.inboxes.waitForMessage(inbox.id, {
timeoutMs: 60_000,
match: (m) => m.codes.length > 0,
})
expect(mail.codes[0]).toHaveLength(6)
- One inbox
- per test run, 60 s to 30 days TTL
- ≤ 60 s
- server-side long-poll wait
- 993 / 995
- IMAP & POP3 over TLS
- OpenAPI
- contract for every
/v1route
HOW IT WORKS
Three calls between a flaky test and a green one
-
01
Create an isolated inbox
Each run gets a fresh address that nothing else writes to, so a stale or parallel message can never satisfy your assertion.
-
02
Wait for the message
A server-side long poll returns the moment mail lands, with an explicit timeout so a missing email fails fast and clearly.
-
03
Assert on parsed content
Verification codes, links, bodies, headers and attachments are already extracted — no MIME parsing in your test code.
The usual workaround compared with MailHulk
-
Usual workaround: One shared inbox that every run and every teammate reads
With MailHulk: A fresh inbox per run that nothing else can write to
-
Usual workaround:
sleep(10)and hope the email made it in timeWith MailHulk: A long poll that returns on arrival, or
204at your timeout -
Usual workaround: Regex over raw MIME to dig out a code or link
With MailHulk: Codes, links and bodies arrive already parsed
-
Usual workaround: Cleanup scripts for every inbox a crashed run left behind
With MailHulk: A TTL from 60 s to 30 days expires the inbox by itself
FEATURES
Everything email, done heavy-duty
REST API for everything
Create inboxes, list messages, read links and attachments — one bearer token, JSON envelopes and a published OpenAPI contract.
Signed webhooks
An authenticated callback after each message is stored, with retries and a visible delivery history when an endpoint misbehaves.
POP3/IMAP access
Standard TLS mail protocols when your system needs a real mailbox. Dedicated server capacity starts on Pro.
Unlimited inboxes on paid plans
A fresh address per test run with no pooling or cleanup scripts. Paid plans never meter inboxes; Free includes 25.
Deep email parsing
HTML and plain-text bodies, links, verification codes and attachment metadata extracted automatically on arrival.
Custom domains
Receive on your own domain with a copy-ready DNS guide and automatic verification, from Pro upwards.
API FIRST
Use the API or a standard mail protocol
Every capability is plain HTTP and JSON. Wait on an inbox with a long poll, receive signed webhook deliveries, or connect a mail client over POP3/IMAP.
-
Responses wrapped in a stable
dataenvelope -
204until mail arrives, never a guess - Full MIME, attachments, HTML & links parsed
# Wait up to 30 s for the next message
BASE=https://mailhulk.net/v1
curl "$BASE/inboxes/$INBOX_ID/messages/latest?wait=30" \
-H "Authorization: Bearer $MAILHULK_API_KEY"
# → 200 OK (204 No Content if nothing arrived)
{ "data": {
"subject": "Verify your email",
"from": { "email": "noreply@yourapp.com", "name": "YourApp" },
"codes": ["481902"],
"links": ["https://yourapp.com/verify?token=…"]
} }
// Plain fetch — or use @mailhulk/sdk
const base = 'https://mailhulk.net/v1'
const url = `${base}/inboxes/${inboxId}/messages/latest?wait=30`
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
})
if (res.status === 204) throw new Error('No email within 30 s')
const { data } = await res.json()
expect(data.subject).toBe('Verify your email')
# Plain requests — no SDK needed
BASE = "https://mailhulk.net/v1"
res = requests.get(
f"{BASE}/inboxes/{inbox_id}/messages/latest",
params={"wait": 30},
headers={"Authorization": f"Bearer {api_key}"},
timeout=40,
)
assert res.status_code == 200, "No email within 30 s"
assert res.json()["data"]["subject"] == "Verify your email"
WORKS WITH YOUR STACK
Fits the way you already test
Call the API directly, or reach for a client built around the same bounded-wait semantics. Availability is labelled honestly.
AVAILABLE
JavaScript SDK
Typed TypeScript client with zero dependencies. waitForMessage scans existing mail before it waits.
npm install @mailhulk/sdk
AVAILABLE
REST API + OpenAPI
Every capability over HTTP and JSON, documented by a downloadable OpenAPI contract.
GET /v1/inboxes/{id}/messages/latest?wait=30
AVAILABLE
POP3 / IMAP
Point an existing mail library or client at a real mailbox over TLS.
imap.mailhulk.net:993 · pop3.mailhulk.net:995
PREVIEW
MCP server
Eleven inbox and message tools for coding and QA agents, over stdio or HTTP, scoped to a Test project.
wait_for_message · get_message · release_session
COMING SOON
CLI
Create an inbox and wait for a code from any shell step, with CI-friendly exit codes.
mailhulk mail wait "$ADDRESS" --extract code
COMING SOON
Python & PHP SDKs
The same inbox and wait semantics for pytest and PHPUnit suites. Plain HTTP works today.
mh.inboxes.wait_for_message(inbox.id, timeout=60)
USE CASES
One mail pipeline, three front doors
FOR TEST SUITESAVAILABLE
Email-testing API
Developers and CI assert on real mail with ephemeral inboxes, long-poll waits and signed webhooks.
See the flow
FOR AI AGENTSPREVIEW
AI agents as clients
Your coding or QA agent reads verification mail through an MCP server with scoped, session-bound access.
See the boundary
FOR MANUAL CHECKSIN DESIGN
Disposable inbox
A throwaway address in the dashboard for a manual check, with the same isolation and retention rules.
See the scope
PRICING
Choose the isolation your tests need
Free
$0
/mo
No card required
Prove one real email flow end to end.
✓ 3-day retention
✓ 25 concurrent inboxes
✓ 3 team members
✓ 50 MiB per inbox
✓ 250 MiB team storage
✓ REST API + webhooks
Starter
$9
/mo
Billed monthly
$86.40 billed yearly
A first suite in CI, without a shared inbox.
✓ 7-day retention
✓ Unlimited inboxes
✓ 5 team members
✓ 250 MiB per inbox
✓ 2 GiB team storage
✓ REST API + webhooks
MOST POPULAR
Pro
$39
/mo
Billed monthly
$374.40 billed yearly
Parallel CI on your own mail server.
✓ 30-day retention
✓ Unlimited inboxes
✓ Unlimited team members
✓ 3 custom domains
✓ 1 GiB per inbox
✓ 10 GiB team storage
✓ REST API + webhooks
Business
$99
/mo
Billed monthly
$950.40 billed yearly
More projects, retention, storage, and support.
✓ 90-day retention, or custom
✓ Unlimited inboxes
✓ Unlimited team members
✓ 10 custom domains
✓ 5 GiB per inbox
✓ 50 GiB team storage
✓ REST API + webhooks
Dedicated POP3/IMAP servers and custom domains start on Pro; Enterprise and custom terms are on the pricing page. Compare every plan capability.
FROM THE BLOG
Guides for deterministic email tests
Playwright Email Testing: OTPs, Magic Links, Password Resets
Choose an email-testing boundary for Playwright, then test OTPs, magic links, and password resets with isolated inboxes and bounded waits.
Build a Reusable Playwright Email Inbox Fixture
Build a test-scoped Playwright email fixture with isolated inboxes, bounded waits, retry-safe ownership, and teardown after failures.
FAQ
Frequently asked questions
MailHulk creates isolated inboxes for testing. Send your application email to those addresses, then inspect captured messages through REST, webhooks, POP3, or IMAP. It is receive-only: nothing is sent or relayed onward.
Yes. Plans with protocol access provide standard POP3 (995) and IMAP (993) credentials with TLS, so compatible clients and libraries can connect normally.
A signed webhook delivery is queued when a message is stored. Delivery history and retries make failures visible; use a bounded API wait when your test needs deterministic timing.
That is the core use case. Create an inbox per test run through the REST API or the JavaScript SDK, use a bounded wait, assert on the received message, and let the inbox expire or delete it during cleanup.
An MCP server that exposes inbox and message tools to agents is in preview. Agent access is scoped to a Test project and treats email content as untrusted data rather than instructions.
Retention is plan-specific and shown in the live comparison on the Pricing page. You can also delete messages or inboxes earlier through the API.
The Free plan needs no credit card. Paid plans carry a 14-day trial; review the current plan and billing state in the dashboard before enabling paid service.
Give your test suite real muscle
Create an isolated inbox and make email failures reproducible.
No credit card required · 14-day trial on paid plans