Capture the email outside the mailbox UI, retrieve it programmatically, then test its content and behavior in Cypress. Use a local SMTP capture server when your test app can route mail to it; use an API-accessible test inbox when the app sends through a real provider or cannot be redirected. Cypress explicitly calls checking email through a consumer mailbox UI an anti-pattern and recommends an API or direct server access instead (Cypress FAQ).
Choose how Cypress will retrieve the email
| Approach | Use it when | Trade-off |
|---|---|---|
| Local SMTP capture | Your test environment can direct outbound mail to a temporary SMTP server. | You control capture locally, but must run the server, retain messages, and coordinate retrieval with Cypress tasks. |
| Hosted test inbox and API | The application sends through a third-party provider, or SMTP cannot be stubbed. | You avoid maintaining a local capture server, but depend on an external service and must protect API credentials. |
| Temporary-email provider or plugin | You need disposable addresses and an integration compatible with your provider. | Verify provider reliability, data handling, maintenance, and compatibility with your Cypress version. Cypress lists email integrations as community extensions, not as endorsed products (Cypress plugin directory). |
In either approach, let Cypress trigger the user workflow, retrieve the resulting message through a server-side task or inbox API, and assert against that message. Do not assume delivery is instantaneous; wait for the specific email instead of relying on a fixed delay.
Capture email with a local SMTP server
A local capture server is useful when the app can be configured to send mail to a test SMTP endpoint. The Cypress tutorial demonstrates running a temporary SMTP server in the plugin process, storing received messages by recipient, and exposing tasks to fetch or clear them (Cypress tutorial, May 11, 2021). The tutorial uses older plugin-file conventions; adapt the pattern to your current Cypress configuration rather than copying its file paths unchanged.
Register capture and retrieval tasks
Run the SMTP server in the Cypress Node-side setup. When a message arrives, retain its recipient, sender, subject, plain-text body, and HTML body in a store keyed by recipient. Register tasks such as getLastEmail and resetEmails: the first returns the latest matching message, and the second clears stored messages for a recipient. Configure the application’s test mail settings to deliver to this local server.
Keep the task boundary intentional: Cypress browser code should ask the Node process for captured mail rather than trying to connect directly to SMTP. Use a unique recipient for each test, or clear that recipient’s messages before triggering mail, so an earlier email cannot satisfy a later assertion.
Trigger the email and assert its contents
- Reset the capture store for the test recipient.
- Visit the application and perform the action that sends mail, such as registration or requesting a password reset.
- Ask the Cypress task for the message addressed to that recipient.
- Assert the relevant headers and both bodies if the application sends both text and HTML alternatives.
The Cypress tutorial shows extracting a confirmation code from the text body, then extending the captured record to retain both body and html. It also correlates the registration request with the generated email, which helps ensure the message belongs to the workflow under test.
Rank #2
Load the HTML into the Cypress browser when behavior matters
For rendered-content checks, write the captured HTML into the test document, assert that key content is visible, click the confirmation link, and verify the resulting application route or state. This checks the template’s DOM and interaction in a browser; it does not prove that the message looks identical in Gmail, Outlook, Apple Mail, or every other mail client.
Use an API-accessible test inbox when mail leaves the app
When the application uses an external email provider or cannot route mail to local SMTP, send a test message to an inbox service and search for it through that service’s API. Mailosaur is one documented example; it is not the only possible provider. Its Cypress flow triggers an email, searches for the matching message, then exposes message properties and HTML for ordinary Cypress assertions (Mailosaur Cypress email testing guide).
Rank #3
Mailosaur setup outline
- Follow the current Mailosaur Cypress quickstart to install
cypress-mailosaurand import it from Cypress support setup. - Configure the API key using the documented environment-variable option,
CYPRESS_MAILOSAUR_API_KEY, rather than committing a secret to source control. - Send the application’s test email to an address under the test domain associated with your Mailosaur server. The guide describes wildcard addresses and an optional helper for generating unique addresses.
- Use
cy.mailosaurGetMessage()to find the message using recipient, sender, subject, or body criteria, then assert on the returned fields and HTML body.
Mailosaur documents that its message helper waits for delivery. Check package and service compatibility against your project’s current Cypress version before adopting the setup.
What to assert in an HTML email test
- Routing and metadata: recipient, sender, display name, and subject where they matter to the product.
- Plain-text alternative: expected copy, verification code, and fallback content if the application sends a text body.
- HTML body: essential message text, markup, verification code, and primary call to action.
- Link correctness: inspect the expected
href; when the workflow warrants it, render the message, click the link, and verify the destination route or resulting state. - Rendered content and accessibility: check key visible content at relevant viewport sizes and consider accessibility and visual checks for important templates.
Keep assertions tied to user-visible requirements. A brittle test of incidental markup can fail after harmless template refactoring, while a check for the required copy, destination, or code protects the actual behavior.
Rank #4
Make email tests reliable
Wait for the right message
The local SMTP example assumes the server has received the message by the time Cypress calls the retrieval task. If that assumption is flaky, retry retrieval until a matching message arrives or a reasonable test timeout is reached. Prefer retrying a condition over an arbitrary fixed sleep. With a hosted inbox, use its message-search helper’s wait behavior and narrow the search with a unique recipient or other identifying details.
Prevent stale or mismatched messages
- Use a fresh recipient or unique message identifier for each test where possible.
- Clear captured local mail before triggering the workflow.
- Search by enough fields to identify the expected message, not merely any recent email.
- Assert that the returned recipient and subject match the scenario before checking the body.
Keep the test environment deliberate
Choose local capture when the purpose is to verify that the application generated the right email without depending on delivery infrastructure. Choose an API inbox when the integration with the actual mail provider is part of what the test needs to exercise. Those are different test boundaries: a local capture test does not prove third-party delivery, and an inbox API test adds an external dependency.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
Common failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| No message returned by a local task | The app is not targeting the capture server, or retrieval ran before SMTP delivery. | Check test SMTP host and port configuration; retry the retrieval task until the message appears or the test timeout expires. |
| A test passes using an old email | Captured messages were not reset, or the inbox search is too broad. | Clear the local store, use a unique recipient, and narrow hosted-inbox search criteria. |
| The HTML assertion fails but the text assertion passes | The app may not be generating the expected HTML part, or the test is reading the wrong message field. | Confirm the captured message includes an HTML body and assert against that field; test the text alternative separately. |
| Hosted inbox authentication fails | The API key is missing, invalid, or unavailable to the Cypress process. | Set the documented environment variable in the test environment and keep the key out of source control. |
| Rendered email looks correct in Cypress but differs in a mailbox | The Cypress browser is not a simulation of every mail client’s rendering engine. | Treat browser checks as DOM and interaction tests; use appropriate email-client rendering or visual checks for cross-client presentation. |
Or skip the browser setup
If the test you need is a screenshot of a page or rendered content, ScreenshotNeo offers a screenshot API and MCP server. It is not an email inbox or a replacement for retrieving and asserting on email messages. For a browser-rendered page, one GET request returns an image or PDF; see the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed; its MCP server lets AI agents take screenshots; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Can Cypress verify the email was sent without opening a mailbox website?
Yes. Retrieve the message through a local SMTP capture task or a test-inbox API and assert on the resulting message.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Does loading email HTML in Cypress prove it will look the same in every email client?
No. It checks browser-rendered content and interaction, not identical rendering across mailbox clients.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
