Real-World Scenarios
Customer Use Cases
Six real workflows where teams replaced mocked email with actual SMTP delivery. Each shows the problem, the MailFork approach, and the result.
OTP / 2FA Verification Flows
The Problem
Every login test with OTP either mocks the delivery (no real coverage) or requires a real personal inbox (flaky, shared state, CI-unsafe). Mocked SMTP tests can't validate MIME structure, multipart encoding, or actual OTP parsing.
The MailFork Approach
1. Create a team inbox: [email protected]
2. Each test run creates a 1-hour ephemeral alias with a unique tag
3. App sends OTP to the alias address
4. extractOtp() polls and returns the code in <1s
The Result
Real SMTP delivery. Real OTP parsing. Zero flakiness from shared state. Your entire login flow — from email send to extraction — uses the same code path your users hit.
Magic Link / Passwordless Auth
The Problem
Magic link tests need to capture the token from a real email, not a hardcoded value. Mocking the email service means you're not testing token generation, MIME structure, or URL extraction logic.
The MailFork Approach
1. Trigger the password reset flow in your app
2. extractUrl() scans the email HTML for the link matching buttonText: 'Sign in'
3. Returns the full URL including the one-time token
4. Playwright test follows it directly
The Result
The test exercises the same code path your users hit. If the email template breaks, the test fails. If the token isn't correctly embedded in the URL, you catch it immediately.
Approval Workflow Emails
The Problem
Multi-step approval flows send several emails (request submitted, approval required, confirmation). Hard to test end-to-end without a real inbox. Mocks can't validate the email sequence or link extraction from multiple emails.
The MailFork Approach
1. Scope each extraction call to subject or buttonText
2. Use Promise.all to extract Approve/Reject URLs from the same email simultaneously
3. Follow both links to validate the outcome
The Result
Full workflow coverage from submission to outcome, end-to-end. Test the entire approval sequence, validate email ordering, and confirm both approval and rejection paths work.
CI/CD Pipelines — Parallel Test Runs
The Problem
Parallel CI workers share an inbox. Emails from one worker contaminate another. Building complex per-worker isolation adds test overhead and requires custom cleanup logic.
The MailFork Approach
1. Each CI worker creates its own ephemeral alias: ci+run-{Date.now()}-{Math.random()}
2. All SDK calls pass the aliasTag — completely isolated
3. Aliases auto-expire after 1 hour; no cleanup code needed
The Result
4 workers, 4 aliases, zero cross-contamination. Works out of the box with GitHub Actions, GitLab CI, CircleCI, and any platform. No custom setup, no per-worker databases, no manual cleanup.
Email Content Regression Testing
The Problem
A template change silently breaks the plain-text version. HTML looks fine in your browser but Outlook users get a blank email. Mocks validate that a template was rendered; they can't validate that the output is actually readable in email clients.
The MailFork Approach
1. MailFork stores both HTML and plain-text parts from the real MIME structure
2. Assert on both: email.body.text and email.body.html
3. Check attachments: email.attachments[0].filename
The Result
A one-line template typo fails the test before it reaches production. Your tests validate the actual email content that reaches users, not just that the send function was called.
Invite Acceptance Flows
The Problem
User invites send a link with a short-lived token. Hard to test without capturing the real email. One-time-use tokens, expiry windows, and redirect behavior are easy to break and hard to mock correctly.
The MailFork Approach
1. Trigger the invite flow in your app
2. extractUrl() with buttonText: 'Accept Invite' grabs the token-bearing URL
3. Test follows it to complete the flow
4. (Optional) Use an ephemeral alias to isolate the test
The Result
Invite token expiry, one-time-use enforcement, and redirect behavior — all covered in the same test. You validate that the real token in the real email works correctly.
See these in action
Check out the SDK Patterns guide for code examples of each use case.