Registry / testing / e2e-mailbox

e2e-mailbox

JSON →
library1.1.7jsnpmunverified

E2E Mailbox is a fully-typed TypeScript library designed for integrating email notification testing into end-to-end test suites. It enables developers to programmatically create temporary email addresses, wait for specific emails to arrive based on subject lines, and extract content like URLs or pins from email bodies for verification. The library currently leverages free, third-party services—DeveloperMail and GuerrillaMail—offering an automatic fallback mechanism to enhance reliability. Key use cases include verifying account registration emails, password reset flows, and ensuring correct email content after specific user actions within an application. It is currently at version 1.1.7 and appears to be actively maintained, providing a robust solution for automating tests that rely on email communication without manual intervention. Its primary differentiator is its focus on e2e testing with a resilient, multi-provider approach to temporary email addresses.

npm install e2e-mailbox
INSTALL
IMPORT
SIG · E2E-MAILBOX
E
e2e-mailbox
testingjavascriptv1.1.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

E2EMailbox
import E2EMailbox from 'e2e-mailbox';
const E2EMailbox = require('e2e-mailbox');
E2EMailbox is a default export. The library is fully typed and primarily designed for ESM consumption, though CJS may work it's not the recommended or type-safe approach.
E2EMailboxProvider
import E2EMailbox, { E2EMailboxProvider } from 'e2e-mailbox';
Use the named export E2EMailboxProvider enum to explicitly choose between 'DEVELOPER' (default) or 'GUERRILLA' mail providers in the constructor.
MailboxEmail
import { type MailboxEmail } from 'e2e-mailbox';
Import types for `MailboxEmail` and other related interfaces to leverage TypeScript's type checking for email objects returned by the API methods.

This quickstart demonstrates the core functionality of E2E Mailbox: creating a temporary email address, polling for an email by its subject line, extracting links from the email body, and finally deleting the email for cleanup. It simulates a common E2E testing scenario for email-dependent features like user registration and account confirmation.

import E2EMailbox from 'e2e-mailbox'; async function runEmailTest() { // Initialize the mailbox; by default, it uses DeveloperMail API. // You can explicitly choose GuerrillaMail: new E2EMailbox('GUERRILLA'); const mailbox = new E2EMailbox(); console.log('Step 1: Generating a new temporary email address...'); const emailAddress = await mailbox.createEmailAddress(); console.log(`Generated email: ${emailAddress}`); // --- In a real E2E test, your application would now send an email to this address --- // Example: await myApp.registerUser(emailAddress, 'password123'); // --- For this quickstart, we'll assume an email with a specific subject is sent --- const expectedSubject = 'Welcome Aboard!'; // Replace with the actual subject line your system sends console.log(`Step 2: Waiting for an email with subject "${expectedSubject}" (max 90s)...`); const foundEmail = await mailbox.waitForEmail(expectedSubject, 90); if (foundEmail) { console.log('Step 3: Email found!'); console.log(`Subject: ${foundEmail.mail_subject}`); console.log(`Excerpt: ${foundEmail.mail_excerpt?.substring(0, 100)}...`); const links = mailbox.extractLinksFromEmail(foundEmail); if (links.length > 0) { console.log('Step 4: Extracted links from email:'); links.forEach(link => console.log(` - ${link}`)); const confirmUrl = links.find(url => url.includes('/confirm-account')); if (confirmUrl) { console.log(`Confirmation URL found: ${confirmUrl}`); // --- In your E2E test, you would now navigate to 'confirmUrl' --- } } else { console.log('No links found in the email body.'); } // Clean up: delete the email after processing console.log(`Step 5: Deleting email with ID: ${foundEmail.mail_id}...`); await mailbox.deleteEmailById(foundEmail.mail_id); console.log('Email deleted.'); } else { console.error(`Error: Email with subject "${expectedSubject}" not received within the timeout.`); } } runEmailTest().catch(console.error);
Debug
Known issues
gotchaThis library relies on free, public temporary email services (DeveloperMail, GuerrillaMail). These services may experience intermittent downtime, rate limiting, or delays in email delivery, which can lead to flaky E2E tests. While the library implements an automatic fallback, persistent issues with both providers can disrupt testing.
fix
Implement robust retry mechanisms in your tests. Monitor the status of DeveloperMail and GuerrillaMail. For critical applications, consider using a self-hosted email testing solution or a paid service with dedicated APIs and SLAs.
affects: >=1.0.0
gotchaEmail delivery is not instantaneous. The `waitForEmail` method polls for a specified duration, but emails might arrive after the timeout or be delayed by the third-party services, leading to test failures if the timeout is too short.
fix
Increase the `timeoutInSeconds` parameter for `mailbox.waitForEmail()` if tests are consistently failing due to emails not being found. Add a small, fixed delay before initiating `waitForEmail()` to give the email system a head start.
affects: >=1.0.0
gotchaThe `extractLinksFromEmail` method parses the email body to find URLs. This parsing can be brittle if the email HTML structure changes significantly or if links are dynamically generated in a way that makes them difficult to extract reliably.
fix
Ensure the email templates used by your application are stable. For critical links (e.g., confirmation links), consider designing the email content to embed unique identifiers or specific patterns that make extraction more robust than generic link parsing. Test `extractLinksFromEmail` against various email templates.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Email not found after timeout.
The `waitForEmail` method timed out because the expected email did not arrive or its subject line did not exactly match the provided string within the given duration.
fix
Verify that your application is indeed sending the email to the generated address. Double-check the exact subject line for any typos or leading/trailing spaces. Increase the `timeoutInSeconds` parameter in `mailbox.waitForEmail()` to allow more time for delivery.
TypeError: Cannot read properties of undefined (reading 'extractLinksFromEmail')
This error occurs when `mailbox.waitForEmail()` returns `null` (meaning no email was found), and your code then attempts to call `extractLinksFromEmail` on the `null` result.
fix
Always add a null-check after `await mailbox.waitForEmail()` to ensure an email object was successfully returned before attempting to process it. For example: `const foundEmail = await mailbox.waitForEmail(...); if (foundEmail) { ... } else { console.error('Email not found!'); }`
Request failed with status code 429
This status code indicates 'Too Many Requests', meaning you have hit the rate limits of the underlying temporary email provider (DeveloperMail or GuerrillaMail) with excessive API calls in a short period.
fix
Introduce delays between your E2E tests that perform email operations. Restructure your test suite to reuse email addresses for multiple tests where possible, or reduce the number of parallel tests that heavily rely on email generation and polling.
Upgrade
Version history
1.1.7latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
40 hits · last 30 days
node
34
OpenAI (training)
1
Resources
e2e-mailbox — npm install e2e-mailbox · libregistry