{"id":13098,"library":"e2e-mailbox","title":"E2E Mailbox","description":"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.","status":"active","version":"1.1.7","language":"javascript","source_language":"en","source_url":"https://github.com/allynsweet/E2E-Mailbox","tags":["javascript","e2e","email","testing","guerrillamail","integration","typescript"],"install":[{"cmd":"npm install e2e-mailbox","lang":"bash","label":"npm"},{"cmd":"yarn add e2e-mailbox","lang":"bash","label":"yarn"},{"cmd":"pnpm add e2e-mailbox","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const E2EMailbox = require('e2e-mailbox');","symbol":"E2EMailbox","correct":"import E2EMailbox from 'e2e-mailbox';"},{"note":"Use the named export E2EMailboxProvider enum to explicitly choose between 'DEVELOPER' (default) or 'GUERRILLA' mail providers in the constructor.","symbol":"E2EMailboxProvider","correct":"import E2EMailbox, { E2EMailboxProvider } from 'e2e-mailbox';"},{"note":"Import types for `MailboxEmail` and other related interfaces to leverage TypeScript's type checking for email objects returned by the API methods.","symbol":"MailboxEmail","correct":"import { type MailboxEmail } from 'e2e-mailbox';"}],"quickstart":{"code":"import E2EMailbox from 'e2e-mailbox';\n\nasync function runEmailTest() {\n  // Initialize the mailbox; by default, it uses DeveloperMail API.\n  // You can explicitly choose GuerrillaMail: new E2EMailbox('GUERRILLA');\n  const mailbox = new E2EMailbox();\n  console.log('Step 1: Generating a new temporary email address...');\n  const emailAddress = await mailbox.createEmailAddress();\n  console.log(`Generated email: ${emailAddress}`);\n\n  // --- In a real E2E test, your application would now send an email to this address ---\n  // Example: await myApp.registerUser(emailAddress, 'password123');\n  // --- For this quickstart, we'll assume an email with a specific subject is sent ---\n\n  const expectedSubject = 'Welcome Aboard!'; // Replace with the actual subject line your system sends\n  console.log(`Step 2: Waiting for an email with subject \"${expectedSubject}\" (max 90s)...`);\n  const foundEmail = await mailbox.waitForEmail(expectedSubject, 90);\n\n  if (foundEmail) {\n    console.log('Step 3: Email found!');\n    console.log(`Subject: ${foundEmail.mail_subject}`);\n    console.log(`Excerpt: ${foundEmail.mail_excerpt?.substring(0, 100)}...`);\n\n    const links = mailbox.extractLinksFromEmail(foundEmail);\n    if (links.length > 0) {\n      console.log('Step 4: Extracted links from email:');\n      links.forEach(link => console.log(`  - ${link}`));\n      const confirmUrl = links.find(url => url.includes('/confirm-account'));\n      if (confirmUrl) {\n        console.log(`Confirmation URL found: ${confirmUrl}`);\n        // --- In your E2E test, you would now navigate to 'confirmUrl' ---\n      }\n    } else {\n      console.log('No links found in the email body.');\n    }\n\n    // Clean up: delete the email after processing\n    console.log(`Step 5: Deleting email with ID: ${foundEmail.mail_id}...`);\n    await mailbox.deleteEmailById(foundEmail.mail_id);\n    console.log('Email deleted.');\n  } else {\n    console.error(`Error: Email with subject \"${expectedSubject}\" not received within the timeout.`);\n  }\n}\n\nrunEmailTest().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Email 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: Email not found after timeout."},{"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!'); }`","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'extractLinksFromEmail')"},{"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.","cause":"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.","error":"Request failed with status code 429"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}